provider

type AgentProvider interface {
	CredentialProvider

	// PrepareContainer sets up staging directories and config files.
	PrepareContainer(ctx context.Context, opts PrepareOpts) (*ContainerConfig, error)

	// RegisterCLI adds provider-specific commands to the root command.
	RegisterCLI(root *cobra.Command)
}

type ContainerConfig struct {
	Env        []string
	Mounts     []MountConfig
	StagingDir string // Temporary directory containing config files (for later cleanup tracking)
	Cleanup    func()
}

type Credential struct {
	Provider  string            `json:"provider"`
	Token     string            `json:"token"`
	Scopes    []string          `json:"scopes,omitempty"`
	ExpiresAt time.Time         `json:"expires_at,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

type CredentialProvider interface {
	// Name returns the provider identifier (e.g., "github", "claude").
	Name() string

	// Grant acquires credentials interactively or from environment.
	Grant(ctx context.Context) (*Credential, error)

	// ConfigureProxy sets up proxy headers for this credential.
	ConfigureProxy(p ProxyConfigurer, cred *Credential)

	// ContainerEnv returns environment variables to set in the container.
	ContainerEnv(cred *Credential) []string

	// ContainerMounts returns mounts needed for this credential.
	// Also returns an optional cleanup path that should be passed to Cleanup()
	// when the run ends.
	ContainerMounts(cred *Credential, containerHome string) ([]MountConfig, string, error)

	// Cleanup is called when the run ends to clean up any resources.
	Cleanup(cleanupPath string)

	// ImpliedDependencies returns dependencies implied by this provider.
	// For example, github implies ["gh", "git"].
	ImpliedDependencies() []string
}

type DescribableProvider interface {
	Description() string
	Source() string // "builtin" or "custom"
}

type EndpointProvider interface {
	CredentialProvider

	// RegisterEndpoints registers HTTP handlers on the proxy mux.
	RegisterEndpoints(mux *http.ServeMux, cred *Credential)
}

type GrantError struct {
	Provider string
	Cause    error
	Hint     string
}

type LegacyCredential interface {
	GetProvider() string
	GetToken() string
	GetScopes() []string
	GetExpiresAt() time.Time
	GetCreatedAt() time.Time
	GetMetadata() map[string]string
}

type MCPServerConfig struct {
	URL     string
	Headers map[string]string
}

type MountConfig = container.MountConfig

type PrepareOpts struct {
	Credential     *Credential
	ContainerHome  string
	MCPServers     map[string]MCPServerConfig
	HostConfig     map[string]interface{}
	RuntimeContext string // Rendered markdown context for agent instruction file
}

type ProxyConfigurer = credential.ProxyConfigurer

type RefreshableProvider interface {
	CanRefresh(cred *Credential) bool
	RefreshInterval() time.Duration
	Refresh(ctx context.Context, p ProxyConfigurer, cred *Credential) (*Credential, error)
}

type ResponseTransformer = credential.ResponseTransformer

type RunStoppedContext struct {
	Workspace string
	StartedAt time.Time
}

type RunStoppedHook interface {
	// OnRunStopped is called after the container exits and logs are captured.
	// It receives run context and returns metadata key-value pairs to persist.
	// Returned metadata is stored in the run's metadata.json under "provider_meta".
	OnRunStopped(ctx RunStoppedContext) map[string]string
}