agent

type ActiveTurnInfo struct {
	TurnID       string
	AgentID      string
	SessionKey   string
	Channel      string
	ChatID       string
	UserMessage  string
	Phase        TurnPhase
	Iteration    int
	StartedAt    time.Time
	Depth        int
	ParentTurnID string
	ChildTurnIDs []string
}

type AgentContextDefinition struct {
	Agent *AgentPromptDefinition `json:"agent,omitempty"`
	Soul  *SoulDefinition        `json:"soul,omitempty"`
	User  *UserDefinition        `json:"user,omitempty"`
}

type AgentDescriptor struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

type AgentFrontmatter struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Tools       []string       `json:"tools,omitempty"`
	Model       string         `json:"model,omitempty"`
	MaxTurns    *int           `json:"maxTurns,omitempty"`
	Skills      []string       `json:"skills,omitempty"`
	MCPServers  []string       `json:"mcpServers,omitempty"`
	Fields      map[string]any `json:"-"`
}

type AgentInstance struct {
	ID   string
	Name string
	// Model is the agent's model selection — an exact target
	// "instance-id/model-id" or a model route name — taken from its AGENT.md
	// frontmatter, its agents.list entry or agents.defaults.model_name, in
	// that order. Empty when none is set.
	Model     string
	Workspace string
	// ModuleSummaries are one-line capability summaries for each enabled
	// module, composed into the system prompt so the agent knows what its
	// installed modules can do without loading their full documentation.
	ModuleSummaries []string
	// ModuleKnowledge composes a selected module's overlay and skills for one
	// turn. It is set at init, where module discovery already happens, so a
	// turn never pays to re-describe every installed module.
	//
	// nil when no module is installed, and it returns empty for a turn with no
	// selection -- an installed module costs one line of capability summary
	// until someone points the agent at it.
	ModuleKnowledge func(moduleID string) (overlays string, skills string, warnings []string)
	MaxIterations   int
	MaxTokens       int
	Temperature     float64
	// ThinkingLevel is the extended-thinking level of the agent's first
	// target, from its instance's runtime settings.
	ThinkingLevel             ThinkingLevel
	ThinkingLevelConfigured   bool
	ContextWindow             int
	SummarizeMessageThreshold int
	SummarizeTokenPercent     int
	// Provider is the provider of Candidates[0]; nil when the agent has no
	// model.
	Provider           providers.LLMProvider
	Sessions           session.SessionStore
	ContextBuilder     *ContextBuilder
	Tools              *tools.ToolRegistry
	Definition         AgentContextDefinition
	Subagents          *config.SubagentsConfig
	SkillsFilter       []string
	MCPServerAllowlist map[string]struct{}
	// Candidates are the targets Model resolved to, in failover order: one
	// for an exact target, the route's targets for a route. Empty when the
	// agent has no model.
	Candidates []providers.FallbackCandidate
	// ImageCandidates are the targets of agents.defaults.image_model, which
	// turns carrying images are rerouted to.
	ImageCandidates []providers.FallbackCandidate

	// Router is non-nil when model routing is configured and the light model
	// resolved. It scores each incoming message and decides whether to route
	// to LightCandidates or stay with Candidates.
	Router *routing.Router
	// LightCandidates are the targets of the routing light model selection,
	// resolved at agent creation.
	LightCandidates []providers.FallbackCandidate
	// LightProvider is the provider of LightCandidates[0]. It is only used
	// when routing selects the light tier for a turn.
	LightProvider providers.LLMProvider
	// CandidateProviders and CandidateConfigs hold the provider and the
	// request spec of every candidate above, keyed by
	// FallbackCandidate.StableKey(). A request spec carries the target
	// instance's runtime settings: thinking level, streaming, RPM, timeouts.
	CandidateProviders map[string]providers.LLMProvider
	CandidateConfigs   map[string]*providers.CallSpec
	// contains filtered or unexported fields
}

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

type AgentLoopOption func(*AgentLoop)

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

