runtime

type AgentBudgetUsage struct {
	AgentName     string  `json:"agent_name"`
	Cost          float64 `json:"cost"`
	Tokens        int64   `json:"tokens"`
	ActiveSeconds float64 `json:"active_seconds"`
}

type AgentChoiceEvent struct {
	AgentContext

	Type      string `json:"type"`
	Content   string `json:"content"`
	SessionID string `json:"session_id,omitempty"`
	MessageID string `json:"message_id,omitempty"`
}

type AgentChoiceReasoningEvent struct {
	AgentContext

	Type      string `json:"type"`
	Content   string `json:"content"`
	SessionID string `json:"session_id,omitempty"`
	MessageID string `json:"message_id,omitempty"`
}

type AgentChoiceReasoningResetEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	MessageID string `json:"message_id"`
}

type AgentContext struct {
	OperationID uint64    `json:"-"`
	AgentName   string    `json:"agent_name,omitempty"`
	Timestamp   time.Time `json:"timestamp"`
}

type AgentDetails struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Provider    string `json:"provider"`
	Model       string `json:"model"`
	// Thinking is a short label describing the model's current thinking-effort
	// configuration: an effort level (e.g. "high"), "adaptive", a decimal token
	// count for token-based budgets, or "off" when disabled. Empty when the
	// model has no selectable thinking configuration.
	Thinking              string                            `json:"thinking,omitempty"`
	Commands              types.Commands                    `json:"commands,omitempty"`
	ExecutionCapabilities *inspection.ExecutionCapabilities `json:"execution_capabilities,omitempty"`
}

type AgentInfoEvent struct {
	AgentContext

	Type           string `json:"type"`
	AgentName      string `json:"agent_name"`
	Model          string `json:"model"` // this is in provider/model format (e.g., "openai/gpt-4o")
	Description    string `json:"description"`
	WelcomeMessage string `json:"welcome_message,omitempty"`
	ContextLimit   int64  `json:"context_limit,omitempty"`
	// CompactionModel is the identity ("provider/model") of the agent's
	// dedicated compaction model, set only when it actually caps ContextLimit
	// below the primary model's own window.
	CompactionModel string `json:"compaction_model,omitempty"`
	// PrimaryContextLimit is the primary model's own context window, set
	// only alongside CompactionModel.
	PrimaryContextLimit int64 `json:"primary_context_limit,omitempty"`
	// Nil means unknown; model-only update events may omit this field.
	ExecutionCapabilities *inspection.ExecutionCapabilities `json:"execution_capabilities,omitempty"`
}

type AgentRouteEvent struct {
	AgentContext

	Type         string `json:"type"`
	SessionID    string `json:"session_id"`
	InvocationID string `json:"invocation_id"`
	StepID       string `json:"step_id"`
	// Phase is before_agent_run, after_agent_complete, or force_handoff.
	Phase     string `json:"phase"`
	FromAgent string `json:"from_agent"`
	ToAgent   string `json:"to_agent"`
	// Evaluator fields are empty for command selectors and forced handoffs.
	Evaluator      string   `json:"evaluator,omitempty"`
	Selected       string   `json:"selected,omitempty"`
	Probability    *float64 `json:"probability,omitempty"`
	Model          string   `json:"model,omitempty"`
	FallbackReason string   `json:"fallback_reason,omitempty"`
}

type AgentSwitchingEvent struct {
	AgentContext

	Type      string `json:"type"`
	Switching bool   `json:"switching"`
	FromAgent string `json:"from_agent,omitempty"`
	ToAgent   string `json:"to_agent,omitempty"`
}

type AuthorizationEvent struct {
	AgentContext

	Type         string                  `json:"type"`
	Confirmation tools.ElicitationAction `json:"confirmation"`
}

type BackgroundAgentStatusEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Running   bool   `json:"running"`
}

type BudgetExceededEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	// Budget names which budget tripped: "run" for the top-level
	// `budget:`, otherwise the key under `budgets:`.
	Budget string `json:"budget"`
	Limit  string `json:"limit"`
	Used   string `json:"used"`
	Max    string `json:"max"`
	// ConfigPath is the YAML path of the limit that tripped, e.g.
	// "budgets.tight.max_cost", so an operator knows exactly what to edit.
	ConfigPath string `json:"config_path"`
	Message    string `json:"message"`
	// StopMessage is the assistant stop message the runtime appends to the
	// session right after this event. message_added events carry no JSON
	// payload, so this is how JSON consumers (the evaluation pipeline
	// reading `run --exec --json` output) see the message a budget stop
	// records. Its dedicated type carries only agent name, role, content,
	// and creation time; tool calls, reasoning, model, usage, and cost
	// cannot be represented at all.
	StopMessage *BudgetStopMessage `json:"stop_message,omitempty"`
}

