agentadapters

type Activity struct {
	ID              string
	Type            string
	Status          string
	Kind            string
	Title           string
	Detail          string
	ArtifactPreview string
}

type Adapter struct {
	ID             string
	Name           string
	Command        string
	Args           []string
	CandidatePaths []string
	// Embedded means Hecate serves this adapter in-process. Command and
	// CandidatePaths then identify the provider CLI used by the embedded
	// adapter. TestProcess* exists only for hermetic protocol fixtures; it is not
	// a supported product runtime mode.
	Embedded                  bool
	TestProcessCommand        string
	TestProcessArgs           []string
	TestProcessCandidatePaths []string
	AgentVersion              VersionProbe
	LaunchSuffixArgs          []string
	LaunchModel               LaunchModelConfig
	LaunchOptions             []LaunchSelectConfig
	Kind                      string
	Description               string
	CostMode                  string
	DocsURL                   string
	SupportedRange            string
	SupportsAuthenticate      bool
	SupportsLogout            bool
	// NativeSessionScope describes whether a stored ACP session id can be
	// restored after the adapter runtime exits. Process-scoped adapters require
	// an explicit fresh-session replacement after restart; the zero value fails
	// closed when session/load fails.
	NativeSessionScope NativeSessionScope
	CredentialModes    []CredentialMode
	Capabilities       []Capability
}

type AmbiguousOptionError struct {
	Decision ApprovalDecision
	Options  []ApprovalOption
}

type Approval struct {
	ID             string                 `json:"id"`
	SessionID      string                 `json:"session_id"`
	AdapterID      string                 `json:"adapter_id"`
	Workspace      string                 `json:"workspace,omitempty"`
	ToolKind       string                 `json:"tool_kind"`
	ToolName       string                 `json:"tool_name,omitempty"`
	Status         ApprovalStatus         `json:"status"`
	ACPPayload     json.RawMessage        `json:"acp_payload,omitempty"`
	ACPOptions     []ApprovalOption       `json:"acp_options"`
	ScopeChoices   []ApprovalScope        `json:"scope_choices,omitempty"`
	SelectedOption string                 `json:"selected_option,omitempty"`
	Scope          ApprovalScope          `json:"scope,omitempty"`
	Decision       ApprovalDecision       `json:"decision,omitempty"`
	Path           ApprovalResolutionPath `json:"path,omitempty"`
	DecisionNote   string                 `json:"decision_note,omitempty"`
	CreatedAt      time.Time              `json:"created_at"`
	ResolvedAt     *time.Time             `json:"resolved_at,omitempty"`
	ExpiresAt      time.Time              `json:"expires_at"`
}

type ApprovalCoordinator struct {
	// contains filtered or unexported fields
}

type ApprovalDecision string

type ApprovalMode string

type ApprovalOption struct {
	OptionID string `json:"option_id"`
	Kind     string `json:"kind"`
	Name     string `json:"name"`
}

type ApprovalResolutionPath string

type ApprovalRetentionStore interface {
	ApprovalStore

	// PruneApprovals deletes resolved (non-pending) approval rows
	// older than maxAge OR beyond maxCount, whichever fires.
	// Pending rows are never pruned. Returns total deleted.
	PruneApprovals(ctx context.Context, now time.Time, maxAge time.Duration, maxCount int) (int64, error)

	// PruneExpiredGrants removes grants whose ExpiresAt is in the
	// past. Live grants (no expiry, or future expiry) are never
	// touched. Returns total deleted.
	PruneExpiredGrants(ctx context.Context, now time.Time) (int64, error)

	// ReconcilePending sweeps any pending approval rows from a prior
	// process and marks them status=timed_out, path=startup_reconcile.
	// Process-local waiters can't be resurrected; callers must invoke
	// this at startup before serving requests. Returns rows
	// reconciled.
	ReconcilePending(ctx context.Context, now time.Time) (int64, error)

	// Prune implements retention.Pruner — one call that runs both
	// the resolved-approval sweep (subject to maxAge / maxCount)
	// and the expired-grant sweep (grants honor only ExpiresAt;
	// maxAge / maxCount don't apply). Returns the sum so operators
	// see total rows removed by this subsystem in one number.
	// Captures `now := time.Now().UTC()` internally; the
	// per-deletion `now`-tolerant methods stay on the interface for
	// tests and ad-hoc callers.
	Prune(ctx context.Context, maxAge time.Duration, maxCount int) (int, error)
}

