agentapi

type Account struct {
	SignedIn bool   `json:"signed_in"`
	Login    string `json:"login,omitempty"`
	Host     string `json:"host,omitempty"`
	// Source is one of the Account* constants; "" while signed out.
	Source string `json:"source,omitempty"`
	// EnvVar names the service environment variable whose token takes
	// precedence over a stored sign-in; its value is never reported.
	EnvVar string `json:"env_var,omitempty"`
	// Message is the runtime's sanitized status or error text.
	Message string `json:"message,omitempty"`
	// Stored is false after a SignIn the runtime could not keep: it lasts
	// until the runtime stops.
	Stored *bool `json:"stored,omitempty"`
}

type AccountManager interface {
	Account(ctx context.Context) (Account, error)
	// SignIn validates and stores token as the runtime's sign-in. The token
	// goes to the runtime only; it is never logged or kept.
	SignIn(ctx context.Context, token string) (Account, error)
	// SignOut removes the stored sign-in in effect.
	SignOut(ctx context.Context) (Account, error)
}

type Activity struct {
	// Plan is true only after this turn's explicit native implementation approval.
	Plan bool `json:"plan,omitempty"`
	// Intent is what the main agent says it is doing, "" when it says
	// nothing.
	Intent string `json:"intent,omitempty"`
	// Retry is set while the turn's current model call is being retried.
	Retry *Retry `json:"retry,omitempty"`
	// Phase is what the conversation's agents, subagents included, wait on
	// now; nil while no model call is in flight and no tool runs. Between
	// turns it holds only subagents that outlived the turn and compaction.
	Phase *Phase `json:"phase,omitempty"`
}

type AgentSelector interface {
	// SelectAgent selects the custom agent id for the next turns, or the
	// default agent when id is "". The caller never selects during a turn.
	// ErrAgentUnavailable means id cannot be selected.
	SelectAgent(ctx context.Context, id string) error
}

type Answer struct {
	Plan     *PlanAnswer `json:"plan,omitempty"`
	Decision string      `json:"decision,omitempty"`
	Answers  [][]string  `json:"answers,omitempty"`
	Reject   bool        `json:"reject,omitempty"`
	// Cancel dismisses an elicitation without declining it.
	Cancel bool `json:"cancel,omitempty"`
	// Auto marks an answer UAM gave on its own (yolo), not one a person chose.
	// It is internal: a client can never set it.
	Auto bool `json:"-"`
}

type AsideAnswer struct {
	Text      string `json:"text"`
	Truncated bool   `json:"truncated,omitempty"`
}

type AsideAsker interface {
	AskAside(ctx context.Context, question string) (*AsideAnswer, error)
}

type AssistedPermissionSetter interface {
	SetAssistedPermissions(ctx context.Context, approvalModel string) error
	// AssistedPermissionsOn reads the runtime's mode back, for when a change
	// failed or timed out: true when assisted review is on, false when off.
	AssistedPermissionsOn(ctx context.Context) (bool, error)
}

type AssistedReview struct {
	Recommendation string `json:"recommendation"`
	Model          string `json:"model,omitempty"`
	Reason         string `json:"reason,omitempty"`
}

type Attachment struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name"`
	MIME string `json:"mime"`
	Size int64  `json:"size,omitempty"`
	// NotNative is set on a document the provider did not pass to the model
	// as a document: the agent got its path, to read with its own tools.
	NotNative bool `json:"not_native,omitempty"`
	// SHA256 is the hex digest of the content, when the provider's record
	// has it; the web service matches it to its stored copy. It is never
	// sent to browsers.
	SHA256 string `json:"-"`
}

type AutopilotObjective struct {
	ID                int64    `json:"id"`
	Objective         string   `json:"objective"`
	Status            string   `json:"status"`
	TurnCount         int64    `json:"turn_count"`
	PauseReason       string   `json:"pause_reason,omitempty"`
	CompletionSummary string   `json:"completion_summary,omitempty"`
	CreditsUsed       *float64 `json:"credits_used,omitempty"`
	CreditLimit       *float64 `json:"credit_limit,omitempty"`
}

type BackgroundTask struct {
	ID          string    `json:"id"`
	Description string    `json:"description,omitempty"`
	Command     string    `json:"command"`
	Status      string    `json:"status"`
	StartedAt   time.Time `json:"started_at,omitzero"`
	EndedAt     time.Time `json:"ended_at,omitzero"`
}

type BackgroundTaskController interface {
	CancelBackgroundTask(context.Context, string) (BackgroundTasks, error)
}

type BackgroundTasks struct {
	Known bool             `json:"known"`
	Tasks []BackgroundTask `json:"tasks"`
}

type Blob struct {
	Name string
	MIME string
	Data []byte
	Path string
}

type CLIRelease struct {
	// Installed is the version installed, which the next start runs.
	Installed string
	// Latest is the newest stable release; Newer is true when it is newer
	// than Installed. The adapter compares them: version schemes are its own.
	Latest string
	Newer  bool
	// Manual says why the runtime cannot be updated from here, such as an
	// install the adapter does not manage; empty when it can.
	Manual string
}

type CLIUpdater interface {
	// CLIRelease reads the installed and newest release. With an error,
	// Installed may still be set when only the newest could not be read.
	CLIRelease(ctx context.Context) (CLIRelease, error)
	// UpdateCLI installs version, a Latest that CLIRelease reported. A
	// release the SDK refuses fails with ErrCLIIncompatible. A running
	// runtime keeps serving, conversations opened meanwhile included; only
	// the start of a new one waits while the files are replaced. ctx bounds
	// the whole update.
	UpdateCLI(ctx context.Context, version string) error
	// RestartCLI stops a running runtime whose release was replaced (see
	// CLIOutdated), so the next use starts the installed one. New starts
	// wait meanwhile, and quiesce is called first to close idle
	// conversations; its error, or anything still running on the runtime
	// (ErrCLIBusy), leaves it running for a later call. With no such runtime
	// it does nothing and returns nil.
	RestartCLI(ctx context.Context, quiesce func() error) error
	// CLIOutdated reports whether a running runtime runs a release replaced
	// on disk since it started, by UpdateCLI or by an install made outside
	// uam; RestartCLI then restarts it like an update's.
	CLIOutdated() bool
	// RestartRuntime stops the running runtime whatever runs on it, so the
	// next use starts a new one with fresh connections. A running turn ends
	// as cancelled with reason as its note; an idle conversation ends and
	// reopens on its next use. New starts wait meanwhile. With no runtime
	// running it does nothing and returns nil.
	RestartRuntime(ctx context.Context, reason string) error
	// RuntimeStalls counts the turns the running runtime's model requests
	// stalled twice in since it started; zero after a restart.
	RuntimeStalls() int
}

