agent

type Adapter interface {

	// CreateSession creates a new session in the agent and returns the
	// platform view. The adapter generates or translates the ID.
	CreateSession(ctx context.Context, userID, workspaceID, title string) (*session.Session, error)

	// GetSession returns the current state of one session.
	GetSession(ctx context.Context, userID, workspaceID, sessionID string) (*session.Session, error)

	// ListSessions returns the platform view of all sessions on the
	// workspace, ordered by recency.
	ListSessions(ctx context.Context, userID, workspaceID string) ([]session.Session, error)

	// CountMessages returns the session's total message count — the
	// ground truth the session_index rebuild converges to (#1481, the
	// #754 fold-in). On the interface (not a handlers-local assertion)
	// per the #1127 lesson: production adapters are wrapped, and
	// seam assertions fail silently through wrappers. Adapters whose
	// harness offers no cheap count source implement a bounded history
	// walk; a vanished session surfaces the typed gone error so the
	// #1479 reconciliation machinery classifies it.
	CountMessages(ctx context.Context, userID, workspaceID, sessionID string) (int, error)

	// RenameSession updates a session's title.
	RenameSession(ctx context.Context, userID, workspaceID, sessionID, title string) error

	// DeleteSession removes a session from the agent. Subsequent Get
	// calls return a not-found error.
	DeleteSession(ctx context.Context, userID, workspaceID, sessionID string) error

	// Send delivers a user message synchronously and returns the
	// assistant's completed response. Streaming callers use Stream
	// instead; Send is for request-response callers (MCP, SDK).
	Send(ctx context.Context, userID, workspaceID, sessionID, text string, opts session.SendOpts) (*session.Message, error)

	// SendAsync delivers a user message without waiting for the
	// assistant response. The returned message ID lets the caller
	// correlate via Stream or GetHistory. Use this for long-running
	// tasks where the caller will poll.
	SendAsync(ctx context.Context, userID, workspaceID, sessionID, text string, opts session.SendOpts) (messageID string, err error)

	// Abort stops any in-flight work on the session. The abort is
	// non-destructive: queued user input survives and runs on the
	// next wake (design 0049 §3 — loss of revoke is accepted).
	Abort(ctx context.Context, userID, workspaceID, sessionID string) error

	// SetSessionModel sets the session's default model. Under agents
	// whose async-delivery endpoint strips per-prompt model overrides
	// (opencode V2, verified 2026-08-29), this is the ONLY way a
	// message's model selection reaches the agent — the delivery path
	// applies it to the session before admission. On the interface (not
	// a local assertion) per the #1127 lesson: production adapters are
	// wrapped, and seam assertions fail silently through wrappers.
	// Adapters without session-model support return nil (no-op) rather
	// than failing the delivery.
	SetSessionModel(ctx context.Context, userID, workspaceID, sessionID string, m *session.ModelRef) error

	// VerifyDelivery reports whether a user message whose text equals
	// `text` was persisted in the agent's transcript at or after
	// `since`. delivered=true proves the agent holds it;
	// definitive=true with delivered=false proves absence (a re-send
	// cannot duplicate); both false means inconclusive — recheck, never
	// re-send. This is the #987 ambiguity oracle and the #1119
	// promotion oracle.
	//
	// Promoted from a handlers-local type assertion to the interface by
	// the 2026-08-29 incident: production adapters are WRAPPED
	// (systemnotices.Wrap embeds this interface), and the handlers'
	// deliveryVerifier assertion silently failed against the wrapper —
	// every verification returned inconclusive without touching the
	// network, breaking all V2 delivery. The wrapper was the "second
	// consumer" the old comment said would fund this promotion.
	// Adapters without transcript verification return the inconclusive
	// shape (false, false, nil).
	VerifyDelivery(ctx context.Context, userID, workspaceID, sessionID, text string, since time.Time) (delivered, definitive bool, err error)

	// GetHistory returns the session transcript in platform shape.
	// The adapter drops agent-specific parts (e.g. opencode's patch
	// part) and produces FileChange parts from git diff where the
	// agent reported file changes.
	GetHistory(ctx context.Context, userID, workspaceID, sessionID string) ([]session.Message, error)

	// GetHistoryPage returns the NEWEST `limit` messages of a session,
	// oldest-first within the page, using the agent's native pagination
	// when it has one (#971: fetching+decoding the full transcript to
	// slice a page was ~95% of session-load latency on large sessions).
	// Implementations without native pagination may return the full
	// transcript; callers slice.
	GetHistoryPage(ctx context.Context, userID, workspaceID, sessionID string, limit int) ([]session.Message, error)

	// Stream subscribes to the session's event stream, translating
	// agent-specific events to session.Event values. The channel
	// closes when the context is canceled or the agent ends the
	// stream. Unknown/malformed events are dropped silently.
	// Connection-level errors (scanner failure) are emitted as
	// session.EventError events before the channel closes.
	Stream(ctx context.Context, userID, workspaceID, sessionID string) (<-chan session.Event, error)

	// ListPending returns the currently-blocking InputRequests on a
	// session (questions or permissions). The adapter unifies the
	// agent's question/permission shapes into session.InputRequest.
	//
	// Contract: a non-nil error means the pending set is UNKNOWN
	// (agent unreachable, endpoint error) — never treat it as an
	// authoritative empty. A 404-not-implemented endpoint yields an
	// authoritative empty with a nil error. Callers that broadcast
	// snapshots (the SSE input snapshot) must mark failed fetches as
	// non-authoritative so they cannot wipe live pending prompts.
	ListPending(ctx context.Context, userID, workspaceID, sessionID string) ([]session.InputRequest, error)

	// RejectInput dismisses a pending InputRequest without an answer
	// (#1313): questions go to the agent's reject endpoint, permissions
	// reply "reject". The harness terminates the tool call with its
	// dismissal result — the model sees the ask was dismissed.
	RejectInput(ctx context.Context, userID, workspaceID, requestID string) error

	// AnswerQuestion answers a pending question with the user's option
	// selections / custom text in the question-reply schema
	// ({answers: string[][]}).
	AnswerQuestion(ctx context.Context, userID, workspaceID, requestID string, answers [][]string) error

	// ReplyPermission answers a pending permission with the decision
	// ("once" / "always" / "reject") and the user's optional context
	// message; both fields ride the agent's permission-reply schema.
	ReplyPermission(ctx context.Context, userID, workspaceID, requestID, reply, message string) error

	// ListAvailableModels returns the catalog of models the agent can
	// select, including context/output limits for "context: X% used"
	// display. The adapter converts agent-side cost/relay/provider
	// data into the platform ModelInfo shape.
	ListAvailableModels(ctx context.Context, userID, workspaceID string) ([]session.ModelInfo, error)

	// ContextUsageFromEvent translates one raw agent SSE event into the
	// session's live context occupancy. ok=false when the event carries
	// no usage signal (most events don't); callers skip silently — that
	// is normal traffic, not drift. When ok=true, sessionID is non-empty
	// and usage is non-nil (implementations must uphold this; the SSE
	// event path dereferences both). The adapter owns both the wire
	// shapes and the semantic mapping to ContextUsage.Used; platform
	// code never inspects the raw bytes.
	ContextUsageFromEvent(eventType string, rawData string) (sessionID string, usage *session.ContextUsage, ok bool)

	// ClientEventsFromEvent translates one raw agent SSE event into
	// zero or more CONTRACT events (pkg/session) for client
	// consumption — the US-65.8 bridge. Clients render contract shapes
	// only; agent wire names, envelopes, and part shapes stay behind
	// this seam. nil for events carrying no client-facing signal (the
	// majority — implementations must type-check before parsing so the
	// streaming hot path never pays a parse for them).
	ClientEventsFromEvent(eventType string, rawData string) []session.Event

	// RetryFromEvent decodes an agent backoff/retry notification into
	// the platform retry shape. Retry detail is UI-shaped and rides the
	// platform session.status SSE event rather than the contract.
	RetryFromEvent(eventType string, rawData string) (sessionID string, retry *ClientRetryStatus, ok bool)

	// SetModel changes the session's active model. Subsequent Send
	// calls use the new model.
	SetModel(ctx context.Context, userID, workspaceID, sessionID string, model session.ModelRef) error

	// Capabilities reports the optional agent behaviors the client
	// may render affordances for (steer, queue, rewind, fork, stash,
	// diff, reasoning). The set is per-adapter, not per-session.
	Capabilities() []session.Capability

	// FormatProviderConfig renders the supplied providers in the
	// agent's native config format. Returns nil if the agent has no
	// provider config concept for these credentials.
	FormatProviderConfig(providers []LLMProviderData) ([]byte, error)

	// ValidateCredentials checks whether the supplied raw config
	// (already agent-formatted) is structurally valid. Returns nil
	// on success, an error describing the validation failure
	// otherwise. Used at bind time to reject malformed credentials
	// before they reach the workspace.
	ValidateCredentials(rawConfig []byte) (*CredentialCheckResult, error)
}

