provider

type AgentOnlyProvider interface {
	// AgentOnly is a marker method; it does nothing.
	AgentOnly()
}

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 AgentRuntime interface {
	// DefaultDependencies returns the dependencies that install this agent's CLI.
	DefaultDependencies() []string

	// NetworkHosts returns the hosts this agent needs to reach.
	NetworkHosts() []string

	// CredentialGrant returns the STATIC grant name this agent needs — not a
	// credential-store lookup. "" means the agent has no static grant and none
	// should be unioned in. Store lookups stay in the verb-path
	// GetCredentialName funcs; conflating the two puts empty or wrong grant
	// names into the grants list.
	CredentialGrant() string
}

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

type ContainerProvider interface {
	// 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)
}

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 {
	ProxyProvider
	GrantProvider
	ContainerProvider
	ImpliedDepsProvider
}

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 GrantProvider interface {
	Grant(ctx context.Context) (*Credential, error)
}

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

type InitFileProvider interface {
	// ContainerInitFiles returns a map of absolute container paths to file
	// contents. Paths must be under containerHome. The moat-init.sh script
	// writes each entry to disk with mode 0600 before executing the user's
	// command.
	ContainerInitFiles(cred *Credential, containerHome string) map[string]string
}

type JoinOpts struct {
	Continue bool
	Resume   string
	Prompt   string
}

type JoinableAgent interface {
	// JoinCommand returns the in-container command to launch a joined session.
	JoinCommand(opts JoinOpts) ([]string, error)

	// IdentifiesAs reports whether a run whose recorded Agent field is `agent`
	// was created by this provider. This absorbs the difference between the
	// default provider name ("claude") and an explicit moat.yaml agent value
	// ("claude-code").
	IdentifiesAs(agent string) bool
}

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

type LocalMCPServerConfig struct {
	Command string
	Args    []string
	Env     map[string]string
	Cwd     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

	// LocalMCPServers are MCP servers that run as child processes inside the
	// container. These are defined under agent-specific sections in moat.yaml
	// (e.g., claude.mcp, codex.mcp, gemini.mcp).
	LocalMCPServers map[string]LocalMCPServerConfig

	// SubscriptionType and RateLimitTier override the values written to Claude
	// Code's .credentials.json (from moat.yaml claude.subscription_type /
	// claude.rate_limit_tier). Empty means "no override" — the provider falls
	// back to the imported value or a default. Claude-specific; ignored by
	// other agents.
	SubscriptionType string
	RateLimitTier    string

	// ScopeAnthropicKeyToShell stages a BASH_ENV file that exports
	// ANTHROPIC_API_KEY to shell commands only, instead of placing it in the
	// container environment. Set when a run holds both the "claude" (OAuth) and
	// "anthropic" (API key) grants, where a container-wide key would take
	// precedence over Claude Code's OAuth login and move the session onto API
	// billing. Claude-specific; ignored by other agents.
	ScopeAnthropicKeyToShell bool

	// ScopeOpenAIKeyToShell keeps an OpenAI API-key placeholder out of the
	// Codex process when subscription and API-key grants coexist.
	ScopeOpenAIKeyToShell bool

	// CodexRequireApproval keeps Codex's own approval prompts and sandbox
	// enabled instead of moat's default of turning both off (the container is
	// already the isolation boundary, and Codex's sandbox blocks the network
	// the moat proxy provides). Set from `moat codex --noyolo`.
	// Codex-specific; ignored by other agents.
	CodexRequireApproval bool

	// CopilotModel, CopilotContext, and CopilotReasoningEffort strip the
	// corresponding keys (model, contextTier, effortLevel) from the Copilot
	// settings.json staged into the container, because the value is pinned by
	// moat.yaml copilot.* or a CLI flag. Empty means "no override".
	// Copilot-specific; ignored by other agents.
	CopilotModel           string
	CopilotContext         string
	CopilotReasoningEffort string

	// PiModelCatalogSync lets Pi make startup network calls (it omits
	// PI_OFFLINE). Set when the run holds the lunaroute grant: LunaRoute's
	// Pi extension fetches its model catalog at startup, and under PI_OFFLINE
	// a fresh container would list no LunaRoute models.
	// Pi-specific; ignored by other agents.
	PiModelCatalogSync bool
}

type ProxyConfigurer = credential.ProxyConfigurer

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

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

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
}