type Capabilities struct {
	// Plan supports native plan mode and explicit review in the composer.
	Plan        bool `json:"plan,omitempty"`
	Cancel      bool `json:"cancel"`
	Permissions bool `json:"permissions"`
	Questions   bool `json:"questions"`
	// SessionDiff is true when the provider records per-conversation file
	// changes (Conversation.Diff). Workspace Git diffs are separate.
	SessionDiff bool `json:"session_diff"`
	// SessionDiffNeedsTracking limits the default native scope to Tasks that
	// opted into capture before their first turn. Explicit session reads still
	// report the provider's current availability for legacy conversations.
	SessionDiffNeedsTracking bool `json:"-"`
	History                  bool `json:"history"`
	// Fork copies a recorded owner-turn prefix without resending messages.
	Fork bool `json:"fork,omitempty"`
	// Rewind discards an open conversation's recorded suffix natively.
	Rewind bool `json:"rewind,omitempty"`
	// ContextSize is the per-Task context-tier exception to provider parity.
	ContextSize bool `json:"context_size"`
	// ContextBreakdown is an optional on-demand ContextReader, never a stream.
	ContextBreakdown bool `json:"context_breakdown,omitempty"`
	// Usage is the second exception: the provider implements QuotaReporter
	// and reports each conversation's AI units through EventUsage.
	Usage bool `json:"usage"`
	// UsageMetrics advertises an on-demand native conversation reader, separate
	// from account quotas and the combined EventUsage total.
	UsageMetrics bool `json:"usage_metrics,omitempty"`
	// Aside is true when the provider's conversations implement AsideAsker.
	Aside bool `json:"aside,omitempty"`
	// Titles is true when the provider implements Titler and its
	// conversations implement SetTitle, so a chosen model can title a Task.
	Titles bool `json:"titles"`
	// Import is a capability-gated exception to provider parity: the provider lists
	// the conversations recorded for a folder and tells when another client
	// holds one open (Importer).
	Import         bool `json:"import"`
	ExecutionModes bool `json:"execution_modes,omitempty"`
	// HostTools is true when the provider registers OpenRequest.Tools in its
	// conversations and implements UtilityRunner.
	HostTools bool `json:"host_tools,omitempty"`
	// Account is true when the provider implements AccountManager.
	Account bool `json:"account,omitempty"`
	// DeviceSignIn is true when the provider implements DeviceSignInManager.
	DeviceSignIn bool `json:"device_sign_in,omitempty"`
	// MCP is true when the provider implements MCPConfigurer and its
	// conversations implement MCPController.
	MCP bool `json:"mcp,omitempty"`
	// CLIUpdate is true when the provider implements CLIUpdater.
	CLIUpdate bool `json:"cli_update,omitempty"`
	// SubagentModels is true when the provider implements SubagentModelUser.
	SubagentModels bool `json:"subagent_models,omitempty"`
	// GitHubMCP is true when the provider implements GitHubMCPUser.
	GitHubMCP bool `json:"github_mcp,omitempty"`
	// AssistedPermissions is true when the provider honours
	// OpenRequest.AssistedApprovalModel, its conversations implement
	// AssistedPermissionSetter, and its permission requests carry the
	// review in Interaction.Assisted.
	AssistedPermissions bool `json:"assisted_permissions,omitempty"`
	// AssistedUnavailable says why a provider that has assisted
	// permissions withdrew them: the running runtime refused the mode.
	AssistedUnavailable string `json:"assisted_unavailable,omitempty"`
	// CustomAgents is true when the provider implements
	// ConfigurationDiscoverer, applies OpenRequest.Agent and its
	// conversations implement AgentSelector.
	CustomAgents bool `json:"custom_agents,omitempty"`
}

type Command struct {
	Name            string          `json:"name"`
	Description     string          `json:"description"`
	Kind            string          `json:"kind"`
	InputHint       string          `json:"input_hint"`
	Aliases         []string        `json:"aliases,omitempty"`
	AllowDuringTurn bool            `json:"allow_during_turn,omitempty"`
	DisabledReason  string          `json:"disabled_reason,omitempty"`
	InputChoices    []CommandOption `json:"input_choices,omitempty"`
	InputRequired   bool            `json:"input_required,omitempty"`
}

type CommandExecutor interface {
	ExecuteCommand(context.Context, string, Prompt) (*CommandResult, error)
}

type CommandOption struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Group       string `json:"group,omitempty"`
}

type CommandResult struct {
	Kind         string          `json:"kind"`
	Text         string          `json:"text,omitempty"`
	Markdown     bool            `json:"markdown,omitempty"`
	PrefillInput string          `json:"prefill_input,omitempty"`
	Title        string          `json:"title,omitempty"`
	Command      string          `json:"command,omitempty"`
	Options      []CommandOption `json:"options,omitempty"`
	Action       string          `json:"action,omitempty"`
}

type CompletionBlocker struct {
	Kind      string `json:"kind"`
	Reason    string `json:"reason"`
	Resumable bool   `json:"resumable"`
}

type CompletionDecision string

type ConfigurationCatalog struct {
	Definitions []ConfigurationDefinition
	Warnings    []string
}

type ConfigurationDefinition struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	DisplayName   string `json:"display_name,omitempty"`
	Description   string `json:"description,omitempty"`
	Source        string `json:"source"`
	Path          string `json:"path,omitempty"`
	Enabled       *bool  `json:"enabled,omitempty"`
	UserInvocable *bool  `json:"user_invocable,omitempty"`
}

type ConfigurationDiscoverer interface {
	DiscoverSkills(ctx context.Context, projectPaths, skillDirectories []string) (ConfigurationCatalog, error)
	DiscoverAgents(ctx context.Context, projectPaths []string) (ConfigurationCatalog, error)
	DiscoverHooks(ctx context.Context, projectPaths []string) (ConfigurationCatalog, error)
	DiscoverInstructions(ctx context.Context, projectPaths []string) (ConfigurationCatalog, error)
}

type Context struct {
	Used   int64 `json:"used"`
	Limit  int64 `json:"limit"`
	Prompt int64 `json:"prompt,omitempty"`
	Cached int64 `json:"cached,omitempty"`
}

type ContextAttribution struct {
	Model               string            `json:"model"`
	ModelSource         string            `json:"model_source"`
	TotalTokens         int64             `json:"total_tokens"`
	Limit               int64             `json:"limit"`
	PromptTokenLimit    int64             `json:"prompt_token_limit"`
	CompactionThreshold int64             `json:"compaction_threshold"`
	BufferTokens        int64             `json:"buffer_tokens"`
	Compactions         int64             `json:"compactions"`
	Categories          ContextCategories `json:"categories"`
	Entries             []ContextSource   `json:"entries"`
	Truncated           bool              `json:"truncated,omitempty"`
}

type ContextCategories struct {
	SystemPrompt       int64 `json:"system_prompt"`
	CustomInstructions int64 `json:"custom_instructions"`
	SystemTools        int64 `json:"system_tools"`
	MCPTools           int64 `json:"mcp_tools"`
	Messages           int64 `json:"messages"`
	FreeSpace          int64 `json:"free_space"`
	Buffer             int64 `json:"buffer"`
}

type ContextInfo struct {
	Model                string `json:"model"`
	TotalTokens          int64  `json:"total_tokens"`
	Limit                int64  `json:"limit"`
	PromptTokenLimit     int64  `json:"prompt_token_limit"`
	CompactionThreshold  int64  `json:"compaction_threshold"`
	BufferTokens         int64  `json:"buffer_tokens"`
	SystemTokens         int64  `json:"system_tokens"`
	ConversationTokens   int64  `json:"conversation_tokens"`
	ToolDefinitionTokens int64  `json:"tool_definition_tokens"`
	MCPToolsTokens       int64  `json:"mcp_tools_tokens"`
}