type BudgetStatus struct {
	// Name is "run" for the top-level `budget:`, otherwise the key under
	// `budgets:`.
	Name      string  `json:"name"`
	Cost      float64 `json:"cost"`
	MaxCost   float64 `json:"max_cost,omitempty"`
	Tokens    int64   `json:"tokens"`
	MaxTokens int64   `json:"max_tokens,omitempty"`
	// ElapsedSeconds and MaxTimeSeconds are seconds rather than a
	// duration string so consumers can compute a ratio without parsing.
	ElapsedSeconds float64 `json:"elapsed_seconds"`
	MaxTimeSeconds float64 `json:"max_time_seconds,omitempty"`
	// Unpriced reports that at least one response could not be priced, so
	// Cost understates what was really spent.
	Unpriced bool `json:"unpriced,omitempty"`
	// PerAgent attributes this budget's totals to each agent that spent
	// from it, biggest spender first. Empty until a turn completes.
	PerAgent []AgentBudgetUsage `json:"per_agent,omitempty"`
}

type BudgetStopChatMessage struct {
	Role      chat.MessageRole `json:"role"`
	Content   string           `json:"content"`
	CreatedAt string           `json:"created_at,omitempty"`
}

type BudgetStopMessage struct {
	AgentName string                `json:"agent_name,omitempty"`
	Message   BudgetStopChatMessage `json:"message"`
}

type BudgetUsageEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	// Budgets carries one reading per active budget, run-wide first then
	// named budgets alphabetically, so a consumer can render them in a
	// stable order.
	Budgets []BudgetStatus `json:"budgets,omitempty"`
}

type CommandEvaluator interface {
	Evaluate(ctx context.Context, instruction string, args []string) string
}

type CommandEvaluatorFactory = func(agentTools []tools.Tool) CommandEvaluator

type ContextBreakdown struct {
	// SystemPrompt covers the invariant system messages: the agent
	// instruction, multi-agent/handoff prompts, and toolset instructions.
	SystemPrompt ContextCategory `json:"system_prompt"`
	// ToolDefinitions covers the JSON schemas (name, description,
	// parameters) of every tool exposed to the agent.
	ToolDefinitions ContextCategory `json:"tool_definitions"`
	// PromptFiles covers the add_prompt_files content (AGENTS.md, ...)
	// injected as transient context at every turn.
	PromptFiles ContextCategory `json:"prompt_files"`
	// Messages covers the user and assistant conversation turns.
	Messages ContextCategory `json:"messages"`
	// ToolResults covers the tool-role result messages.
	ToolResults ContextCategory `json:"tool_results"`
	// CompactionSummary covers the synthetic message that carries the
	// latest compaction summary, when the session has been compacted.
	CompactionSummary ContextCategory `json:"compaction_summary"`

	// PromptFileItems details the individual files behind the PromptFiles
	// category, in resolution order.
	PromptFileItems []ContextFile `json:"prompt_file_items,omitempty"`
	// AttachedFiles lists the files attached to the session (/attach,
	// @-mentions), in attach order. Their content was inlined into user
	// messages at send time, so their tokens are already counted in the
	// Messages category; the per-file numbers here are re-estimated from
	// the current on-disk content and are informational, not an extra
	// bucket in TotalTokens.
	AttachedFiles []ContextFile `json:"attached_files,omitempty"`
	// LatestCompactionSummary is the verbatim text behind the
	// CompactionSummary category: the most recent compaction summary
	// stored on the session, or "" when it has never been compacted.
	LatestCompactionSummary string `json:"latest_compaction_summary,omitempty"`

	// ContextLimit is the resolved context window of the effective model,
	// or 0 when it cannot be determined (harness-backed agents, models
	// absent from the catalogue).
	ContextLimit int64 `json:"context_limit"`
	// Model is the effective model label ("provider/model", or the
	// harness label for harness-backed agents).
	Model string `json:"model"`

	// CompactionModel is the identity ("provider/model") of the agent's
	// dedicated compaction model, set whenever one is configured (regardless
	// of whether its window actually caps ContextLimit) — renderers need the
	// unresolved-primary edge case (PrimaryContextLimit == 0) too. Use
	// CompactionContextLimit and PrimaryContextLimit together with
	// [LocalRuntime.effectiveContextLimit]'s cap predicate to decide whether
	// to attribute a reduction.
	CompactionModel string `json:"compaction_model,omitempty"`
	// CompactionContextLimit is the dedicated compaction model's own context
	// window, or 0 when it cannot be resolved. Set only alongside
	// CompactionModel.
	CompactionContextLimit int64 `json:"compaction_context_limit,omitempty"`
	// PrimaryContextLimit is the primary model's own context window (before
	// any compaction-model cap is applied), or 0 when it cannot be resolved.
	// Set only alongside CompactionModel.
	PrimaryContextLimit int64 `json:"primary_context_limit,omitempty"`
}

type ContextCategory struct {
	Tokens int64 `json:"tokens"`
	Items  int   `json:"items"`
}

type ContextFile struct {
	// Path is the file's absolute location on disk.
	Path string `json:"path"`
	// Tokens is the estimated in-context footprint of the file. It is 0
	// for files whose content never reaches the prompt inline (unsupported
	// types, oversized text files) and for missing files.
	Tokens int64 `json:"tokens"`
	// Missing marks files that can no longer be read from disk.
	Missing bool `json:"missing,omitempty"`
}

