runtime

type AgentChoiceEvent struct {
	AgentContext

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

type AgentChoiceReasoningEvent struct {
	AgentContext

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

type AgentContext struct {
	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"`
	Commands    types.Commands `json:"commands,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"`
}

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 Client struct {
	// contains filtered or unexported fields
}

type ClientOption func(*Client)

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

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 string         `json:"elicitation_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"`
	Error string `json:"error"`
}

type ErrorResponse struct {
	Error string `json:"error"`
}

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 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 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:"-"`
}

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 MessageUsage struct {
	chat.Usage

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

type ModelChoice struct {
	// Name is the display name (config key)
	Name string
	// Ref is the model reference used internally (e.g., "my_model" or "openai/gpt-4o")
	Ref string
	// Provider is the provider name (e.g., "openai", "anthropic")
	Provider string
	// Model is the specific model name (e.g., "gpt-4o", "claude-sonnet-4-0")
	Model string
	// IsDefault indicates this is the agent's configured default model
	IsDefault bool
	// IsCurrent indicates this is the currently active model for the agent
	IsCurrent bool
	// IsCustom indicates this is a custom model from the session history (not from config)
	IsCustom bool
	// IsCatalog indicates this is a model from the models.dev catalog
	IsCatalog bool

	// Family is the model family (e.g., "claude", "gpt").
	Family string
	// InputCost is the price (in USD) per 1M input tokens.
	InputCost float64
	// OutputCost is the price (in USD) per 1M output tokens.
	OutputCost float64
	// CacheReadCost is the price (in USD) per 1M cached input tokens.
	CacheReadCost float64
	// CacheWriteCost is the price (in USD) per 1M cache-write tokens.
	CacheWriteCost float64
	// ContextLimit is the maximum context window size in tokens.
	ContextLimit int
	// OutputLimit is the maximum number of tokens the model can produce
	// in a single response.
	OutputLimit int64
	// InputModalities lists the input modalities supported by the model
	// (e.g., "text", "image", "audio").
	InputModalities []string
	// OutputModalities lists the output modalities the model can produce.
	OutputModalities []string
}

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, modelID string) (*modelsdev.Model, error)
	GetDatabase(ctx context.Context) (*modelsdev.Database, error)
}

type ModelSwitcher interface {
	// SetAgentModel sets a model override for the specified 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 model spec (e.g., "openai/gpt-4o")
	SetAgentModel(ctx context.Context, agentName, modelRef string) error

	// AvailableModels returns the list of models available for selection.
	// This includes all models defined in the config, with the current agent's
	// default model marked as IsDefault.
	AvailableModels(ctx context.Context) []ModelChoice
}

type ModelSwitcherConfig struct {
	// Models is the map of model names to configurations from the loaded config
	Models map[string]latest.ModelConfig
	// Providers is the map of custom provider configurations
	Providers map[string]latest.ProviderConfig
	// ModelsGateway is the gateway URL if configured
	ModelsGateway string
	// EnvProvider provides access to environment variables
	EnvProvider environment.Provider
	// AgentDefaultModels maps agent names to their configured default model references
	AgentDefaultModels map[string]string
}

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 PermissionsInfo struct {
	Allow []string
	Ask   []string
	Deny  []string
}

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

type QueuedMessage struct {
	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 RemoteClient interface {
	// GetAgent retrieves an agent configuration by ID
	GetAgent(ctx context.Context, id string) (*latest.Config, error)

	// CreateSession creates a new session
	CreateSession(ctx context.Context, sessTemplate *session.Session) (*session.Session, error)

	// ResumeSession resumes a paused session with optional rejection reason or tool name
	ResumeSession(ctx context.Context, id, confirmation, reason, toolName string) error

	// ResumeElicitation sends an elicitation response
	ResumeElicitation(ctx context.Context, sessionID string, action tools.ElicitationAction, content map[string]any) error

	// RunAgent executes an agent and returns a channel of streaming events
	RunAgent(ctx context.Context, sessionID, agent string, messages []api.Message) (<-chan Event, error)

	// RunAgentWithAgentName executes an agent with a specific agent name
	RunAgentWithAgentName(ctx context.Context, sessionID, agent, agentName string, messages []api.Message) (<-chan Event, error)

	// SteerSession injects user messages into a running session mid-turn
	SteerSession(ctx context.Context, sessionID string, messages []api.Message) error

	// FollowUpSession queues messages for end-of-turn processing
	FollowUpSession(ctx context.Context, sessionID string, messages []api.Message) error

	// UpdateSessionTitle updates the title of a session
	UpdateSessionTitle(ctx context.Context, sessionID, title string) error

	// GetAgentToolCount returns the number of tools available for an agent
	GetAgentToolCount(ctx context.Context, agentFilename, agentName string) (int, error)
}

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

type RemoteRuntimeOption func(*RemoteRuntime)

type ResumeRequest = toolexec.ResumeRequest

type ResumeType = toolexec.ResumeType

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() string
	// SetCurrentAgent sets the currently active agent for subsequent user messages
	SetCurrentAgent(agentName string) error
	// CurrentAgentTools returns the tools for the active agent
	CurrentAgentTools(ctx context.Context) ([]tools.Tool, 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 chan Event)
	// ResetStartupInfo resets the startup info emission flag, allowing re-emission
	ResetStartupInfo()
	// RunStream starts the agent's interaction loop and returns a channel of events
	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
	ResumeElicitation(_ context.Context, action tools.ElicitationAction, content map[string]any) 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 chan Event)

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

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

	// 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]mcptools.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).
	TitleGenerator() *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(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(msg QueuedMessage) error

	// Close releases resources held by the runtime (e.g., session store connections).
	Close() error
}

type SessionCompactionEvent struct {
	AgentContext

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

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"`
}

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"`
	Output string `json:"output"`
}

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"`
}

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.
	ToolsApproved 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
	// 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
}

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 is fired after each model response that reports usage.
	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"`
}

type ToolCallConfirmationEvent struct {
	AgentContext

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

type ToolCallEvent struct {
	AgentContext

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

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 ToolHandlerFunc func(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, events chan Event) (*tools.ToolCallResult, error)

type ToolsChangeSubscriber interface {
	OnToolsChanged(handler func(Event))
}

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"`
}

type UserMessageEvent struct {
	AgentContext

	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"`
}