type AdminPromptChange struct {
	Text string
}

type AgentConfigInput struct {
	// Providers updates the LLM provider map. Formatted is the
	// agent-rendered provider JSON — the agent's formatter is the
	// only thing that knows the shape (e.g. opencode's
	// {"provider": {...}} struct). The writer passes the bytes
	// through verbatim.
	//
	// A non-nil pointer with nil/empty Formatted bytes clears the
	// provider source.
	Providers *AgentProvidersChange

	// Model updates the default model selection. Empty string
	// (ModelSelection("")) clears the model source.
	Model *ModelSelection

	// Relay updates the relay state. A non-nil pointer with empty URL
	// clears the relay source (distinct from nil = leave unchanged).
	Relay *RelayState

	// MCPServers updates the MCP server list. A non-nil pointer with
	// an empty Servers slice clears the MCP source.
	MCPServers *MCPServerChange

	// AdminPrompt updates the platform-level system prompt rendered into
	// the agent's build prompt (replace semantics: the new Text fully
	// supersedes the prior source, side-car-loaded or rendered). A
	// non-nil pointer with empty Text clears the prompt source
	// (distinct from nil = leave unchanged).
	//
	// At bootstrap the writer loads this source from the side-car file
	// (WithAdminPromptPath — the materialize staging contract); this
	// field is the runtime update path so a caller can revise the
	// prompt without recreating the writer. It does NOT watch files.
	AdminPrompt *AdminPromptChange

	// AllowedDirs updates the glob patterns auto-approved as the
	// agent's external-directory allow rules. A non-nil pointer with an
	// empty Dirs slice clears the source. Same bootstrap/runtime split
	// as AdminPrompt: construction may load from the side-car file
	// (WithAllowedDirsPath); this field updates thereafter.
	AllowedDirs *AllowedDirsChange
}