type ContextReader interface {
	ContextInfo(context.Context) (*ContextInfo, error)
	ContextAttribution(context.Context) (*ContextAttribution, error)
}

type ContextSize struct {
	ID     string `json:"id"`
	Tokens int64  `json:"tokens"`
}

type ContextSource struct {
	ID       string `json:"id"`
	Kind     string `json:"kind"`
	Label    string `json:"label"`
	ParentID string `json:"parent_id,omitempty"`
	Tokens   int64  `json:"tokens"`
}

type Conversation interface {
	// ID returns the exact provider conversation ID to persist.
	ID() string
	// History returns the provider-recorded transcript and subagents of a
	// reopened conversation.
	History(ctx context.Context) (History, error)
	// Send submits one user prompt that starts a turn and returns once the
	// provider accepted or rejected it. The turn continues asynchronously and
	// is reported through events. Ambiguous failures wrap
	// ErrSubmissionUncertain. A provider that would otherwise fold a prompt
	// sent during a turn into that turn must run it after the turn or refuse
	// it with ErrBusy instead.
	Send(ctx context.Context, prompt Prompt) error
	// Commands lists the slash commands that become a prompt: skills and
	// the provider's prompt commands. Nothing else is offered.
	Commands(ctx context.Context) ([]Command, error)
	// RunCommand runs one command from Commands with args.Text as its
	// arguments. It starts a turn like Send, with Send's outcomes; the user
	// item shows "/name arguments". A result that would not start a prompt
	// turn is a rejection. ErrUnsupported means the provider has no commands.
	RunCommand(ctx context.Context, name string, args Prompt) error
	// Steer adds prompt to the turn that is running, before the provider's
	// next model call, and returns once the provider accepted or rejected
	// it. The caller steers only while a turn runs; it never starts a turn.
	// An accepted steer cannot be withdrawn. When the provider uses it, its
	// user item carries Delivery DeliverySteer; when the turn ends without
	// the provider using it, the adapter emits an ItemNotice saying so.
	// Ambiguous failures wrap ErrSubmissionUncertain and are never resent.
	// ErrUnsupported means the provider cannot steer.
	Steer(ctx context.Context, prompt Prompt) error
	// Cancel aborts the current turn. The conversation stays open.
	Cancel(ctx context.Context) error
	// CancelSubagent stops only the exact agent instance. Its final status
	// arrives through EventSubagent; the parent and siblings stay running.
	CancelSubagent(ctx context.Context, agentID string) error
	// PromptSubagent sends text to the exact agent instance while it is
	// SubagentIdle, and returns once the provider accepted or refused it. It
	// is not a turn: the main agent does not see it. An accepted prompt moves
	// the subagent back to SubagentRunning through EventSubagent. Ambiguous
	// failures wrap ErrSubmissionUncertain and are never resent.
	// ErrUnsupported means the provider cannot chat with a subagent.
	PromptSubagent(ctx context.Context, agentID, text string) error
	// Respond answers a pending interaction. It returns ErrInteractionGone
	// when the provider no longer considers the interaction pending.
	Respond(ctx context.Context, interactionID string, answer Answer) error
	// Diff returns provider-recorded file changes for this conversation, or
	// ErrUnsupported when Capabilities().SessionDiff is false.
	Diff(ctx context.Context) ([]FileDiff, error)
	// SetModel applies the complete selection from the next turn on. Empty
	// effort means Default; contextSize is default or a catalog tier ID.
	// The caller validates the selection and never switches during a turn.
	SetModel(ctx context.Context, model, effort, contextSize string) error
	// SetTitle names the conversation in the provider's own store, so the
	// provider's clients show title and the provider no longer titles it.
	// ErrUnsupported means the provider cannot.
	SetTitle(ctx context.Context, title string) error
	// Close disconnects from the conversation without deleting it. Pending
	// interactions end without an answer being fabricated.
	Close(ctx context.Context) error
}

type CustomModel struct {
	// Name names the provider connection; models with one Name share
	// BaseURL, WireAPI and APIKeyEnv.
	Name        string
	DisplayName string
	BaseURL     string
	ModelID     string
	Vision      bool
	// WireAPI is "completions" (also for "") or "responses".
	WireAPI   string
	APIKeyEnv string
	APIKey    string `json:"-"`
}

type CustomModelUser interface {
	SetCustomModels([]CustomModel)
}

type CustomizationsReloader interface {
	ReloadCustomizations(ctx context.Context) error
}

type Delta struct {
	ItemID string   `json:"item_id"`
	Kind   ItemKind `json:"kind"`
	Text   string   `json:"text"`
	// AgentID is the item's agent, as in Item.AgentID.
	AgentID string `json:"agent_id,omitempty"`
}

type DeviceCode struct {
	URL    string `json:"verification_uri"`
	Code   string `json:"user_code"`
	Notice string `json:"notice,omitempty"`
}

type DeviceSignInManager interface {
	// DeviceSignIn starts the flow, calls show with the code to enter (again
	// with a new code when a second approval is needed), and returns once the sign-in is approved and in effect, refused,
	// expired, or ctx ends.
	DeviceSignIn(ctx context.Context, show func(DeviceCode)) (Account, error)
}

type Elicitation struct {
	Mode string `json:"mode"`
	// Source names who asked, such as an MCP server; empty when unknown.
	Source string `json:"source,omitempty"`
	URL    string `json:"url,omitempty"`
}

type Event struct {
	Kind            EventKind
	Item            *Item
	Delta           *Delta
	Turn            *Turn
	Interaction     *Interaction
	PlanPath        string
	PlanVersion     uint64 // lightweight invalidation from native plan_changed
	Subagent        *Subagent
	BackgroundTasks *BackgroundTasks
	Schedules       *ScheduleSnapshot
	Context         *Context
	Usage           *Usage
	Tokens          *TokenUsage
	Execution       *ExecutionState
	// Error is the sanitized reason for EventExit.
	Error string
	// Detached marks an EventExit that ended only this conversation because
	// its turn did not end after Stop: the provider ended the turn as
	// cancelled first, nothing was lost, and the next prompt reopens it.
	Detached bool
	// Title is the untrusted provider title for EventTitle.
	Title string
	// Compacting and CompactingBackground are the payload of
	// EventCompaction: a compaction that holds the conversation, or one the
	// turn goes on beside; neither once it ended.
	Compacting           bool
	CompactingBackground bool

	Activity       *Activity
	Todos          *TodoList
	ModelSelection *ModelSelection
	MCPStatus      *MCPStatusSnapshot
	Skill          *SkillLoad
}

type EventKind string

type EventSink interface {
	Emit(Event)
}

type ExecutionState struct {
	Known     bool                `json:"known"`
	Mode      string              `json:"mode,omitempty"`
	Objective *AutopilotObjective `json:"objective,omitempty"`
}

type Field struct {
	Name     string   `json:"name"`
	Type     string   `json:"type"`
	Required bool     `json:"required,omitempty"`
	Values   []string `json:"values,omitempty"`
	Format   string   `json:"format,omitempty"`
	Minimum  *float64 `json:"minimum,omitempty"`
	Maximum  *float64 `json:"maximum,omitempty"`
	// MinLength and MaxLength bound a string in characters.
	MinLength *int `json:"min_length,omitempty"`
	MaxLength *int `json:"max_length,omitempty"`
	// MinItems and MaxItems bound how many choices an array field takes.
	MinItems *int `json:"min_items,omitempty"`
	MaxItems *int `json:"max_items,omitempty"`
}

