runtime

type AgentLister interface {
	// ListAgents returns the names of all agents supported by this runtime.
	// Returns an empty slice if no agents are configured.
	ListAgents() ([]string, error)
}

type CreateParams struct {
	// Name is the human-readable name for the instance.
	Name string

	// SourcePath is the absolute path to the workspace source directory.
	SourcePath string

	// WorkspaceConfig is the workspace configuration (optional, can be nil if no configuration exists).
	WorkspaceConfig *workspace.WorkspaceConfiguration

	// Agent is the agent name for loading agent-specific configuration (required, cannot be empty).
	Agent string

	// AgentSettings contains the agent settings files to embed into the agent user's
	// home directory in the workspace image. Keys are relative file paths using
	// forward slashes (e.g., ".claude/settings.json"), values are file contents.
	// This map can be nil or empty if no default settings are configured.
	AgentSettings map[string][]byte
}

type Registry interface {
	// Register adds a runtime to the registry.
	// Returns an error if a runtime with the same type is already registered.
	Register(runtime Runtime) error

	// Get retrieves a runtime by type.
	// Returns ErrRuntimeNotFound if the runtime type is not registered.
	Get(runtimeType string) (Runtime, error)

	// List returns all registered runtime types.
	List() []string
}

type Runtime interface {
	// Type returns the runtime type identifier (e.g., "podman", "docker", "process", "fake").
	Type() string

	// WorkspaceSourcesPath returns the path where sources will be mounted inside the workspace.
	// This is a constant for each runtime type and doesn't require an instance to exist.
	WorkspaceSourcesPath() string

	// Create creates a new runtime instance without starting it.
	// Returns RuntimeInfo with the assigned instance ID and initial state.
	Create(ctx context.Context, params CreateParams) (RuntimeInfo, error)

	// Start starts a previously created runtime instance.
	// Returns updated RuntimeInfo with running state.
	Start(ctx context.Context, id string) (RuntimeInfo, error)

	// Stop stops a running runtime instance without removing it.
	// The instance can be started again later.
	Stop(ctx context.Context, id string) error

	// Remove removes a runtime instance and cleans up all associated resources.
	// The instance must be stopped before removal.
	Remove(ctx context.Context, id string) error

	// Info retrieves current information about a runtime instance.
	Info(ctx context.Context, id string) (RuntimeInfo, error)
}

type RuntimeInfo struct {
	// ID is the runtime-assigned instance identifier.
	ID string

	// State is the current runtime state.
	State api.WorkspaceState

	// Info contains runtime-specific metadata as key-value pairs.
	// Examples: container_id, pid, created_at, network addresses.
	Info map[string]string
}

type StorageAware interface {
	// Initialize is called during registration with the runtime's private storage directory.
	// The directory is created before this method is called and is guaranteed to exist.
	// The path will be: REGISTRY_STORAGE/runtimeType
	//
	// Runtimes should store the directory path and use it for persisting private data.
	// This method is called exactly once during registration, before the runtime is available for use.
	Initialize(storageDir string) error
}

type Terminal interface {
	// Terminal starts an interactive terminal session inside a running instance.
	// The command is executed with stdin/stdout/stderr connected directly to the user's terminal.
	// Returns an error if the instance is not running or command execution fails.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout
	//   - instanceID: The runtime instance identifier
	//   - agent: The agent name for loading agent-specific configuration
	//   - command: The command to execute (e.g., ["bash"], ["claude-code", "--debug"]).
	//              If empty, the runtime will use the agent's configured terminal command.
	Terminal(ctx context.Context, instanceID string, agent string, command []string) error
}