type CreateSessionRequest struct {
	AgentName string `json:"agent_name,omitempty"`
	// ToolsApproved is the legacy --yolo signal. New callers should
	// prefer SafetyPolicy; option setters keep both in sync.
	ToolsApproved bool `json:"tools_approved"`
	// SafetyPolicy is the user-owned per-session safety preference (CLI
	// flags, alias options, user settings — never author YAML); empty
	// falls back to the ToolsApproved-derived default or, for fresh local
	// sessions, to the author-declared config defaults. See
	// [session.SafetyPolicy].
	SafetyPolicy session.SafetyPolicy `json:"safety_policy,omitempty"`
	// SafetyExplicit marks a SafetyPolicy chosen explicitly on the command
	// line (--safety / --yolo) rather than resolved from alias or
	// user-settings defaults. Resuming a stored session only honours
	// explicit values: defaults must never replace the persisted mode.
	// Not serialized: the remote protocol has no resume path yet (--remote
	// is mutually exclusive with --session).
	SafetyExplicit    bool                 `json:"-"`
	HideToolResults   bool                 `json:"hide_tool_results"`
	SessionDB         string               `json:"session_db,omitempty"`
	ResumeSessionID   string               `json:"resume_session_id,omitempty"`
	SnapshotsEnabled  bool                 `json:"snapshots_enabled"`
	GlobalPermissions *permissions.Checker `json:"-"`
	WorkingDir        string               `json:"working_dir,omitempty"`
}

type CurrentAgentInfo struct {
	Name        string
	Description string
	Commands    types.Commands
}

type ElicitationClosedEvent struct {
	AgentContext

	Type          string `json:"type"`
	ElicitationID string `json:"elicitation_id"`
	SessionID     string `json:"session_id,omitempty"`
}

type ElicitationError struct {
	Action  string
	Message string
}

type ElicitationRequestEvent struct {
	AgentContext

	Type    string `json:"type"`
	Message string `json:"message"`
	Mode    string `json:"mode,omitempty"` // "form" or "url"
	Schema  any    `json:"schema,omitempty"`
	URL     string `json:"url,omitempty"`
	// ElicitationID is the internally-generated correlation ID used to route
	// a ResumeElicitation response back to this specific request (see
	// elicitationHandler). It is always set and always unique, regardless of
	// whether the originating MCP server supplied its own wire ID: two
	// independent servers can coincidentally reuse the same wire ID, so that
	// value is never used for routing (#3584).
	ElicitationID string `json:"elicitation_id,omitempty"`
	// ServerElicitationID is the MCP wire-protocol elicitationId as supplied
	// by the originating server, if any (URL-mode elicitations only; form
	// elicitations leave it empty). It is informational only — useful for
	// correlating with server-side logs — and must never be used as a
	// routing key.
	ServerElicitationID string `json:"server_elicitation_id,omitempty"`
	// SessionID is the session (or sub-session) on whose behalf this
	// elicitation was raised. A detached background job's sub-session ID
	// differs from its parent/foreground session, which lets consumers (see
	// the TUI supervisor) tell apart a foreground stream's own elicitation
	// from a still-live background job's when the foreground stream stops
	// (#3584 review item 4).
	SessionID string         `json:"session_id,omitempty"`
	Meta      map[string]any `json:"meta,omitempty"`
}

type ElicitationRequestHandler func(ctx context.Context, message string, schema map[string]any) (map[string]any, error)

type ElicitationResult struct {
	Action  tools.ElicitationAction
	Content map[string]any // The submitted form data (only present when action is "accept")
}

type ErrorEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"`
	Error     string `json:"error"`
	Code      string `json:"code,omitempty"`
}

type EvaluationUsageEvent struct {
	AgentContext

	Type       string              `json:"type"`
	SessionID  string              `json:"session_id"`
	Evaluation *session.Evaluation `json:"evaluation"`
}

type Event interface {
	GetAgentName() string
}

type EventObserver interface {
	// OnRunStart fires once when [LocalRuntime.RunStream] begins, before
	// any event is dispatched. Use it for one-shot lifecycle work like
	// persisting initial session metadata.
	OnRunStart(ctx context.Context, sess *session.Session)
	// OnEvent fires once per event, after the runtime emits it but
	// before the consumer's channel receives it. Observers cannot
	// modify or suppress events (a future extension may relax this);
	// to drop an event from persistence, simply ignore it inside
	// OnEvent.
	OnEvent(ctx context.Context, sess *session.Session, event Event)
}

type EventSink interface {
	// Emit delivers an event to the sink. The default implementation
	// preserves back-pressure: if the consumer is slow, Emit blocks
	// until the event can be delivered. Implementations must still be
	// panic-safe so a closed channel does not crash the caller.
	Emit(event Event)
}

type EventSinkFunc func(Event)