type ApprovalScope string

type ApprovalStatus string

type ApprovalStore interface {
	// CreateApproval persists a pending approval and returns the row
	// with its assigned ID + timestamps filled in.
	CreateApproval(ctx context.Context, a Approval) (Approval, error)

	// ResolveApproval transitions a pending approval to a terminal
	// status. Returns the updated row. Returns ErrApprovalNotFound
	// when id is unknown and ErrApprovalAlreadyResolved when the row
	// is already terminal — the second writer always loses the race.
	ResolveApproval(ctx context.Context, id string, status ApprovalStatus, decision ApprovalDecision, selectedOption string, scope ApprovalScope, path ApprovalResolutionPath, note string, resolvedAt time.Time) (Approval, error)

	// GetApproval fetches an approval by id.
	GetApproval(ctx context.Context, id string) (Approval, error)

	// ListApprovals returns approvals for a session, oldest-first.
	// status="" returns all statuses; otherwise filters.
	ListApprovals(ctx context.Context, sessionID string, status ApprovalStatus) ([]Approval, error)

	// CreateGrant persists an operator-authored "always allow / always
	// deny" grant. Used by the coordinator when scope > once.
	CreateGrant(ctx context.Context, g Grant) (Grant, error)

	// ListGrants returns grants matching the filter, newest-first.
	// Expired grants (ExpiresAt <= now) are excluded.
	ListGrants(ctx context.Context, filter GrantFilter, now time.Time) ([]Grant, error)

	// DeleteGrant removes a grant by id. Returns ErrApprovalNotFound
	// when the id is unknown so the HTTP layer can surface 404.
	DeleteGrant(ctx context.Context, id string) error

	// FindMatchingGrant returns the most-specific live grant for the
	// given (sessionID, workspace, adapterID, toolKind) tuple, or
	// (Grant{}, false). Lookup walks scopes session → workspace_tool →
	// adapter_tool, returning the first match. Expired grants are
	// ignored. The returned grant carries the operator's decision.
	FindMatchingGrant(ctx context.Context, sessionID, workspace, adapterID, toolKind string, now time.Time) (Grant, bool, error)
}

type AuthenticateResult struct {
	AdapterID  string `json:"adapter_id"`
	Status     string `json:"status"`
	MethodID   string `json:"method_id"`
	Path       string `json:"path,omitempty"`
	DurationMS int64  `json:"duration_ms"`
}

type AvailableCommandsUpdate struct {
	SessionID string
	AdapterID string
	Commands  []agentcontrols.Command
	// contains filtered or unexported fields
}

type Capability struct {
	ID          string
	Name        string
	Description string
	Status      string
}

type CoordinatorHooks struct {
	OnRequested func(approval Approval)
	OnResolved  func(approval Approval, durationMS int64)
	OnTimedOut  func(approval Approval, durationMS int64)
	// OnGrantCreated fires after a successful CreateGrant inside the
	// coordinator's resolve path (i.e. when the operator's decision
	// scope is broader than `once`). Used to drive the
	// `approval.grants_active` UpDownCounter; nil-safe.
	OnGrantCreated func(grant Grant)
	// OnGrantDeleted fires after a successful DeleteGrant. Symmetric
	// with OnGrantCreated; nil-safe.
	OnGrantDeleted func()
}

type CoordinatorOptions struct {
	Mode    ApprovalMode
	Timeout time.Duration
	Store   ApprovalStore
	Logger  *slog.Logger
	// NowFunc is used by tests; defaults to time.Now.UTC.
	NowFunc func() time.Time
	// IDFunc generates approval ids; defaults to ULID-shaped hex.
	IDFunc func() string
	// Hooks are optional callbacks for telemetry. Zero values are no-ops.
	Hooks CoordinatorHooks
}

