instances

type AddOptions struct {
	// Instance is the instance to add
	Instance Instance
	// RuntimeType is the type of runtime to use
	RuntimeType string
	// WorkspaceConfig is the workspace-level configuration from .kaiden/workspace.json (optional, can be nil)
	WorkspaceConfig *workspace.WorkspaceConfiguration
	// Project is an optional custom project identifier to override auto-detection
	Project string
	// Agent is an optional agent name for loading agent-specific configuration
	Agent string
	// Model is an optional model ID to configure for the agent
	Model string
}

type Instance interface {
	// GetID returns the unique identifier for the instance.
	GetID() string
	// GetName returns the human-readable name for the instance.
	GetName() string
	// GetSourceDir returns the source directory.
	// The path is always absolute.
	GetSourceDir() string
	// GetConfigDir returns the configuration directory.
	// The path is always absolute.
	GetConfigDir() string
	// IsAccessible checks if both source and config directories are accessible
	IsAccessible() bool
	// GetRuntimeType returns the runtime type for this instance
	GetRuntimeType() string
	// GetRuntimeData returns the complete runtime data for this instance
	GetRuntimeData() RuntimeData
	// GetProject returns the project identifier for this instance
	GetProject() string
	// GetAgent returns the agent name for this instance
	GetAgent() string
	// GetModel returns the model ID for this instance (empty if not set)
	GetModel() string
	// Dump returns the serializable data of the instance
	Dump() InstanceData
}

type InstanceData struct {
	// ID is the unique identifier for the instance
	ID string `json:"id"`
	// Name is the human-readable name for the instance
	Name string `json:"name"`
	// Paths contains the source and configuration directories
	Paths InstancePaths `json:"paths"`
	// Runtime contains runtime-specific information
	Runtime RuntimeData `json:"runtime"`
	// Project is the project identifier for grouping instances.
	// Format depends on workspace type:
	// - Git repository with remote: normalized remote repository identifier (remote URL with .git suffix
	//   and credentials stripped, e.g., "https://github.com/user/repo")
	// - Git repository without remote: repository root directory as absolute path (e.g., "/home/user/my-local-repo")
	// - Non-git directory: workspace source directory as absolute path (e.g., "/home/user/my-workspace")
	// When the workspace is in a subdirectory of the repository, a relative-path suffix is appended
	// (e.g., "https://github.com/user/repo/pkg/subdir" or "/home/user/my-local-repo/pkg/subdir")
	Project string `json:"project"`
	// Agent is the agent name for this instance (e.g., "claude", "goose").
	// This is used to load agent-specific configuration and determine which agent command to run.
	Agent string `json:"agent"`
	// Model is the model ID configured for the agent (e.g., "claude-sonnet-4-20250514").
	// Empty string means no model was explicitly specified.
	Model string `json:"model,omitempty"`
}

type InstanceFactory func(InstanceData) (Instance, error)

type InstancePaths struct {
	// Source is the directory containing source files (absolute path)
	Source string `json:"source"`
	// Configuration is the directory containing workspace configuration (absolute path)
	Configuration string `json:"configuration"`
}

type Manager interface {
	// Add registers a new instance with a runtime and returns the instance with its generated ID
	Add(ctx context.Context, opts AddOptions) (Instance, error)
	// Start starts a runtime instance by ID
	Start(ctx context.Context, id string) error
	// Stop stops a runtime instance by ID
	Stop(ctx context.Context, id string) error
	// Terminal starts an interactive terminal session, auto-starting the instance if needed
	Terminal(ctx context.Context, id string, command []string) error
	// List returns all registered instances
	List() ([]Instance, error)
	// Get retrieves a specific instance by name or ID
	Get(nameOrID string) (Instance, error)
	// Delete unregisters an instance by ID
	Delete(ctx context.Context, id string) error
	// Reconcile removes instances with inaccessible directories
	// Returns the list of removed instance IDs
	Reconcile() ([]string, error)
	// GetDashboardURL returns the dashboard URL for a workspace instance by name or ID.
	// Returns ErrInstanceNotFound if the workspace does not exist.
	// Returns ErrDashboardNotSupported if the runtime does not implement the Dashboard interface.
	GetDashboardURL(ctx context.Context, nameOrID string) (string, error)
	// RegisterRuntime registers a runtime with the manager's registry
	RegisterRuntime(rt runtime.Runtime) error
	// RegisterAgent registers an agent with the manager's registry
	RegisterAgent(name string, agent agent.Agent) error
	// RegisterSecretService registers a secret service with the manager's registry
	RegisterSecretService(service secretservice.SecretService) error
}

type NewInstanceParams struct {
	// SourceDir is the directory containing source files
	SourceDir string
	// ConfigDir is the directory containing workspace configuration
	ConfigDir string
	// Name is the human-readable name for the instance (optional, will be generated if empty)
	Name string
}

type RuntimeData struct {
	// Type is the runtime type (e.g., "fake", "podman", "docker")
	Type string `json:"type"`
	// InstanceID is the runtime-assigned instance identifier
	InstanceID string `json:"instance_id"`
	// State is the current runtime state (e.g., "running", "stopped")
	State api.WorkspaceState `json:"state"`
	// Info contains runtime-specific metadata
	Info map[string]string `json:"info"`
}