type HookBlockedEvent struct {
	AgentContext

	Type           string         `json:"type"`
	ToolCall       tools.ToolCall `json:"tool_call"`
	ToolDefinition tools.Tool     `json:"tool_definition"`
	Message        string         `json:"message"`
}

type HookFinishedEvent struct {
	AgentContext

	Type       string          `json:"type"`
	SessionID  string          `json:"session_id"`
	HookEvent  hooks.EventType `json:"hook_event"`
	DurationMs int64           `json:"duration_ms"`
	Allowed    bool            `json:"allowed"`
	Error      string          `json:"error,omitempty"`
	Message    string          `json:"message,omitempty"`
}

type HookStartedEvent struct {
	AgentContext

	Type      string          `json:"type"`
	SessionID string          `json:"session_id"`
	HookEvent hooks.EventType `json:"hook_event"`
}

type LiveSession struct {
	SessionID    string `json:"session_id"`
	AgentName    string `json:"agent_name"`
	InputTokens  int64  `json:"input_tokens"`
	OutputTokens int64  `json:"output_tokens"`
	ContextLimit int64  `json:"context_limit"`
	// Current marks the caller's current root session. It is listed even
	// while idle (no active stream), unlike child rows which exist only
	// while their RunStream is live.
	Current bool `json:"current"`

	// CompactionModel is the identity ("provider/model") of the row's agent
	// dedicated compaction model, set only when it actually caps ContextLimit
	// below the primary model's own window. Render-unused in the /context
	// dialog (the header's single cap statement is authoritative there); kept
	// on the struct as part of the JSON/API surface for other consumers.
	CompactionModel string `json:"compaction_model,omitempty"`
	// PrimaryContextLimit is the primary model's own context window, set
	// only alongside CompactionModel. Render-unused today (see CompactionModel).
	PrimaryContextLimit int64 `json:"primary_context_limit,omitempty"`
}

type LoadTeamRequest struct {
	Source         config.Source         `json:"-"`
	ModelOverrides []string              `json:"model_overrides,omitempty"`
	PromptFiles    []string              `json:"prompt_files,omitempty"`
	RunConfig      *config.RuntimeConfig `json:"-"`
}

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

type MCPInitFinishedEvent struct {
	AgentContext

	Type string `json:"type"`
}

type MCPInitStartedEvent struct {
	AgentContext

	Type string `json:"type"`
}

type MaxIterationsReachedEvent struct {
	AgentContext

	Type          string `json:"type"`
	MaxIterations int    `json:"max_iterations"`
}

type MessageAddedEvent struct {
	AgentContext

	Type      string           `json:"type"`
	SessionID string           `json:"session_id"`
	Message   *session.Message `json:"-"`
	// Completion metadata remains available when Message is omitted on the wire.
	AssistantMessageEmpty bool `json:"assistant_message_empty,omitempty"`
	HasToolCalls          bool `json:"has_tool_calls,omitempty"`
}

type MessageQueue interface {
	// Enqueue adds a message to the queue. Returns false if the queue is
	// full or the context is cancelled.
	Enqueue(ctx context.Context, msg QueuedMessage) bool
	// Dequeue removes and returns the next message from the queue.
	// Returns the message and true, or a zero value and false if the
	// queue is empty. Must not block.
	Dequeue(ctx context.Context) (QueuedMessage, bool)
	// Drain returns all pending messages and removes them from the queue.
	// Must not block — if the queue is empty it returns nil.
	Drain(ctx context.Context) []QueuedMessage
}

type MessageTransform func(ctx context.Context, in *hooks.Input, msgs []chat.Message) ([]chat.Message, error)

type MessageUsage struct {
	chat.Usage

	Cost         float64
	Model        string
	FinishReason chat.FinishReason `json:"finish_reason,omitempty"`
}

type ModelFallbackEvent struct {
	AgentContext

	Type          string `json:"type"`
	FailedModel   string `json:"failed_model"`
	FallbackModel string `json:"fallback_model"`
	Reason        string `json:"reason"`
	Attempt       int    `json:"attempt"`      // Current attempt number (1-indexed)
	MaxAttempts   int    `json:"max_attempts"` // Total attempts allowed for this model
}

type ModelStore interface {
	GetModel(ctx context.Context, id modelsdev.ID) (*modelsdev.Model, error)
	GetDatabase(ctx context.Context) (*modelsdev.Database, error)
}

type Opt func(*LocalRuntime)

type PartialToolCallEvent struct {
	AgentContext

	Type           string         `json:"type"`
	ToolCall       tools.ToolCall `json:"tool_call"`
	ToolDefinition *tools.Tool    `json:"tool_definition,omitempty"`
}

type PausedEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"`
}

type PendingMessageCanceler interface {
	CancelSteer(ctx context.Context, id string) bool
	CancelFollowUp(ctx context.Context, id string) bool
}

type PermissionsInfo struct {
	Allow []string
	Ask   []string
	Deny  []string
}

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