type AgentPromptDefinition struct {
	Path           string           `json:"path"`
	Raw            string           `json:"raw"`
	Body           string           `json:"body"`
	RawFrontmatter string           `json:"raw_frontmatter,omitempty"`
	Frontmatter    AgentFrontmatter `json:"frontmatter"`
	FrontmatterErr string           `json:"frontmatter_error,omitempty"`
}

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

type ApprovalDecision struct {
	Approved bool   `json:"approved"`
	Reason   string `json:"reason,omitempty"`
}

type ApprovalRequestedPayload struct {
	ApprovalID string         `json:"approval_id"`
	ActionID   string         `json:"action_id"`
	Tool       string         `json:"tool"`
	Parameters map[string]any `json:"parameters,omitempty"`
	Reason     string         `json:"reason"`
	State      string         `json:"state"` // "pending", "approved", "rejected", "cancelled"
}

type ApprovalResolvedPayload struct {
	ApprovalID string `json:"approval_id"`
	Resolution string `json:"resolution"` // "approved", "rejected", "cancelled"
	Reason     string `json:"reason,omitempty"`
}

type ArtifactProducedPayload struct {
	ArtifactID  string `json:"artifact_id"`
	Kind        string `json:"kind"`
	Module      string `json:"module"`
	Locator     string `json:"locator"`
	MediaType   string `json:"media_type"`
	Bytes       int64  `json:"bytes"`
	Digest      string `json:"digest"`
	Title       string `json:"title,omitempty"`
	ReviewState string `json:"review_state,omitempty"` // "draft", "verified", "reviewed", "approved"
	ToolName    string `json:"tool_name,omitempty"`
}

type AssembleRequest struct {
	SessionKey string // session identifier
	Budget     int    // context window in tokens
	MaxTokens  int    // max response tokens
}

type AssembleResponse struct {
	History []providers.Message // assembled conversation history for BuildMessagesFromPrompt
	Summary string              // conversation summary embedded into system prompt by BuildMessagesFromPrompt
}

type BuiltinHookFactory func(ctx context.Context, spec config.BuiltinHookConfig) (any, error)

type CompactRequest struct {
	SessionKey string                // session identifier
	Reason     ContextCompressReason // proactive_budget | llm_retry | summarize
	Budget     int                   // context window budget (used for retry aggressive compaction)
}

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

type ContextCompressPayload struct {
	Reason            ContextCompressReason
	DroppedMessages   int
	RemainingMessages int
}

type ContextCompressReason string

type ContextManager interface {
	// Assemble builds budget-aware context from the ContextManager's own storage.
	// Called before BuildMessagesFromPrompt. Returns assembled messages ready for LLM.
	Assemble(ctx context.Context, req *AssembleRequest) (*AssembleResponse, error)

	// Compact compresses conversation history.
	// Called after turn completes (may be async internally) and on context overflow (sync).
	Compact(ctx context.Context, req *CompactRequest) error

	// Ingest records a message into the ContextManager's own storage.
	// Called after each message is persisted to session JSONL.
	Ingest(ctx context.Context, req *IngestRequest) error

	// Clear removes all stored context for a session (messages, summaries, etc.).
	// Called when the user issues /clear or /reset.
	Clear(ctx context.Context, sessionKey string) error
}

type ContextManagerFactory func(cfg json.RawMessage, al *AgentLoop) (ContextManager, error)

type Control int

type DispatchRequest struct {
	SessionKey     string
	InboundContext *bus.InboundContext
	RouteResult    *routing.ResolvedRoute
	SessionScope   *session.SessionScope
	UserMessage    string
	Media          []string
}

type ErrorPayload struct {
	Stage   string
	Message string
}

type FollowUpQueuedPayload struct {
	SourceTool string
	ContentLen int
}

type HookAction string

type HookDecision struct {
	Action HookAction `json:"action"`
	Reason string     `json:"reason,omitempty"`
}

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

type HookMeta struct {
	AgentID      string
	TurnID       string
	ParentTurnID string
	SessionKey   string
	Iteration    int
	TracePath    string
	Source       string
	// contains filtered or unexported fields
}

type HookRegistration struct {
	Name     string
	Priority int
	Source   HookSource
	Hook     any
}