type CredentialMode struct {
	ID            string
	Name          string
	Description   string
	RemoteAllowed bool
	EnvKeys       []string
}

type Grant struct {
	ID        string           `json:"id"`
	Scope     ApprovalScope    `json:"scope"`
	AdapterID string           `json:"adapter_id"`
	ToolKind  string           `json:"tool_kind"`
	Workspace string           `json:"workspace,omitempty"`
	SessionID string           `json:"session_id,omitempty"`
	Decision  ApprovalDecision `json:"decision"`
	GrantedBy string           `json:"granted_by,omitempty"`
	GrantedAt time.Time        `json:"granted_at"`
	ExpiresAt *time.Time       `json:"expires_at,omitempty"`
}

type GrantFilter struct {
	AdapterID string
	Scope     ApprovalScope
	ToolKind  string
}

type LaunchModel struct {
	ID          string
	Name        string
	Description string
	Default     bool
}

type LaunchModelConfig struct {
	ConfigID       string
	ArgTemplate    []string
	ListArgs       []string
	FallbackModels []LaunchModel
}

type LaunchSelectConfig struct {
	ConfigID         string
	Name             string
	Description      string
	Category         string
	Default          string
	UnsetValue       string
	UnsetName        string
	UnsetDescription string
	ArgTemplate      []string
	Options          []LaunchSelectOption
}

type LaunchSelectOption struct {
	ID          string
	Name        string
	Description string
}

type LogoutResult struct {
	AdapterID  string `json:"adapter_id"`
	Status     string `json:"status"`
	Path       string `json:"path,omitempty"`
	DurationMS int64  `json:"duration_ms"`
}

type LookupFunc func(file string) (string, error)

type MemoryApprovalStore struct {
	// contains filtered or unexported fields
}

type NativeSessionReplacement struct {
	PreviousNativeSessionID string
	NativeSessionID         string
	Reason                  string
}

type NativeSessionScope string

type PrepareSessionRequest struct {
	SessionID               string
	AdapterID               string
	Workspace               string
	PreviousNativeSessionID string
	ConfigOptions           []agentcontrols.ConfigOption
	MCPServers              []types.MCPServerConfig
}

type PrepareSessionResult struct {
	Adapter                Adapter
	DriverKind             string
	NativeSessionID        string
	AgentInfo              *agentcontrols.ImplementationInfo
	SessionStarted         bool
	SessionResumed         bool
	SessionRecovery        string
	ConfigOptions          []agentcontrols.ConfigOption
	AvailableCommands      []agentcontrols.Command
	AvailableCommandsKnown bool
}

type ProbeAgentInfo = agentcontrols.ImplementationInfo