type File struct {
	Path string
	Rel  string
	Dir  bool
}

type FileDeclaration struct {
	ArtifactID string `json:"artifact_id"`
	Path       string `json:"path"`
	Title      string `json:"title,omitempty"`
	TypeHint   string `json:"type_hint,omitempty"`
}

type FileDiff struct {
	// CountsUnknown distinguishes omitted/binary patches from zero changes.
	CountsUnknown bool   `json:"counts_unknown,omitempty"`
	Binary        bool   `json:"binary,omitempty"`
	Truncated     bool   `json:"truncated,omitempty"`
	OldPath       string `json:"old_path,omitempty"`
	Path          string `json:"path"`
	Status        string `json:"status,omitempty"`
	Additions     int    `json:"additions"`
	Deletions     int    `json:"deletions"`
	Before        string `json:"before,omitempty"`
	After         string `json:"after,omitempty"`
	Patch         string `json:"patch,omitempty"`
}

type FileEdit struct {
	Path       string `json:"path"`
	Kind       string `json:"kind"`
	Additions  int    `json:"additions,omitempty"`
	Deletions  int    `json:"deletions,omitempty"`
	DiffStatus string `json:"diff_status"`
}

type ForkBoundary struct {
	UserEventID string `json:"user_event_id"`
	ToEventID   string `json:"to_event_id,omitempty"`
	TailEventID string `json:"tail_event_id"`
}

type ForkBoundaryRequest struct {
	ConversationID string
	UserItemID     string
}

type ForkRequest struct {
	ForkBoundaryRequest
	Boundary ForkBoundary
}

type Forker interface {
	ReadForkBoundary(context.Context, ForkBoundaryRequest) (ForkBoundary, error)
	Fork(context.Context, ForkRequest) (string, error)
}

type GitHubMCPUser interface {
	SetGitHubMCP(on bool)
}

type History struct {
	// Items is the transcript, oldest first. Subagent items carry AgentID.
	Items []Item
	// Subagents are the subagent records the recorded events allow to
	// rebuild.
	Subagents []Subagent
	// Usage is the conversation's AI units as recorded, or nil when the
	// record has none.
	Usage *Usage
	// Model is the main agent's model as the record last states it, or ""
	// when the record does not say.
	Model string
	// Skills are the skill loads the record holds, oldest first.
	Skills []SkillLoad
	// Truncated is set when only the newest part of a record too large to
	// read whole was returned.
	Truncated bool
}

type HistoryPager interface {
	ReadHistoryWindow(ctx context.Context, req WindowRequest) (HistoryWindow, error)
}

type HistoryReader interface {
	ReadHistory(ctx context.Context, req ReadRequest) (History, error)
}

type HistoryRewinder interface {
	PreviewRewind(ctx context.Context, userItemID string) (RewindPreview, error)
	Rewind(ctx context.Context, userEventID, mode string) (RewindResult, error)
}

type HistoryWindow struct {
	Items []Item
	// At is the index of the requested item in Items, len(Items) for the
	// end of the record.
	At int
	// Start is set when Items begins with the agent's first recorded item.
	Start bool
	// Next is the ID of the item recorded right after Items, or "" when
	// Items ends with the newest one.
	Next string
}

type HostTool struct {
	Name        string
	Description string
	Parameters  map[string]any
}

type HostToolCall struct {
	Name string
	// CallID is the provider's tool call ID, the ID of the call's ItemTool
	// item. A call repeated with the same CallID gets the first one's result
	// without reaching CallTool again.
	CallID string
	// TaskID is the conversation's OpenRequest.SessionID, the Task the call
	// belongs to.
	TaskID string
	// AgentID is the subagent instance that made the call, as in
	// Item.AgentID; it is empty for the main agent and when the provider does
	// not say.
	AgentID string
	// Arguments is the model's JSON object as received, at most
	// MaxHostToolArguments bytes.
	Arguments json.RawMessage
}

type HostToolResult struct {
	// Text is what the model sees.
	Text string
	// Failed marks a refused or failed call; Text says why.
	Failed bool
	// Payload is optional JSON the web service keeps for its own display of
	// the call. Adapters never send it to the model.
	Payload json.RawMessage
}

type Image struct {
	// ID names the web service's stored copy.
	ID   string `json:"id"`
	MIME string `json:"mime"`
	Size int64  `json:"size"`
	Name string `json:"name,omitempty"`
	// SHA256 is the hex digest of the bytes. The web service matches it to
	// a stored copy when Data is empty. It is never sent to browsers.
	SHA256 string `json:"-"`
	// Data is the image's bytes, from the adapter to the web service only.
	Data []byte `json:"-"`
}

type Importer interface {
	// Previous lists the conversations recorded with exactly workdir as
	// their working directory. An empty workdir lists all local conversations.
	Previous(ctx context.Context, workdir string) ([]PreviousConversation, error)
	// InUse returns the IDs among ids that another process holds open. It is
	// a snapshot: a client can open one right after it. The provider's own
	// runtime is never reported.
	InUse(ctx context.Context, ids []string) ([]string, error)
}

type Interaction struct {
	ID    string          `json:"id"`
	Kind  InteractionKind `json:"kind"`
	Title string          `json:"title"`
	// Detail is display text: command, paths, patterns, or tool arguments.
	Detail string `json:"detail,omitempty"`
	// Intention is the agent's own one-line reason for a permission request,
	// when the provider sends one.
	Intention string      `json:"intention,omitempty"`
	Plan      *PlanReview `json:"plan,omitempty"`
	// Options lists permission decisions the provider accepts. Answer.Decision
	// must be one of these IDs.
	Options []Option `json:"options,omitempty"`
	// Questions lists question prompts. Answer.Answers must have one entry per
	// question.
	Questions  []Question       `json:"questions,omitempty"`
	State      InteractionState `json:"state"`
	Resolution string           `json:"resolution,omitempty"`
	Time       time.Time        `json:"time"`
	// AgentID names the subagent that asked, when the provider says so.
	AgentID string `json:"agent_id,omitempty"`
	// ToolCallID names the provider tool call a request is for: the ID of
	// that call's ItemTool item with the same AgentID. For a permission it
	// is the call that needs it; for a question, the tool call that asked
	// (Copilot's ask_user). It is empty when unknown.
	ToolCallID string `json:"tool_call_id,omitempty"`
	// Auto is set by the web service, never by a provider: yolo mode or an
	// approving assisted review is answering this pending request, so it
	// does not wait for the user.
	Auto bool `json:"auto,omitempty"`
	// Assisted is the provider's assisted review of a permission request;
	// zero when the request was not reviewed.
	Assisted AssistedReview `json:"assisted,omitzero"`
	// Elicitation is set on a question that stands for a provider's
	// structured request: a form or a link. It is user data, never a
	// permission, so yolo mode never answers it.
	Elicitation *Elicitation `json:"elicitation,omitempty"`
}

type InteractionKind string

type InteractionState string