type HookSource uint8

type IngestRequest struct {
	SessionKey string            // session identifier
	Message    providers.Message // the message just persisted
}

type InstanceSelectionResult struct {
	Response       *providers.LLMResponse
	ServedIdentity string
	ExactTarget    string
}

type InterruptKind string

type InterruptReceivedPayload struct {
	Kind       InterruptKind
	Role       string
	ContentLen int
	QueueDepth int
}

type LLMDeltaPayload struct {
	ContentDeltaLen   int
	ReasoningDeltaLen int
}

type LLMHookRequest struct {
	Meta     HookMeta                   `json:"meta"`
	Context  *TurnContext               `json:"context,omitempty"`
	Model    string                     `json:"model"`
	Messages []providers.Message        `json:"messages,omitempty"`
	Tools    []providers.ToolDefinition `json:"tools,omitempty"`
	Options  map[string]any             `json:"options,omitempty"`
}

type LLMHookResponse struct {
	Meta     HookMeta               `json:"meta"`
	Context  *TurnContext           `json:"context,omitempty"`
	Model    string                 `json:"model"`
	Response *providers.LLMResponse `json:"response,omitempty"`
}

type LLMInterceptor interface {
	BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision, error)
	AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision, error)
}

type LLMPhase int

type LLMRequestPayload struct {
	Model         string
	MessagesCount int
	ToolsCount    int
	MaxTokens     int
	Temperature   float64
}

type LLMResponsePayload struct {
	ContentLen   int
	ToolCalls    int
	HasReasoning bool
}

type LLMRetryPayload struct {
	Attempt    int
	MaxRetries int
	Reason     string
	Error      string
	Backoff    time.Duration
}

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

type ModelResolver func(cfg *config.Config, selection string) (*providers.InstanceResolution, error)

type Pipeline struct {
	Bus            interfaces.MessageBus
	Cfg            *config.Config
	ContextManager ContextManager
	Hooks          *HookManager
	Failover       *providers.Failover
	ChannelManager interfaces.ChannelManager
	MediaStore     media.MediaStore
	Steering       any // TODO: *Steering
	// contains filtered or unexported fields
}

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

type ProcessHookOptions struct {
	Command       []string
	Dir           string
	Env           []string
	Observe       bool
	ObserveKinds  []string
	InterceptLLM  bool
	InterceptTool bool
	ApproveTool   bool
}

type PromptBuildRequest struct {
	History []providers.Message
	Summary string

	CurrentMessage string
	Media          []string

	Channel           string
	ChatID            string
	SenderID          string
	SenderDisplayName string

	ActiveSkills []string
	Overlays     []PromptPart

	SuppressDefaultSystemPrompt bool
	SuppressSkillContext        bool
	// ModuleSummaries are one-line capability summaries for the enabled
	// detached modules, carried per turn so the agent's context reflects what
	// is installed right now rather than what was installed at startup.
	ModuleSummaries     []string
	SuppressToolUseRule bool
	AllowedSkills       []string
	AllowedTools        []string
	ToolUseFallback     bool
}

type PromptCachePolicy string

type PromptContributor interface {
	PromptSource() PromptSourceDescriptor
	ContributePrompt(ctx context.Context, req PromptBuildRequest) ([]PromptPart, error)
}

type PromptLayer string

type PromptPart struct {
	ID      string
	Layer   PromptLayer
	Slot    PromptSlot
	Source  PromptSource
	Title   string
	Content string
	Stable  bool
	Cache   PromptCachePolicy
}

type PromptPlacement struct {
	Layer PromptLayer
	Slot  PromptSlot
}

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

type PromptSlot string

type PromptSource struct {
	ID   PromptSourceID
	Name string
	Path string
}

type PromptSourceDescriptor struct {
	ID              PromptSourceID
	Owner           string
	Description     string
	Allowed         []PromptPlacement
	StableByDefault bool
}

type PromptSourceID string

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

type RuntimeEventObserver interface {
	OnRuntimeEvent(ctx context.Context, evt runtimeevents.Event) error
}