type ProbeAuthMethod struct {
	ID          string `json:"id"`
	Kind        string `json:"kind"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
}

type ProbeResult struct {
	AdapterID            string            `json:"adapter_id"`
	Status               string            `json:"status"`
	Stage                string            `json:"stage"`
	Path                 string            `json:"path,omitempty"`
	Error                string            `json:"error,omitempty"`
	Stderr               string            `json:"stderr,omitempty"`
	Hint                 string            `json:"hint,omitempty"`
	AgentInfo            *ProbeAgentInfo   `json:"agent_info,omitempty"`
	CapabilitiesKnown    bool              `json:"capabilities_known,omitempty"`
	SupportsAuthenticate bool              `json:"supports_authenticate"`
	SupportsLogout       bool              `json:"supports_logout"`
	SupportsLoadSession  bool              `json:"supports_load_session"`
	AuthMethods          []ProbeAuthMethod `json:"auth_methods,omitempty"`
	DurationMS           int64             `json:"duration_ms"`
}

type PromptFile struct {
	Filename  string
	MediaType string
	SizeBytes int64
	SHA256    string
	Data      []byte
}

type PromptInput struct {
	Text  string
	Files []PromptFile
}

type RecordingContext struct {
	SessionID string
	AdapterID string
	Workspace string
}

type ResolveRequest struct {
	Decision       ApprovalDecision `json:"decision"`
	Scope          ApprovalScope    `json:"scope"`
	SelectedOption string           `json:"selected_option,omitempty"`
	Note           string           `json:"note,omitempty"`
	GrantedBy      string           `json:"granted_by,omitempty"`
}

type RunRequest struct {
	SessionID               string
	AdapterID               string
	Workspace               string
	PreviousNativeSessionID string
	Prompt                  PromptInput
	ConfigOptions           []agentcontrols.ConfigOption
	MCPServers              []types.MCPServerConfig
	Timeout                 time.Duration
	MaxOutputBytes          int64
	OnOutput                func(string)
	OnActivity              func(Activity)
	// OnTerminalActivity is bound to terminals created by this turn and may be
	// called after Run returns, until OnTerminalClosed reports that terminal's
	// authoritative settlement. Callers must return promptly, keep it safe for
	// concurrent late delivery, and bind it to the originating durable message
	// rather than mutable current-turn state.
	OnTerminalActivity func(Activity)
	// OnTerminalClosed runs exactly once for each successfully-created terminal,
	// after its final OnTerminalActivity callback. A session-close deadline makes
	// the emitted cancellation authoritative: no transcript callbacks occur for
	// that terminal after OnTerminalClosed returns. Callers must return promptly.
	OnTerminalClosed func(terminalID string)
	// AllowNativeSessionReplacement is explicit host authority to replace a
	// provider-native conversation that the adapter proves is missing. The
	// zero value fails closed. OnNativeSessionReplaced must durably persist the
	// new native ID before Hecate sends the prompt again.
	AllowNativeSessionReplacement bool
	OnNativeSessionReplaced       func(NativeSessionReplacement) error
}

type RunResult struct {
	Adapter                Adapter
	DriverKind             string
	NativeSessionID        string
	AgentInfo              *agentcontrols.ImplementationInfo
	StopReason             string
	SessionStarted         bool
	SessionResumed         bool
	SessionRecovery        string
	Output                 string
	RawOutput              string
	ExitCode               int
	StartedAt              time.Time
	CompletedAt            time.Time
	DiffStat               string
	Diff                   string
	Usage                  Usage
	ConfigOptions          []agentcontrols.ConfigOption
	AvailableCommands      []agentcontrols.Command
	AvailableCommandsKnown bool
	// contains filtered or unexported fields
}

type Runner interface {
	PrepareSession(context.Context, PrepareSessionRequest) (PrepareSessionResult, error)
	Run(context.Context, RunRequest) (RunResult, error)
	SetSessionConfigOption(context.Context, SetSessionConfigOptionRequest) (SetSessionConfigOptionResult, error)
	CloseSession(context.Context, string) error
	DeleteSession(context.Context, string) error
	Shutdown(context.Context) error
}

type SQLiteApprovalStore struct {
	// contains filtered or unexported fields
}

type SessionManager struct {
	// contains filtered or unexported fields
}

type SetSessionConfigOptionRequest struct {
	SessionID string
	ConfigID  string
	Value     string
	BoolValue *bool
}

type SetSessionConfigOptionResult struct {
	ConfigOptions          []agentcontrols.ConfigOption
	AvailableCommands      []agentcontrols.Command
	AvailableCommandsKnown bool
}

type SetupCommandStatus struct {
	Available      bool   `json:"available"`
	Command        string `json:"command,omitempty"`
	ExecutablePath string `json:"executable_path,omitempty"`
}

type Status struct {
	Adapter
	Available            bool
	Status               string
	Path                 string
	Error                string
	AdapterVersion       string
	AgentVersion         string
	VersionOutsideRange  bool
	AuthStatus           string
	AuthError            string
	RemoteCredentialMode string
	RemoteCredentialOK   bool
	RemoteCredentialHint string
	ClaudeCodeCLI        SetupCommandStatus
}

type Usage struct {
	ContextSize          int
	ContextUsed          int
	ReportedCostAmount   string
	ReportedCostCurrency string
}

type VersionProbe struct {
	Command        string
	Args           []string
	CandidatePaths []string
}