type PlanChangedEvent struct {
	AgentContext

	Type   string `json:"type"`
	Scope  string `json:"scope"`
	Name   string `json:"name"`
	Action string `json:"action"`
	// Version is the plan version after a write, or the guard version of a
	// guarded delete (0 when unguarded).
	Version int `json:"version,omitempty"`
}

type QueueStatus struct {
	SteerDepth       int
	SteerCapacity    int
	FollowupDepth    int
	FollowupCapacity int
}

type QueuedMessage struct {
	ID           string
	Content      string
	MultiContent []chat.MessagePart
}

type RAGIndexingCompletedEvent struct {
	AgentContext

	Type         string `json:"type"`
	RAGName      string `json:"rag_name"`
	StrategyName string `json:"strategy_name"`
}

type RAGIndexingProgressEvent struct {
	AgentContext

	Type         string `json:"type"`
	RAGName      string `json:"rag_name"`
	StrategyName string `json:"strategy_name"`
	Current      int    `json:"current"`
	Total        int    `json:"total"`
}

type RAGIndexingStartedEvent struct {
	AgentContext

	Type         string `json:"type"`
	RAGName      string `json:"rag_name"`
	StrategyName string `json:"strategy_name"`
}

type RecallHandler func(ctx context.Context, msg QueuedMessage) bool

type ResumeRequest = toolexec.ResumeRequest

type ResumeType = toolexec.ResumeType

type RoutingDecisionEvent struct {
	AgentContext

	Type      string                   `json:"type"`
	SessionID string                   `json:"session_id"`
	Decision  *session.RoutingDecision `json:"decision"`
}