type SessionSummarizePayload struct {
	SummarizedMessages int
	KeptMessages       int
	SummaryLen         int
	OmittedOversized   bool
}

type SkillContextSnapshot struct {
	Sequence   int      `json:"sequence"`
	Trigger    string   `json:"trigger"`
	SkillNames []string `json:"skill_names,omitempty"`
}

type SoulDefinition struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type SteeringInjectedPayload struct {
	Count           int
	TotalContentLen int
}

type SteeringMode string

type SubTurnConfig struct {
	Tools        []tools.Tool
	SystemPrompt string
	MaxTokens    int

	// Async controls the result delivery mechanism:
	//
	// When Async = false (synchronous sub-turn):
	//   - The caller blocks until the sub-turn completes
	//   - The result is ONLY returned via the function return value
	//   - The result is NOT delivered to the parent's pendingResults channel
	//   - This prevents double delivery: caller gets result immediately, no need for channel
	//   - Use case: When the caller needs the result immediately to continue execution
	//   - Example: A tool that needs to process the sub-turn result before returning
	//
	// When Async = true (asynchronous sub-turn):
	//   - The sub-turn runs in the background (still blocks the caller, but semantically async)
	//   - The result is delivered to the parent's pendingResults channel
	//   - The result is ALSO returned via the function return value (for consistency)
	//   - The parent turn can poll pendingResults in later iterations to process results
	//   - Use case: Fire-and-forget operations, or when results are processed in batches
	//   - Example: Spawning multiple sub-turns in parallel and collecting results later
	//
	// IMPORTANT: The Async flag does NOT make the call non-blocking. It only controls
	// whether the result is delivered via the channel. For true non-blocking execution,
	// the caller must spawn the sub-turn in a separate goroutine.
	Async bool

	// Critical indicates this SubTurn's result is important and should continue
	// running even after the parent turn finishes gracefully.
	//
	// When parent finishes gracefully (Finish(false)):
	//   - Critical=true: SubTurn continues running, delivers result as orphan
	//   - Critical=false: SubTurn exits gracefully without error
	//
	// When parent finishes with hard abort (Finish(true)):
	//   - All SubTurns are canceled regardless of Critical flag
	Critical bool

	// Timeout is the maximum duration for this SubTurn.
	// If the SubTurn runs longer than this, it will be canceled.
	// Default is 5 minutes (defaultSubTurnTimeout) if not specified.
	Timeout time.Duration

	// MaxContextRunes limits the context size (in runes) passed to the SubTurn.
	// This prevents context window overflow by truncating message history before LLM calls.
	//
	// Values:
	//   0  = Auto-calculate based on model's ContextWindow * 0.75 (default, recommended)
	//   -1 = No limit (disable soft truncation, rely only on hard context errors)
	//   >0 = Use specified rune limit
	//
	// The soft limit acts as a first line of defense before hitting the provider's
	// hard context window limit. When exceeded, older messages are intelligently
	// truncated while preserving system messages and recent context.
	MaxContextRunes int

	// ActualSystemPrompt is injected as the true 'system' role message for the childAgent.
	// SystemPrompt, despite its name, carries the task description and is sent as
	// the first 'user' message.
	ActualSystemPrompt string

	// InitialMessages preloads the ephemeral session history before the agent loop starts.
	// Used by evaluator-optimizer patterns to pass the full worker context across multiple iterations.
	InitialMessages []providers.Message

	// InitialTokenBudget is a shared atomic counter for tracking remaining tokens.
	// If set, the SubTurn will inherit this budget and deduct tokens after each LLM call.
	// If nil, the SubTurn will inherit the parent's tokenBudget (if any).
	// Used by team tool to enforce token limits across all team members.
	InitialTokenBudget *atomic.Int64

	// TargetAgentID, when set, runs the sub-turn as the specified agent.
	// The target agent's workspace, model, tools, and system prompt are used
	// instead of the caller's. If empty, the sub-turn runs as the parent agent.
	TargetAgentID string
}

type SubTurnEndPayload struct {
	AgentID string
	Status  string
}

type SubTurnOrphanPayload struct {
	ParentTurnID string
	ChildTurnID  string
	Reason       string
}