type Item struct {
	ID   string    `json:"id"`
	Kind ItemKind  `json:"kind"`
	Text string    `json:"text,omitempty"`
	Tool *ToolCall `json:"tool,omitempty"`
	// Completion is a provider's bounded completion decision, preserved as
	// a notice. It is separate from the foreground turn's lifecycle.
	Completion *TaskCompletion `json:"completion,omitempty"`
	// Plan is compact native review metadata; its body is read on demand.
	Plan *PlanReview `json:"plan,omitempty"`
	// Time is when the item began: a tool call's start, a thought's model
	// call start, a message's first text.
	Time time.Time `json:"time"`
	// EndedAt is when a tool call or thought finished, from the provider's
	// record; zero while it runs or when the provider did not say.
	EndedAt time.Time `json:"ended_at,omitzero"`
	// AgentID is empty for the main agent, otherwise the exact subagent
	// instance ID from the provider.
	AgentID string `json:"agent_id,omitempty"`
	// Delivery is DeliverySteer on a user item that joined a running turn
	// as a steer, and empty otherwise.
	Delivery string `json:"delivery,omitempty"`
	// SteerStatus marks a local receipt before the provider records a user
	// message. The provider's item with the same ID replaces this receipt.
	SteerStatus string `json:"steer_status,omitempty"`
	// Attachments are the uploads a user item carried; the adapter never
	// includes their bytes.
	Attachments []Attachment `json:"attachments,omitempty"`
	// Images are the images a tool item's result returned, in the
	// provider's order. The adapter includes their bytes; the web service
	// stores them and passes on only the stored copies' metadata.
	Images []Image `json:"images,omitempty"`
	// ImagesNote is set by the web service when it did not keep some of a
	// tool item's images, and says why. Adapters leave it empty.
	ImagesNote string `json:"images_note,omitempty"`
	// Clipped is set when a text of the item was shortened to bound memory.
	// A HistoryPager reads the item whole.
	Clipped bool `json:"-"`
}

type ItemDiff struct {
	Path   string `json:"path"`
	Status string `json:"status"`
	Patch  string `json:"patch,omitempty"`
}

type ItemDiffReader interface {
	ReadItemDiff(ctx context.Context, req ItemDiffRequest) (ItemDiff, error)
}

type ItemDiffRequest struct {
	ReadRequest
	AgentID, ItemID, EventID, Path string
}

type ItemKind string

type MCPCallbackController interface {
	MCPSignInCallback(ctx context.Context, name string, again bool, redirectURI string) (MCPCallbackSignIn, error)
	CompleteMCPSignIn(ctx context.Context, authorizationID, callbackURL string) error
}

type MCPCallbackSignIn struct {
	AuthorizationID string
	URL             string
}

type MCPConfigurer interface {
	MCPServers(ctx context.Context) ([]MCPServer, error)
	// AddMCPServer adds a new server; UpdateMCPServer replaces the
	// transport fields of an existing one and keeps the rest of its entry.
	AddMCPServer(ctx context.Context, cfg MCPServerConfig) error
	UpdateMCPServer(ctx context.Context, cfg MCPServerConfig) error
	RemoveMCPServer(ctx context.Context, name string) error
	SetMCPServerEnabled(ctx context.Context, name string, enabled bool) error
}

type MCPController interface {
	MCPStatus(ctx context.Context) ([]MCPStatus, error)
	SetMCPServerEnabled(ctx context.Context, name string, enabled bool) error
	RestartMCPServer(ctx context.Context, name string) error
	// MCPSignIn starts the OAuth sign-in of a remote server and returns the
	// address to open in a browser, or "" when a kept sign-in sufficed. The
	// provider waits for the browser on a loopback address of this host.
	// again discards a kept sign-in first.
	MCPSignIn(ctx context.Context, name string, again bool) (string, error)
}

type MCPServer struct {
	MCPServerConfig
	Enabled bool   `json:"enabled"`
	Source  string `json:"source"`
}