type Runtime interface {
	// CurrentAgentInfo returns information about the currently active agent
	CurrentAgentInfo(ctx context.Context) CurrentAgentInfo
	// CurrentAgentName returns the name of the currently active agent
	CurrentAgentName(ctx context.Context) string
	// SetCurrentAgent sets the currently active agent for subsequent user messages
	SetCurrentAgent(ctx context.Context, agentName string) error
	// CurrentAgentTools returns the tools for the active agent
	CurrentAgentTools(ctx context.Context) ([]tools.Tool, error)
	// CurrentAgentToolsetStatuses returns lifecycle status for each toolset of
	// the active agent (name, kind, state, last error, restart count).
	// Used by the /tools dialog. Best-effort: toolsets that don't expose
	// state appear with State == StateStopped/Ready as appropriate.
	CurrentAgentToolsetStatuses() []tools.ToolsetStatus

	// RestartToolset finds the named toolset on the active agent and asks
	// its supervisor to drop the current session and reconnect. Returns
	// an error if no toolset matches name or the toolset does not
	// implement tools.Restartable.
	RestartToolset(ctx context.Context, name string) error
	// EmitStartupInfo emits initial agent, team, and toolset information for immediate display.
	// When sess is non-nil and contains token data, a TokenUsageEvent is also emitted
	// so the UI can display context usage percentage on session restore.
	EmitStartupInfo(ctx context.Context, sess *session.Session, events EventSink)
	// EmitAgentInfo emits up-to-date agent and team info (model, thinking
	// level, description) without re-running heavier startup work such as
	// tool discovery. Used to refresh the UI after a lightweight change like
	// cycling the thinking level, avoiding the tool-count flicker that
	// re-emitting full startup info would cause.
	EmitAgentInfo(ctx context.Context, events EventSink)
	// ResetStartupInfo resets the startup info emission flag, allowing re-emission
	ResetStartupInfo()
	// RunStream starts the agent's interaction loop and returns a channel of events.
	// Consumers must drain it to closure before releasing turn ownership, even
	// after cancellation. Cancel the supplied context before draining on errors.
	RunStream(ctx context.Context, sess *session.Session) <-chan Event
	// Run starts the agent's interaction loop and returns the final messages
	Run(ctx context.Context, sess *session.Session) ([]session.Message, error)
	// Resume allows resuming execution after user confirmation.
	// The ResumeRequest carries the decision type and an optional reason (for rejections).
	Resume(ctx context.Context, req ResumeRequest)
	// ResumeElicitation sends an elicitation response back to a waiting
	// elicitation request. elicitationID correlates the response with a
	// specific concurrent request (see ElicitationRequestEvent.ElicitationID);
	// omit it (or pass "") to fall back to resolving the sole pending
	// request, for backward compatibility with older clients. The parameter
	// is variadic — rather than a required 4th positional argument — purely
	// so pre-#3584 callers of this interface method keep compiling unchanged;
	// implementations should treat more than one value as a caller error and
	// use only the first.
	ResumeElicitation(_ context.Context, action tools.ElicitationAction, content map[string]any, elicitationID ...string) error
	// SessionStore returns the session store for browsing/loading past sessions.
	// Returns nil if no persistent session store is configured.
	SessionStore() session.Store

	// Summarize generates a summary for the session
	Summarize(ctx context.Context, sess *session.Session, additionalPrompt string, events EventSink)

	// PermissionsInfo returns the team-level permission patterns (allow/ask/deny).
	// Returns nil if no permissions are configured.
	PermissionsInfo() *PermissionsInfo

	// ReadSkillContent loads a skill for sess without executing embedded commands.
	ReadSkillContent(ctx context.Context, sess *session.Session, name string) (string, error)

	// CurrentAgentSkillsToolset returns the skills toolset for the current agent, or nil if skills are not enabled.
	CurrentAgentSkillsToolset() *skills.ToolSet

	// RunSkillFork executes a `context: fork` skill as an isolated
	// sub-session of sess. Used by the run_skill tool and the App's
	// slash-command path. Returns a ToolCallResult carrying the sub-agent's
	// last assistant message, or a user-facing error reason; err is non-nil
	// only for unexpected runtime failures.
	RunSkillFork(ctx context.Context, sess *session.Session, args skills.RunSkillArgs, events EventSink) (*tools.ToolCallResult, error)

	// CurrentMCPPrompts returns MCP prompts available from the current agent's toolsets.
	// Returns an empty map if no MCP prompts are available.
	CurrentMCPPrompts(ctx context.Context) map[string]tools.PromptInfo

	// ExecuteMCPPrompt executes a named MCP prompt with the given arguments.
	ExecuteMCPPrompt(ctx context.Context, promptName string, arguments map[string]string) (string, error)

	// UpdateSessionTitle persists a new title for the current session.
	UpdateSessionTitle(ctx context.Context, sess *session.Session, title string) error

	// TitleGenerator returns a generator for automatic session titles, or nil
	// if the runtime does not support local title generation (e.g. remote
	// runtimes) or no configured model is a usable title candidate.
	TitleGenerator(ctx context.Context) *sessiontitle.Generator

	// Steer enqueues a user message for urgent mid-turn injection into the
	// running agent loop. Returns an error if the queue is full or steering
	// is not available.
	Steer(ctx context.Context, msg QueuedMessage) error
	// FollowUp enqueues a message for end-of-turn processing. Each follow-up
	// gets a full undivided agent turn. Returns an error if the queue is full.
	FollowUp(ctx context.Context, msg QueuedMessage) error

	// SetAgentModel sets a model override for the named agent.
	// modelRef can be:
	//   - "" (empty) to clear the override and use the agent's default model
	//   - A model name from the config (e.g., "my_fast_model")
	//   - An inline spec (e.g., "openai/gpt-4o")
	// Returns [ErrUnsupported] for runtimes that don't expose model
	// switching (e.g. remote runtimes, where the server owns the choice).
	SetAgentModel(ctx context.Context, agentName, modelRef string) error

	// CycleAgentThinkingLevel advances the named agent's thinking-effort
	// level to the next value in its provider's cycle (wrapping around),
	// applies it as a runtime model override, and returns the newly
	// selected level. Returns [ErrUnsupported] for runtimes that can't
	// switch models (e.g. remote runtimes) or for models that don't
	// support thinking-effort selection.
	CycleAgentThinkingLevel(ctx context.Context, agentName string) (effort.Level, error)

	// SetAgentThinkingLevel sets the named agent's thinking-effort level to
	// the requested value, applies it as a runtime model override, and
	// returns the applied level. The level must be one the current model
	// supports. Returns [ErrUnsupported] for runtimes that can't switch
	// models (e.g. remote runtimes) or for models that don't support
	// thinking-effort selection.
	SetAgentThinkingLevel(ctx context.Context, agentName string, level effort.Level) (effort.Level, error)

	// AvailableModels returns the models the user can pick from in the
	// /model picker. Returns nil for runtimes that don't expose model
	// switching; see SupportsModelSwitching for a cheap pre-check.
	AvailableModels(ctx context.Context) []modelcatalog.ModelChoice

	// SupportsModelSwitching reports whether SetAgentModel and
	// AvailableModels are wired for this runtime. Use it to gate UI
	// affordances (e.g. show /model in the menu) without paying the
	// cost of AvailableModels.
	SupportsModelSwitching() bool

	// OnToolsChanged registers a handler invoked outside of any RunStream
	// when a toolset reports a tool list change (e.g. after an MCP
	// ToolListChanged notification). A nil handler unregisters. Runtimes
	// that don't emit such events can implement this as a no-op.
	OnToolsChanged(handler func(Event))

	// OnBackgroundEvent registers a handler invoked outside of any RunStream
	// for events surfaced from detached background work (e.g. token usage
	// from background agent tasks started via run_background_agent), which
	// has no live event channel of its own. Runtimes that don't run local
	// background work can implement this as a no-op.
	OnBackgroundEvent(handler func(Event))

	// OnElicitationRequest registers a handler invoked whenever an MCP
	// toolset raises an elicitation request, regardless of which stream
	// (foreground or a detached background job) is currently "active" for
	// the runtime's internal elicitation bridge. This is the reliable
	// delivery route for background-job elicitations (#3584); runtimes
	// that don't run local background work can implement this as a no-op.
	OnElicitationRequest(handler func(Event))

	// QueueStatus returns the current depth and capacity of message queues
	QueueStatus() QueueStatus

	// TogglePause toggles whether the run loop is paused at iteration
	// boundaries. Returns the new state (true if now paused). Returns
	// [ErrUnsupported] for runtimes that don't expose pause control.
	TogglePause(ctx context.Context) (paused bool, err error)

	// Close releases resources held by the runtime (e.g., background
	// agents and pending lifecycles). The session store is *not* closed
	// here: it is supplied by the embedder via WithSessionStore and may
	// be shared with other runtimes (e.g. the TUI's spawner reuses the
	// same store across spawned sessions). Embedders that own the store
	// must close it themselves.
	Close() error
}

type SessionCompactionEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	// Outcome qualifies a "completed" status: "applied" (a summary
	// replaced part of the history), "skipped" (no-op: nothing to
	// compact or the model produced no summary), or "failed" (an error
	// was emitted). Empty on "started" events and events from older
	// servers; consumers should treat empty as "applied" for backward
	// compatibility.
	Outcome string `json:"outcome,omitempty"`
}

type SessionRecoveredEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
}

type SessionScoped interface {
	GetSessionID() string
}

type SessionSummaryEvent struct {
	AgentContext

	Type           string      `json:"type"`
	SessionID      string      `json:"session_id"`
	Summary        string      `json:"summary"`
	FirstKeptEntry int         `json:"first_kept_entry,omitempty"`
	Cost           float64     `json:"cost,omitempty"`
	Model          string      `json:"model,omitempty"`
	Usage          *chat.Usage `json:"usage,omitempty"`
	// contains filtered or unexported fields
}

type SessionTitleEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id"`
	Title     string `json:"title"`
}

type ShellOutputEvent struct {
	AgentContext

	Type      string `json:"type"`
	CommandID string `json:"command_id,omitempty"`
	Command   string `json:"command,omitempty"`
	Output    string `json:"output,omitempty"`
	Error     string `json:"error,omitempty"`
	Done      bool   `json:"done,omitempty"`
}

type StreamStartedEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"`
}

type StreamStoppedEvent struct {
	AgentContext

	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"`
	Reason    string `json:"reason,omitempty"`
	// FinishReason is the terminal model result, independent of content or usage.
	FinishReason chat.FinishReason `json:"finish_reason,omitempty"`
}

type SubSessionCompletedEvent struct {
	AgentContext

	Type            string `json:"type"`
	ParentSessionID string `json:"parent_session_id"`
	SubSession      any    `json:"sub_session"` // *session.Session
}

type SubSessionConfig struct {
	// Task is the user-facing task description.
	Task string
	// ExpectedOutput is an optional description of what the sub-agent should produce.
	ExpectedOutput string
	// SystemMessage, when non-empty, replaces the default task-based system
	// message. This is used by skill sub-agents whose system prompt is the
	// skill content itself rather than the team delegation boilerplate.
	SystemMessage string
	// AgentName is the name of the agent that will execute the sub-session.
	AgentName string
	// Title is a human-readable label for the sub-session (e.g. "Transferred task").
	Title string
	// ToolsApproved overrides whether tools are pre-approved in the child session.
	//
	// Deprecated: prefer SafetyPolicy; kept for callers that only know
	// the legacy blanket-approval flag.
	ToolsApproved bool
	// SafetyPolicy is the safety mode the child session inherits from
	// its parent, so a Balanced/Autonomous opt-in (or a Strict pin)
	// survives task transfers, skills, and background agents.
	SafetyPolicy session.SafetyPolicy
	// Permissions defines session-level tool permission overrides.
	Permissions *session.PermissionsConfig
	// NonInteractive marks the child session as running without a user present
	// (e.g. MCP server, A2A adapter, background agent). This causes the runtime
	// to auto-stop on max iterations instead of blocking for user input.
	NonInteractive bool
	// PinAgent, when true, pins the child session to AgentName via
	// session.WithAgentName. This is required for concurrent background
	// tasks that must not share the runtime's mutable currentAgent field.
	PinAgent bool
	// AllowHandoffs permits intentional routing inside a pinned skill fork.
	AllowHandoffs bool
	// ImplicitUserMessage, when non-empty, overrides the default "Please proceed."
	// user message sent to the child session. This allows callers like skill
	// sub-agents to pass the task description as the user message.
	ImplicitUserMessage string
	// ExcludedTools lists tool names that should be filtered out of the agent's
	// tool list for the child session. This prevents recursive tool calls
	// (e.g. run_skill calling itself in a skill sub-session).
	ExcludedTools []string
	// AllowedTools, when non-empty, restricts the child session's inherited
	// agent tools to those whose names match an entry (glob or exact). Used by
	// fork-mode skills that declare an allowed-tools list. ExtraToolSets are
	// exempt from this filter.
	AllowedTools []string
	// ExtraToolSets are additional toolsets exposed in the child session on
	// top of the agent's own toolsets. Used by fork-mode skills that declare
	// assistive toolsets.
	ExtraToolSets []tools.ToolSet
	// DisableStructuredOutput exempts the child session from tool-mode
	// structured-output enforcement. Set only by fork-mode skills, whose
	// answer is free-form text for the calling agent; ordinary delegations
	// and background agents stay enforced.
	DisableStructuredOutput bool
	// DelegationLineage is the chain of agents that delegated to produce this
	// child session (parent lineage plus the delegating caller), as computed
	// by validateDelegation. Set only for true delegation edges
	// (transfer_task, run_background_agent); when nil the child inherits the
	// parent session's lineage unchanged, so non-delegation sub-sessions
	// (e.g. skills) preserve ancestry without adding an edge.
	DelegationLineage []string
}