type SubTurnResultDeliveredPayload struct {
	TargetChannel string
	TargetChatID  string
	ContentLen    int
}

type SubTurnSpawnPayload struct {
	AgentID      string
	Label        string
	ParentTurnID string
}

type ThinkingLevel string

type Tool = tools.Tool

type ToolApprovalRequest struct {
	Meta      HookMeta       `json:"meta"`
	Context   *TurnContext   `json:"context,omitempty"`
	Tool      string         `json:"tool"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

type ToolApprover interface {
	ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error)
}

type ToolCallHookRequest struct {
	Meta       HookMeta          `json:"meta"`
	Context    *TurnContext      `json:"context,omitempty"`
	Tool       string            `json:"tool"`
	Arguments  map[string]any    `json:"arguments,omitempty"`
	Channel    string            `json:"channel,omitempty"`
	ChatID     string            `json:"chat_id,omitempty"`
	HookResult *tools.ToolResult `json:"hook_result,omitempty"` // Result returned directly by hook (for respond action). Media is supported - see Media handling section in docs.
}

type ToolControl int

type ToolExecEndPayload struct {
	Tool       string
	Duration   time.Duration
	ForLLMLen  int
	ForUserLen int
	IsError    bool
	Async      bool
}

type ToolExecSkippedPayload struct {
	Tool   string
	Reason string
}

type ToolExecStartPayload struct {
	Tool      string
	Arguments map[string]any
}

type ToolExecutionRecord struct {
	Name         string   `json:"name"`
	Success      bool     `json:"success"`
	ErrorSummary string   `json:"error_summary,omitempty"`
	SkillNames   []string `json:"skill_names,omitempty"`
}

type ToolInterceptor interface {
	BeforeTool(ctx context.Context, call *ToolCallHookRequest) (*ToolCallHookRequest, HookDecision, error)
	AfterTool(ctx context.Context, result *ToolResultHookResponse) (*ToolResultHookResponse, HookDecision, error)
}

type ToolProvider interface {
	// RegisterTools contributes tools via register and returns one-line
	// summaries for the agent's context.
	//
	// workspace is the AGENT'S OWN working directory, and it is passed rather
	// than captured because it is resolved PER AGENT inside the registration
	// loop -- the composition root does not know it. An earlier version of this
	// interface omitted it, which only surfaced when wiring the call sites:
	// the provider would have had to invent a workspace, and every agent would
	// have shared one.
	//
	// The returned knowledge function is optional -- nil is valid, and means
	// this provider has no per-selection knowledge to load. It maps a
	// provider-defined identifier to overlays, skills and warnings.
	RegisterTools(workspace string, register func(Tool)) (summaries []string,
		knowledge func(id string) (overlays string, skills string, warnings []string))
}

type ToolResultHookResponse struct {
	Meta      HookMeta          `json:"meta"`
	Context   *TurnContext      `json:"context,omitempty"`
	Tool      string            `json:"tool"`
	Arguments map[string]any    `json:"arguments,omitempty"`
	Result    *tools.ToolResult `json:"result,omitempty"`
	Duration  time.Duration     `json:"duration"`
}

type TurnContext struct {
	Inbound *bus.InboundContext    `json:"inbound,omitempty"`
	Route   *routing.ResolvedRoute `json:"route,omitempty"`
	Scope   *session.SessionScope  `json:"scope,omitempty"`
}

type TurnEndPayload struct {
	Status                TurnEndStatus
	Workspace             string
	Iterations            int
	Duration              time.Duration
	FinalContentLen       int
	UserMessage           string
	FinalContent          string
	ActiveSkills          []string
	AttemptedSkills       []string
	FinalSuccessfulPath   []string
	SkillContextSnapshots []SkillContextSnapshot
	ToolKinds             []string
	ToolExecutions        []ToolExecutionRecord
	// Error says why a turn that ended with TurnEndStatusError failed.
	Error string
}

type TurnEndStatus string

type TurnPhase string

type TurnStartPayload struct {
	UserMessage string
	MediaCount  int
}

type UserDefinition struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}