type AgentConfigWriter interface {
	Apply(in AgentConfigInput) (restartRequired bool, err error)
	HasRelay() bool
}

type AgentProvidersChange struct {
	// Formatted is the agent-rendered provider JSON. For opencode,
	// this is the output of FormatOpenCodeConfig — a struct
	// {"provider": {...}} containing the agent's exact provider map.
	Formatted []byte
}

type AgentRuntime interface {
	Type() AgentType
	ValidateCredentials(rawConfig []byte) (*CredentialCheckResult, error)
	FormatProviderConfig(providers []LLMProviderData) ([]byte, error)
}

type AgentType string

type AllowedDirsChange struct {
	Dirs []string
}

type ClientRetryStatus struct {
	Attempt int
	Message string
	NextAt  int64
	Action  string
}

type CredentialCheckResult struct {
	State   CredentialState `json:"state"`
	Agent   AgentType       `json:"agent"`
	Message string          `json:"message,omitempty"`
}

type CredentialState string

type InputResolution struct {
	RequestID string `json:"request_id"`
	SessionID string `json:"session_id"`
	Reply     string `json:"reply,omitempty"`
}

type LLMModelConfig struct {
	ID           string `json:"id"`
	Label        string `json:"label,omitempty"`
	ContextLimit int    `json:"contextLimit,omitempty"`
	OutputLimit  int    `json:"outputLimit,omitempty"`
	Attachment   *bool  `json:"attachment,omitempty"`
}

type LLMProviderData struct {
	Kind       string           `json:"kind"`
	Slug       string           `json:"slug"`
	APIKey     string           `json:"apiKey"`
	BaseURL    string           `json:"baseURL,omitempty"`
	Models     []LLMModelConfig `json:"models,omitempty"`
	Default    string           `json:"default,omitempty"`
	SmallModel string           `json:"smallModel,omitempty"`
}

type MCPServerChange struct {
	Servers []MCPServerEntry
}

type MCPServerEntry struct {
	Name      string
	Transport string // http, sse, or stdio
	URL       string
	Command   string
	Args      []string
	TimeoutMs int
	Env       map[string]string
	Headers   map[string]string
}

type ModelSelection string

type PermissionRequest struct {
	ID            string                 `json:"id"`
	SessionID     string                 `json:"session_id"`
	RootSessionID string                 `json:"root_session_id,omitempty"`
	Permission    string                 `json:"permission"`
	Patterns      []string               `json:"patterns"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`
	Always        []string               `json:"always,omitempty"`
	Tool          *ToolRef               `json:"tool,omitempty"`
}

type QuestionInfo struct {
	Question string           `json:"question"`
	Header   string           `json:"header"`
	Options  []QuestionOption `json:"options"`
	Multiple bool             `json:"multiple"`
	Custom   bool             `json:"custom"`
}

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description"`
}

type QuestionRequest struct {
	ID            string         `json:"id"`
	SessionID     string         `json:"session_id"`
	RootSessionID string         `json:"root_session_id,omitempty"`
	Questions     []QuestionInfo `json:"questions"`
	Tool          *ToolRef       `json:"tool,omitempty"`
}

type RelayModel struct {
	ID           string
	Name         string
	ContextLimit int
	OutputLimit  int
}

type RelayState struct {
	URL    string
	Models []RelayModel
}

type SessionUsage struct {
	SessionID     string
	ModelID       string
	ProviderID    string
	InputTokens   int64
	OutputTokens  int64
	CostUSD       float64
	CostMalformed bool
}

type ToolRef struct {
	MessageID string `json:"message_id"`
	CallID    string `json:"call_id"`
}

type V2Delivery string

type V2PromptResponse struct {
	AdmittedSeq int    `json:"admittedSeq"`
	ID          string `json:"id"`
	SessionID   string `json:"sessionID"`
}