type TeamInfoEvent struct {
	AgentContext

	Type            string         `json:"type"`
	AvailableAgents []AgentDetails `json:"available_agents"`
	CurrentAgent    string         `json:"current_agent"`
}

type Telemetry interface {
	// RecordSessionStart is fired once at the top of RunStream.
	RecordSessionStart(ctx context.Context, agentName, sessionID string)
	// RecordSessionEnd is fired when the run loop exits.
	RecordSessionEnd(ctx context.Context)
	// RecordError is fired when the run loop or a model call surfaces a fatal error.
	RecordError(ctx context.Context, message string)
	// RecordToolCall is fired after every tool invocation, regardless of outcome.
	RecordToolCall(ctx context.Context, toolName, sessionID, agentName string, duration time.Duration, err error)
	// RecordTokenUsage reports per-call tokens and cost, not cumulative session totals.
	RecordTokenUsage(ctx context.Context, model string, inputTokens, outputTokens int64, cost float64)
}

type TokenUsageEvent struct {
	AgentContext

	Type                  string `json:"type"`
	SessionID             string `json:"session_id"`
	Usage                 *Usage `json:"usage"`
	AssistantMessageEmpty bool   `json:"assistant_message_empty,omitempty"`
}

type ToolCallConfirmationEvent struct {
	AgentContext

	Type           string         `json:"type"`
	ToolCall       tools.ToolCall `json:"tool_call"`
	ToolDefinition tools.Tool     `json:"tool_definition"`
	// Metadata carries arbitrary key/value annotations attached to the
	// confirmation prompt. Toolsets contribute static metadata via
	// [tools.Tool.Metadata]; a permission_request hook can enrich it per
	// call. nil when neither source supplied any.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type ToolCallEvent struct {
	AgentContext

	Type           string         `json:"type"`
	ToolCall       tools.ToolCall `json:"tool_call"`
	ToolDefinition tools.Tool     `json:"tool_definition"`
}

type ToolCallOutputEvent struct {
	AgentContext

	Type           string     `json:"type"`
	ToolCallID     string     `json:"tool_call_id"`
	ToolDefinition tools.Tool `json:"tool_definition"`
	Output         string     `json:"output"`
}

type ToolCallResponseEvent struct {
	AgentContext

	Type           string                `json:"type"`
	ToolCallID     string                `json:"tool_call_id"`
	ToolDefinition tools.Tool            `json:"tool_definition"`
	Response       string                `json:"response"`
	Result         *tools.ToolCallResult `json:"result,omitempty"`
}

type ToolCallsRetractedEvent struct {
	AgentContext

	Type        string   `json:"type"`
	ToolCallIDs []string `json:"tool_call_ids"`
}

type ToolHandlerFunc func(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, events EventSink, rt tools.Runtime) (*tools.ToolCallResult, error)

type ToolsetInfoEvent struct {
	AgentContext

	Type           string `json:"type"`
	AvailableTools int    `json:"available_tools"`
	Loading        bool   `json:"loading"`
}

type Usage struct {
	InputTokens   int64         `json:"input_tokens"`
	OutputTokens  int64         `json:"output_tokens"`
	ContextLength int64         `json:"context_length"`
	ContextLimit  int64         `json:"context_limit"`
	Cost          float64       `json:"cost"`
	LastMessage   *MessageUsage `json:"last_message,omitempty"`
	// SnapshotOnly refreshes totals without reporting another chat response.
	SnapshotOnly bool `json:"snapshot_only,omitempty"`
	// CompactionThreshold is the fraction of the context window at which
	// auto-compaction triggers for the agent that produced this snapshot,
	// so UIs can color context gauges against it. 0 means unknown;
	// consumers should fall back to [compaction.DefaultThreshold].
	CompactionThreshold float64 `json:"compaction_threshold,omitempty"`
}

type UserMessageEvent struct {
	AgentContext

	MessageID       string             `json:"message_id,omitempty"`
	Type            string             `json:"type"`
	Message         string             `json:"message"`
	MultiContent    []chat.MessagePart `json:"multi_content,omitempty"`
	SessionID       string             `json:"session_id"`
	SessionPosition int                `json:"session_position"` // Index in session.Messages, -1 if unknown
}

type WarningEvent struct {
	AgentContext

	Type    string `json:"type"`
	Message string `json:"message"`
}