type MCPServerConfig struct {
	Name    string            `json:"name"`
	Type    string            `json:"type"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Cwd     string            `json:"cwd,omitempty"`
	Env     map[string]string `json:"-"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"-"`
}

type MCPServerStatus struct {
	Name           string `json:"name"`
	Status         string `json:"status"`
	Error          string `json:"error,omitempty"`
	Source         string `json:"source,omitempty"`
	Remote         bool   `json:"remote,omitempty"`
	SignIn         bool   `json:"sign_in,omitempty"`
	NeedsReconnect bool   `json:"needs_reconnect,omitempty"`
}

type MCPStatus struct {
	Name   string    `json:"name"`
	Status string    `json:"status"`
	Error  string    `json:"error,omitempty"`
	Source string    `json:"source,omitempty"`
	Remote bool      `json:"remote,omitempty"`
	SignIn bool      `json:"sign_in,omitempty"`
	Tools  []MCPTool `json:"tools,omitempty"`
}

type MCPStatusReader interface {
	MCPStatusSnapshot(ctx context.Context) (MCPStatusSnapshot, error)
	MCPTools(ctx context.Context, name string) ([]MCPTool, error)
}

type MCPStatusSnapshot struct {
	Supported bool              `json:"supported"`
	Ready     bool              `json:"ready"`
	Servers   []MCPServerStatus `json:"servers"`
	Truncated bool              `json:"truncated,omitempty"`
}

type MCPTool struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type Media struct {
	Images bool `json:"images"`
	PDF    bool `json:"pdf"`
	// MaxImages is the most images one prompt may carry; 0 means no limit
	// was reported.
	MaxImages int `json:"max_images,omitempty"`
	// Types lists the accepted image and document MIME types; empty means
	// any type Images and PDF allow.
	Types []string `json:"types,omitempty"`
}

type Model struct {
	ID           string        `json:"id"`
	Name         string        `json:"name"`
	Efforts      []string      `json:"efforts"`
	ContextSizes []ContextSize `json:"context_sizes"`
	// Media is what the model accepts besides text. Nil means the provider
	// reports nothing (Copilot's auto), and uploads are not gated.
	Media *Media `json:"media,omitempty"`
	// CostTier is one of the Cost constants, the provider's relative cost of
	// the model; empty when it reports none.
	CostTier string `json:"cost_tier,omitempty"`
	// DiscountPercent is the whole-number discount (1-100) the provider
	// applies to usage billed through this model, such as Copilot's auto; 0
	// when it reports none.
	DiscountPercent int `json:"discount_percent,omitempty"`
	// Prices are the model's token prices; nil when the provider reports
	// none.
	Prices *Prices `json:"prices,omitempty"`
}

type ModelSelection struct {
	Model       string
	Effort      *string
	ContextSize *string
}

type NativeTurnChanges struct {
	Status    string           `json:"status"`
	EventID   string           `json:"event_id,omitempty"`
	Files     int64            `json:"files,omitempty"`
	Additions int64            `json:"additions,omitempty"`
	Deletions int64            `json:"deletions,omitempty"`
	Omitted   int64            `json:"omitted,omitempty"`
	Entries   []NativeTurnFile `json:"entries,omitempty"`
}

type NativeTurnFile struct {
	Path      string `json:"path"`
	Kind      string `json:"kind"`
	Additions int64  `json:"additions,omitempty"`
	Deletions int64  `json:"deletions,omitempty"`
}

type OpenRequest struct {
	// SessionID is the uam managed-session ID (a UUID).
	SessionID string
	// ConversationID is the exact provider conversation ID, or "" to create.
	ConversationID string
	// Workdir is the absolute, canonical project directory.
	Workdir string
	// Title is the user-visible session name.
	Title string
	// Model is the model ID for a new conversation; "" means the provider
	// default. Reopening does not switch to it (the caller applies the
	// selection with SetModel), but an adapter keeps Model, Effort and
	// ContextSize when selecting Agent applies the agent's own model.
	Model string
	// Effort and ContextSize apply when creating a conversation.
	Effort      string
	ContextSize string
	// Agent is the ID of the custom agent selected on create and on every
	// reopen, before anything is sent; "" keeps the provider's default
	// agent. An agent that cannot be selected fails the open with
	// ErrAgentUnavailable.
	Agent string
	// Events receives every event for this conversation until Close returns.
	Events EventSink
	// ValidateFile checks a declaration candidate without granting access or
	// reading file bytes, and returns its normalized absolute display path.
	ValidateFile func(context.Context, string) (string, error)
	// Hooks run host policy for this Task, including calls by its subagents.
	Hooks ToolHooks
	// Tools are the web service's host tools, registered beside the
	// adapter's own when Capabilities.HostTools is set. CallTool, bound to
	// this Task by the web service, runs each of their calls.
	Tools    []HostTool
	CallTool func(context.Context, HostToolCall) HostToolResult
	// SkillDirectories are directories of the web service's own skills, each
	// holding <name>/SKILL.md, loaded beside the ones the provider discovers.
	SkillDirectories []string
	// CompactionThreshold is the share of the context window (0 to 1) at
	// which the conversation starts compacting; 0 keeps the provider default.
	// It applies on create and on every reopen.
	CompactionThreshold float64
	// AssistedApprovalModel, when set, turns on the provider's assisted
	// permission review with this model as the reviewer, on create and on
	// every reopen. Open fails when the runtime does not apply it.
	AssistedApprovalModel string
}

type Option struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	// Reject marks decisions that deny the request.
	Reject bool `json:"reject,omitempty"`
	// AllowOnce marks the decision that allows this one request and nothing
	// more. A provider leaves it off when its policy says a person must
	// decide: the web service's yolo mode answers only with this option.
	AllowOnce bool `json:"allow_once,omitempty"`
}

type OutputLine struct {
	Text string `json:"text"`
	Err  bool   `json:"err,omitempty"` // stream "stderr"; stdout and terminal are false
}

type Phase struct {
	// Calls counts the model calls in flight, the main agent's (compaction
	// included) and its subagents'; Subagents how many of them are
	// subagents'.
	Calls     int `json:"calls,omitempty"`
	Subagents int `json:"subagents,omitempty"`
	// Model is the model of the main agent's call in flight, else of its
	// compaction, else of the oldest subagent call; CallsSince is when
	// Model's call started. Compacting is set when Model's call is the
	// compaction; Agent describes the subagent when it is a subagent's.
	Model      string    `json:"model,omitempty"`
	CallsSince time.Time `json:"calls_since,omitzero"`
	Compacting bool      `json:"compacting,omitempty"`
	Agent      string    `json:"agent,omitempty"`
	// Tool names the oldest running tool call, "" when none runs; Detail is
	// the short argument it is shown by (toolargs.Compact), bounded;
	// ToolSince is when it started. ToolSubagent is set when a subagent runs
	// it.
	Tool         string    `json:"tool,omitempty"`
	Detail       string    `json:"detail,omitempty"`
	ToolSince    time.Time `json:"tool_since,omitzero"`
	ToolSubagent bool      `json:"tool_subagent,omitempty"`
}

type PlanAction string

type PlanAnswer struct {
	Action   PlanAction `json:"action,omitempty"`
	Feedback string     `json:"feedback,omitempty"`
}

type PlanDraft struct {
	Exists    bool   `json:"exists"`
	Content   string `json:"content,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

type PlanDraftReader interface {
	ReadPlanDraft(context.Context) (PlanDraft, error)
}

type PlanHistoryReader interface {
	ReadPlanReview(context.Context, ReadRequest, string) (PlanReview, error)
}

type PlanReview struct {
	RequestID           string       `json:"request_id"`
	Summary             string       `json:"summary,omitempty"`
	Revision            int          `json:"revision,omitempty"`
	Actions             []PlanAction `json:"actions,omitempty"`
	Recommended         PlanAction   `json:"recommended,omitempty"`
	Content             string       `json:"content,omitempty"`
	Previous            string       `json:"previous,omitempty"`
	Truncated           bool         `json:"truncated,omitempty"`
	PreviousTruncated   bool         `json:"previous_truncated,omitempty"`
	PreviousUnavailable bool         `json:"previous_unavailable,omitempty"`
}

type PreviousConversation struct {
	ID        string
	Title     string
	Workdir   string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type Prices struct {
	BatchSize int64 `json:"batch_size,omitempty"`
	TierPrices
	// LongContext holds the long-context tier's prices, which apply past the
	// default MaxPromptTokens or when that tier is selected.
	LongContext *TierPrices `json:"long_context,omitempty"`
}

type Prompt struct {
	Text        string
	Files       []File
	Attachments []Blob
}

type Provider interface {
	// Name returns the provider identifier used in persisted task records.
	Name() string
	// DisplayName returns a human label, e.g. "GitHub Copilot".
	DisplayName() string
	Capabilities() Capabilities
	// Check reports whether the installed runtime is present and compatible,
	// without starting a conversation. The error text is shown to the user.
	Check(ctx context.Context) error
	// Models returns the models the signed-in account can select. An empty
	// list or ErrUnsupported means only the provider default is offered. A
	// provider that lists models must support Conversation.SetModel.
	Models(ctx context.Context) ([]Model, error)
	// Open creates a conversation when req.ConversationID is empty, otherwise
	// reopens exactly that conversation (ErrConversationNotFound when it no
	// longer exists). ctx bounds the open call only.
	Open(ctx context.Context, req OpenRequest) (Conversation, error)
	// Shutdown closes every conversation and stops runtimes this provider
	// started. It never stops a runtime it did not start.
	Shutdown(ctx context.Context) error
}

type Question struct {
	Text    string   `json:"text"`
	Header  string   `json:"header,omitempty"`
	Choices []string `json:"choices,omitempty"`
	// Multiple allows selecting more than one choice.
	Multiple bool `json:"multiple,omitempty"`
	// Custom allows a free-form answer.
	Custom bool `json:"custom"`
	// Field is the typed form field this question asks for, on an
	// elicitation form only.
	Field *Field `json:"field,omitempty"`
}

type Quota struct {
	// Type is the provider's quota key, e.g. Copilot's premium_interactions.
	Type string
	// Used is what the current period used; Entitlement is what it includes,
	// 0 when Unlimited.
	Used        int64
	Entitlement int64
	Unlimited   bool
	// RemainingPercent is the provider's percentage of the entitlement left.
	RemainingPercent float64
	// Overage is what was used beyond the entitlement this period.
	Overage float64
	// ResetAt is when the provider says the quota resets; zero when it does
	// not say. It is not checked here.
	ResetAt time.Time
	// Unit is what Used and Entitlement count, QuotaUnitCredits or
	// QuotaUnitRequests; "" when the provider has not said.
	Unit string
	// Plan is the account's plan tier as the provider names it, e.g.
	// Copilot's "pro" or "pro_plus"; "" when it is not known.
	Plan string
}

type QuotaReporter interface {
	Quota(ctx context.Context) ([]Quota, error)
}

type ReadRequest struct {
	ConversationID string
	Workdir        string
}

type Retry struct {
	// Count is how many times the call was retried so far.
	Count int `json:"count"`
	// Reason is the provider's reason code, such as "rate_limited", when it
	// gives one.
	Reason string `json:"reason,omitempty"`
	// Status is the HTTP status of the attempt that failed, 0 when unknown.
	Status int `json:"status,omitempty"`
	// Network is set when that attempt failed without a response.
	Network bool      `json:"network,omitempty"`
	At      time.Time `json:"at"`
}

type RewindPreview struct {
	UserEventID    string            `json:"user_event_id"`
	TailEventID    string            `json:"tail_event_id"`
	Turns          int               `json:"turns"`
	Discarded      []string          `json:"-"`
	FilesAvailable bool              `json:"files_available"`
	FilesReason    string            `json:"files_reason,omitempty"`
	Files          NativeTurnChanges `json:"files"`
}

type RewindResult struct {
	Outcome         string       `json:"outcome"`
	Error           *string      `json:"error,omitempty"`
	EventsRemoved   *int64       `json:"events_removed,omitempty"`
	RestoredFiles   []string     `json:"restored_files"`
	SkippedFiles    []RewindSkip `json:"skipped_files"`
	RestoredOmitted int          `json:"restored_omitted,omitempty"`
	SkippedOmitted  int          `json:"skipped_omitted,omitempty"`
}

type RewindSkip struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

type ScheduleEntry struct {
	ID         string    `json:"id"`
	Recurring  bool      `json:"recurring"`
	SelfPaced  bool      `json:"self_paced,omitempty"`
	IntervalMs int64     `json:"interval_ms,omitempty"`
	Cron       string    `json:"cron,omitempty"`
	Timezone   string    `json:"timezone,omitempty"`
	NextRunAt  time.Time `json:"next_run_at,omitzero"`
}

type ScheduleSnapshot struct {
	Supported bool            `json:"supported"`
	Known     bool            `json:"known"`
	Entries   []ScheduleEntry `json:"entries"`
	Truncated bool            `json:"truncated,omitempty"`
	Reason    string          `json:"reason,omitempty"`
}

type SkillGlobalSetter interface {
	SetSkillGloballyDisabled(ctx context.Context, name string, disabled bool) error
}

type SkillLoad struct {
	ID          string
	AgentID     string
	Name        string
	Description string
	At          time.Time
}

type Subagent struct {
	ID     string `json:"id"`
	Model  string `json:"model,omitempty"`
	Effort string `json:"effort,omitempty"`
	// ParentToolCallID is the ID of the tool call item that spawned it.
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
	// ParentAgentID is the subagent whose tool call spawned it, empty when
	// the main agent did: that call is in the parent's transcript.
	ParentAgentID string `json:"parent_agent_id,omitempty"`
	Name          string `json:"name"`
	Description   string `json:"description,omitempty"`
	// Background is set when it was launched in the background: its parent
	// tool call then only acknowledges the launch, and its result is its own
	// last message.
	Background bool           `json:"background,omitempty"`
	Status     SubagentStatus `json:"status"`
	// Error is the provider's reason for SubagentFailed.
	Error     string    `json:"error,omitempty"`
	StartedAt time.Time `json:"started_at,omitzero"`
	EndedAt   time.Time `json:"ended_at,omitzero"`
	// Runs lists its periods of work, oldest first, when the provider tracks
	// them: a reused subagent keeps its ID and gains a run per reuse. The
	// latest run carries Status and EndedAt. At most MaxSubagentRuns are
	// kept: the first and the newest.
	Runs []SubagentRun `json:"runs,omitempty"`
	// Tokens is the input and output tokens it consumed, over all runs.
	Tokens int64 `json:"tokens,omitempty"`
	// ToolCalls is the number of tool calls it made, over all runs.
	ToolCalls int64 `json:"tool_calls,omitempty"`
	// Retry is set while its current model call is being retried. It is
	// live only: the provider does not record retries.
	Retry *Retry `json:"retry,omitempty"`
	// Result is the start of the output its parent tool call recorded, when
	// a read record has it but not that tool call's item.
	Result string `json:"-"`
}

type SubagentModelUser interface {
	SetSubagentModels(models []string)
}

type SubagentPager interface {
	ReadSubagents(ctx context.Context, req SubagentRequest) (SubagentWindow, error)
}

type SubagentRequest struct {
	ReadRequest
	AgentID string
	Before  int
}

type SubagentRun struct {
	StartedAt time.Time      `json:"started_at,omitzero"`
	EndedAt   time.Time      `json:"ended_at,omitzero"`
	Status    SubagentStatus `json:"status"`
	// Trigger says who started the run: SubagentTriggerSpawn, -Agent or -User.
	Trigger string `json:"trigger"`
}

type SubagentStatus string

type SubagentWindow struct {
	Subagents []Subagent
	// Start is set when Subagents begins with the first recorded subagent.
	Start bool
}

type TaskCompletion struct {
	Decision   CompletionDecision `json:"decision"`
	UserItemID string             `json:"user_item_id,omitempty"`
	Summary    string             `json:"summary,omitempty"`
	Reason     string             `json:"reason,omitempty"`
	Blocker    *CompletionBlocker `json:"blocker,omitempty"`
}

type TaskUsageMetrics struct {
	StartedAt          time.Time              `json:"started_at"`
	CurrentModel       string                 `json:"current_model,omitempty"`
	UserRequests       int64                  `json:"user_requests"`
	PremiumRequestCost float64                `json:"premium_request_cost"`
	APIDurationMS      int64                  `json:"api_duration_ms"`
	AIUnits            *float64               `json:"ai_units,omitempty"`
	LastInput          int64                  `json:"last_input"`
	LastOutput         int64                  `json:"last_output"`
	CodeChanges        UsageMetricCodeChanges `json:"code_changes"`
	TokenDetails       []UsageTokenDetail     `json:"token_details"`
	Models             []UsageMetricModel     `json:"models"`
	Agents             []UsageMetricAgent     `json:"agents"`
	Truncated          bool                   `json:"truncated,omitempty"`
}

type TierPrices struct {
	Input           *float64 `json:"input,omitempty"`
	Output          *float64 `json:"output,omitempty"`
	CacheRead       *float64 `json:"cache_read,omitempty"`
	CacheWrite      *float64 `json:"cache_write,omitempty"`
	MaxPromptTokens int64    `json:"max_prompt_tokens,omitempty"`
}

type TitleRequest struct {
	// Model is a model ID from Provider.Models.
	Model string
	// Workdir is the Task's project directory.
	Workdir string
	// Text is the Task's first message, already sanitized and clipped; it
	// may be empty when the message carried only uploads or files.
	Text string
	// Images are the first message's images, set only when Model accepts
	// them.
	Images []Blob
	// Reply is the agent's reply to the first message, sanitized and
	// clipped, set when the title waited for the first turn.
	Reply string
	// OnUsage is as in UtilityRequest.
	OnUsage func(UtilityUsage)
}

type Titler interface {
	// Title asks req.Model for a title of a Task's first message and returns
	// the model's reply as it came; the caller cleans it. The call runs in a
	// throwaway conversation without tools that it deletes whatever the
	// outcome. ctx bounds the whole call.
	Title(ctx context.Context, req TitleRequest) (string, error)
}

type Todo struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	// Status is pending, in_progress, done or blocked.
	Status string `json:"status"`
	// Note says why a blocked row is blocked; "" for the others.
	Note string `json:"note,omitempty"`
	// AgentID is the subagent that first wrote the row; "" for the main
	// agent or when that is not known.
	AgentID string `json:"agent_id,omitempty"`
	// ChangedAt is when its status last changed, as far as uam saw it;
	// zero when it was first seen on opening the conversation.
	ChangedAt time.Time `json:"changed_at,omitzero"`
}

type TodoList struct {
	// Known is false when the list could not be read.
	Known bool   `json:"known"`
	Todos []Todo `json:"todos"`
}

type TokenUsage struct {
	Model                                string
	Time                                 time.Time
	Input, Output, CacheRead, CacheWrite int64
	// DurationMS is the model call's own duration when the provider reports it.
	DurationMS int64
	NanoAIU    int64
	Cost       float64
}

type ToolCall struct {
	Name   string     `json:"name"`
	Title  string     `json:"title,omitempty"`
	Status ToolStatus `json:"status"`
	Input  string     `json:"input,omitempty"`
	Output string     `json:"output,omitempty"`
	// Native committed edits are bounded metadata. The exact completion event
	// identifies their immutable patch, fetched separately through ItemDiffReader.
	EditEventID        string     `json:"edit_event_id,omitempty"`
	FileEdits          []FileEdit `json:"file_edits,omitempty"`
	FileEditsTruncated bool       `json:"file_edits_truncated,omitempty"`
	// Progress is the latest human status of a running call, at most 512
	// UTF-8 bytes. It is display metadata, not tool output; empty once ended.
	Progress string `json:"progress,omitempty"`
	// ExitCode is a shell command's exit code, when the provider reports
	// one; nil otherwise.
	ExitCode *int `json:"exit_code,omitempty"`
	// Declaration is display intent from a completed host tool call. It is
	// neither file provenance nor authority to open the path.
	Declaration *FileDeclaration `json:"declaration,omitempty"`
	// Tail is the newest output lines of a running shell call, oldest first,
	// at most 10, each at most 512 bytes; nil once the call ends.
	Tail []OutputLine `json:"tail,omitempty"`
}

type ToolHooks struct {
	Pre func(context.Context, ToolUse) ToolVerdict
	// Succeeded observes completed tool calls without changing their result.
	Succeeded func(context.Context, ToolUse)
	// Failed also receives native automatic permission denials, with PermissionKind.
	Failed func(context.Context, ToolUse, string) string
	// Prompt adds host context to a prompt as its turn starts.
	Prompt func(context.Context) string
}

type ToolStatus string

type ToolUse struct {
	// PermissionKind comes from verified provider metadata or a permission request.
	PermissionKind string
	Tool           string
	Args           map[string]any
	Workdir        string
	// AgentID is the subagent making the call; "" for the main agent.
	AgentID string
}

type ToolVerdict struct {
	Context, Deny string
	Args          map[string]any
}

type Turn struct {
	// Completion is the main agent's receipt from this foreground event
	// generation only. Consumers must also match its UserItemID.
	Completion *TaskCompletion `json:"completion,omitempty"`
	State      TurnState       `json:"state"`
	// Error is the sanitized provider error for TurnFailed.
	Error string `json:"error,omitempty"`
	// Model is the model the provider reported for this turn, when known.
	Model string `json:"model,omitempty"`
	// Reason is the provider's code for why a TurnCancelled turn stopped,
	// such as "autopilot_credit_limit"; "" when it gave none.
	Reason string `json:"reason,omitempty"`
	// ReadOnceHits counts the repeat views the provider's read-once replaced
	// in the turn; StallGaveUp is set when a second model stall ended it.
	// Only uam's own counts read them.
	ReadOnceHits int  `json:"-"`
	StallGaveUp  bool `json:"-"`
}

type TurnChangeReader interface {
	TurnChanges(context.Context, string) (NativeTurnChanges, error)
}

type TurnState string

type Usage struct {
	AIUnits float64 `json:"ai_units"`
}

type UsageMetricAgent struct {
	ID            string             `json:"id"`
	Name          string             `json:"name,omitempty"`
	DisplayName   string             `json:"display_name,omitempty"`
	APIDurationMS int64              `json:"api_duration_ms"`
	AIUnits       float64            `json:"ai_units"`
	Models        []UsageMetricModel `json:"models"`
}

type UsageMetricCodeChanges struct {
	Files   int64 `json:"files"`
	Added   int64 `json:"added"`
	Removed int64 `json:"removed"`
}

type UsageMetricModel struct {
	Model              string             `json:"model"`
	Requests           int64              `json:"requests"`
	PremiumRequestCost float64            `json:"premium_request_cost"`
	AIUnits            *float64           `json:"ai_units,omitempty"`
	Input              int64              `json:"input"`
	Output             int64              `json:"output"`
	CacheRead          int64              `json:"cache_read"`
	CacheWrite         int64              `json:"cache_write"`
	Reasoning          *int64             `json:"reasoning,omitempty"`
	CacheExpiresAt     *time.Time         `json:"cache_expires_at,omitempty"`
	TokenDetails       []UsageTokenDetail `json:"token_details"`
}

type UsageMetricsReader interface {
	UsageMetrics(context.Context) (*TaskUsageMetrics, error)
}

type UsageSessionRecorder interface {
	SetUsageSessionRecorder(func(sessionID string, active bool) error)
}

type UsageTokenDetail struct {
	Type   string `json:"type"`
	Tokens int64  `json:"tokens"`
}

type UtilityRequest struct {
	// Model is a model ID from Provider.Models; Workdir is the project
	// directory the conversation runs in.
	Model, Workdir string
	// Purpose names the job in the provider's client name and logs, such as
	// "title".
	Purpose        string
	System, Prompt string
	// Attachments go with Prompt as uploads, such as the images a title
	// is made from.
	Attachments []Blob
	// Tools and CallTool are as in OpenRequest. Their calls have no TaskID.
	Tools    []HostTool
	CallTool func(context.Context, HostToolCall) HostToolResult
	// Timeout, when positive, also bounds the whole call.
	Timeout time.Duration
	// ResponseSchema is an optional JSON Schema the provider enforces;
	// callers still validate.
	ResponseSchema map[string]any
	// OnUsage, when set, receives what the call's model requests reported,
	// summed, once before the call returns; it is not called when none
	// reported usage.
	OnUsage func(UtilityUsage)
}

type UtilityRunner interface {
	RunUtility(ctx context.Context, req UtilityRequest) (string, error)
}

type UtilityUsage struct {
	InputTokens, OutputTokens int64
	Credits                   float64
	// Tokens preserves each reported model call for dated usage accounting.
	Tokens []TokenUsage
}

type WindowRequest struct {
	ReadRequest
	// AgentID is "" for the main agent, otherwise a subagent instance ID.
	// Only that agent's items are read.
	AgentID string
	ItemID  string
	// Before and After bound the items read before and after ItemID.
	Before, After int
}