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 {
	Source AgentDefinitionSource  `json:"source,omitempty"`
	Agent  *AgentPromptDefinition `json:"agent,omitempty"`
	Soul   *SoulDefinition        `json:"soul,omitempty"`
	User   *UserDefinition        `json:"user,omitempty"`
}

type AgentDefinitionSource string

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"`
	ToolPolicy  *PatternPolicy `json:"-"`
	Model       string         `json:"model,omitempty"`
	MaxTurns    *int           `json:"maxTurns,omitempty"`
	Skills      []string       `json:"skills,omitempty"`
	MCPServers  []string       `json:"mcpServers,omitempty"`
	MCPPolicy   *PatternPolicy `json:"-"`
	Fields      map[string]any `json:"-"`
}

type AgentInstance struct {
	ID                        string
	Name                      string
	Model                     string
	Fallbacks                 []string
	Workspace                 string
	Layout                    RuntimeLayout
	MaxIterations             int
	MaxTokens                 int
	Temperature               float64
	ThinkingLevel             ThinkingLevel
	ThinkingLevelConfigured   bool
	ContextWindow             int
	SummarizeMessageThreshold int
	SummarizeTokenPercent     int
	Provider                  providers.LLMProvider
	Sessions                  session.SessionStore
	ContextBuilder            *ContextBuilder
	Tools                     *tools.ToolRegistry

	Definition       AgentContextDefinition
	Subagents        *config.SubagentsConfig
	SkillsFilter     []string
	MCPServerPolicy  *PatternPolicy
	ToolPolicy       *PatternPolicy
	Candidates       []providers.FallbackCandidate
	MaxParallelTurns int

	// Router is non-nil when model routing is configured and the light model
	// was successfully resolved. It scores each incoming message and decides
	// whether to route to LightCandidates or stay with Candidates.
	Router *routing.Router
	// LightCandidates holds the resolved provider candidates for the light model.
	// Pre-computed at agent creation to avoid repeated model_list lookups at runtime.
	LightCandidates []providers.FallbackCandidate
	// LightProvider is the concrete provider instance for the configured light model.
	// It is only used when routing selects the light tier for a turn.
	LightProvider providers.LLMProvider
	// CandidateProviders maps "provider/model" keys to per-candidate LLMProvider
	// instances. This allows each fallback model to use its own api_base and api_key
	// from model_list, instead of inheriting the primary model's provider config.
	CandidateProviders map[string]providers.LLMProvider
	ToolLoopDetection  loopguard.Config
	// 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"`
	RequireHuman   bool   `json:"require_human,omitempty"`
	Reason         string `json:"reason,omitempty"`
	ActionSummary  string `json:"action_summary,omitempty"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
}

type AssembleRequest struct {
	Agent         *AgentInstance // exact owner of the session
	SessionKey    string         // session identifier
	Budget        int            // context window in tokens
	MaxTokens     int            // max response tokens
	ReserveTokens int            // non-history prompt/tool tokens reserved outside context manager
}

type AssembleResponse struct {
	History []providers.Message  // assembled conversation history for BuildMessages
	Summary string               // conversation summary embedded into system prompt by BuildMessages
	Budget  *ContextBudgetReport // optional bounded-context selection details
}

type AsyncCompletionInput struct {
	SourceTool   string
	CompletionID string
	Content      string
	Origin       bus.InboundContext
	SenderID     string
}

type AsyncCompletionPayload struct {
	SourceTool   string
	CompletionID string
	TaskID       string
	DeliveryMode string
	ContentLen   int
	ForUserLen   int
	MediaCount   int
	IsError      bool
	WillUser     bool
	WillParent   bool
}

type AsyncDeliveryDecision struct {
	TaskID        string
	DeliveryMode  toolshared.AsyncDeliveryMode
	PublishToUser bool
	QueueParent   bool
	ParentHandled bool
	ContentLen    int
	ForUserLen    int
	MediaCount    int
	IsError       bool
}

type AsyncDeliveryRequest struct {
	TurnState    *turnState
	ToolName     string
	CompletionID string
	Result       *toolshared.ToolResult
	Decision     AsyncDeliveryDecision
	TraceScopes  []runtimeevents.TraceScope
}

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

type CompactRequest struct {
	Agent      *AgentInstance           // exact owner of the session
	SessionKey string                   // session identifier
	Workspace  string                   // canonical workspace owner
	TraceScope runtimeevents.TraceScope // exact owner for synchronous turn work; zero for background work
	Reason     ContextCompressReason    // proactive_budget | llm_retry | summarize
	Budget     int                      // effective history budget for compact/overflow repair
}

type ContextBudgetReport struct {
	ContextWindow            int
	OutputReserve            int
	NonHistoryReserve        int
	AvailableContext         int
	HistoryBudget            int
	SummaryBudget            int
	SourceHistoryTokens      int
	SourceSummaryTokens      int
	SelectedHistoryTokens    int
	SelectedSummaryTokens    int
	RequestedRecentTailTurns int
	RecentTailTurns          int
	RecentTailTokens         int
	RecentTailOverflowTokens int
	RecentTailDegraded       bool
	Truncated                bool
	NeedsCompaction          bool
	PressureReasons          []string
}

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

type ContextCompressPayload struct {
	Reason                   ContextCompressReason
	DroppedMessages          int
	RemainingMessages        int
	ContextWindow            int
	OutputReserve            int
	NonHistoryReserve        int
	AvailableContext         int
	HistoryBudget            int
	SummaryBudget            int
	SourceHistoryTokens      int
	SourceSummaryTokens      int
	SelectedHistoryTokens    int
	SelectedSummaryTokens    int
	RequestedRecentTailTurns int
	RecentTailTurns          int
	RecentTailTokens         int
	RecentTailOverflowTokens int
	RecentTailDegraded       bool
	Truncated                bool
	PressureReasons          []string
	TokensSaved              int
	SummariesCreated         int
	LeafSummaries            int
	CondensedSummaries       int
}

type ContextCompressReason string

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

	// Compact compresses conversation history.
	// Called by background schedulers for routine/proactive pressure and
	// synchronously only on emergency context-overflow retry.
	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, agent *AgentInstance, sessionKey string) error
}

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

type ContextSnapshotPayload struct {
	MessageCount     int
	SnapshotHash     string
	GoalHash         string
	SteeringCount    int
	ToolPairingValid bool
}

type Control int

type DirectTurnOptions struct {
	// Stateless prevents the turn from loading or saving conversation history.
	// Tool calls and results remain available for the duration of the turn.
	Stateless bool
}

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

type ErrorPayload struct {
	Stage   string
	Message string
}

type Event struct {
	Kind    EventKind
	Time    time.Time
	Meta    EventMeta
	Context *TurnContext
	Payload any
}

type EventKind = runtimeevents.Kind

type EventMeta = HookMeta

type EventSubscription struct {
	ID uint64
	C  <-chan Event
}

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

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 {
	runtimeevents.TraceScope
	AgentID      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 InboundMessageRelation struct {
	Kind      InboundRelationKind
	MediaOnly bool
}

type InboundRelationKind string

type IngestRequest struct {
	Agent             *AgentInstance    // exact owner of the session
	SessionKey        string            // session identifier
	Message           providers.Message // the message submitted to canonical history
	CanonicalWriteErr error             // non-nil when canonical persistence failed
}

type InteractionEventPayload struct {
	InteractionID string                 `json:"interaction_id"`
	ShortID       string                 `json:"short_id,omitempty"`
	Kind          interactions.Kind      `json:"kind"`
	Event         interactions.EventType `json:"event"`
	Status        interactions.Status    `json:"status"`
	Outcome       interactions.Outcome   `json:"outcome,omitempty"`
	Revision      int64                  `json:"revision"`
	Code          string                 `json:"code,omitempty"`
	Success       *bool                  `json:"success,omitempty"`
}

type InterruptKind string

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

type LLMCallOutcome struct {
	Control      Control
	FinalContent string
	AbortCause   TurnAbortCause
}

type LLMDeltaPayload struct {
	ContentDeltaLen   int
	ReasoningDeltaLen int
}

type LLMFallbackAttemptPayload struct {
	Provider    string
	Model       string
	IdentityKey string
	Attempt     int
	Status      string
	Reason      string
	ErrorCode   string
	Skipped     bool
}

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"`
	GracefulTerminal bool                       `json:"graceful_terminal,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 LLMIterationState struct {
	// contains filtered or unexported fields
}

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

type LLMResponsePayload struct {
	ResponseHash        string
	ContentLen          int
	ToolCalls           int
	HasReasoning        bool
	PromptTokens        int
	CompletionTokens    int
	TotalTokens         int
	HasProviderUsage    bool
	DiagnosticContent   string
	DiagnosticReasoning string
	DiagnosticToolCalls string
}

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

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

type PatternPolicy struct {
	Allow []string
	Deny  []string
	// contains filtered or unexported fields
}

type Pipeline struct {
	Cfg         *config.Config
	Runtime     PipelineRuntimeServices
	Config      PipelineConfigServices
	Context     PipelineContextServices
	Interaction PipelineInteractionServices
}

type PipelineConfigServices struct {
	ChannelStreaming      channelStreamingConfigProvider
	NativeSearch          nativeSearchPolicy
	LLMRetry              llmRetryPolicy
	RetrySleeper          retrySleeper
	MediaLimits           mediaLimitsProvider
	FinalTurnRender       finalTurnRenderPolicy
	ModelResolution       pipelineModelResolution
	PromptBuilder         pipelinePromptBuilder
	ToolContentFilter     toolContentFilter
	TrustAllToolExecution bool
	HashToolArguments     func(string, map[string]any) (string, error)
}

type PipelineContextServices struct {
	Runtime              pipelineContextRuntime
	BackgroundCompaction backgroundCompactionScheduler
	ModelExecution       modelExecutionResolver
	Steering             steeringDequeuer
	MediaResolver        mediaResolver
}

type PipelineDependencies struct {
	Cfg         *config.Config
	Runtime     PipelineRuntimeServices
	Config      PipelineConfigServices
	Context     PipelineContextServices
	Interaction PipelineInteractionServices
}

type PipelineInteractionServices struct {
	Reasoning        reasoningPublisher
	ToolFeedback     toolFeedbackManager
	SyncToolDelivery syncToolResultDeliveryManager
	ToolDelivery     toolDeliveryManager
	Hooks            hookInterceptor
	Fallback         fallbackExecutor
	Suspension       toolSuspensionManager
}

type PipelineRuntimeServices struct {
	Bus            pipelineBus
	Events         runtimeEventEmitter
	ActiveRequests activeRequestTracker
	TurnControl    turnController
}

type PreparedConfigReload struct {
	// 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
	ReplyToMessageID  string
	// AllowAdjacentMediaFollowup enables inferred media-only continuation from
	// the previous user turn. Callers should only set it when the session scope
	// is known to be single-sender-safe, or when sender metadata can prove the
	// prior user message came from the same sender.
	AllowAdjacentMediaFollowup bool
	CurrentMessageRelation     InboundMessageRelation

	ActiveSkills []string
	Overlays     []PromptPart

	SuppressDefaultSystemPrompt bool
	SuppressSkillContext        bool
	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 RuntimeAgentToolFactory func(cfg *config.Config, agentID string) (toolshared.Tool, error)

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

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

type RuntimeOwner struct {
	Kind RuntimeOwnerKind
	ID   string
}

type RuntimeOwnerKind string

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

type RuntimeProfileBinding struct {
	AgentID string
	Layout  RuntimeLayout
}

type RuntimeStatePaths struct {
	SessionsRoot       string
	ContextRoot        string
	MemoryRoot         string
	OperationalRoot    string
	RuntimeStateFile   string
	TaskRegistryFile   string
	InteractionFile    string
	InteractionKeyFile string
	DiagnosticsRoot    string
	MediaRoot          string
}

type RuntimeStoreFactory interface {
	NewSessionStore(layout RuntimeLayout) (session.SessionStore, error)
	NewSeahorseEngine(config seahorse.Config, complete seahorse.CompleteFn) (*seahorse.Engine, error)
}

type RuntimeToolDecoratorFactory func(
	cfg *config.Config,
	agentID string,
	local toolshared.Tool,
) (toolshared.Tool, error)

type RuntimeToolFactory func(cfg *config.Config) (toolshared.Tool, error)

type RuntimeToolProfile string

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 {
	Model        string
	Tools        []toolshared.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.
	// The legacy SystemPrompt field is actually used as the first 'user' message (task description).
	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

	// DeliveryMode controls user-facing delivery ownership for synchronous
	// delegate/sub-turn flows. Reuses the same enum names as async spawn:
	// parent_only, user_only, user_and_parent.
	DeliveryMode toolshared.AsyncDeliveryMode
	TaskID       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 ToolApprovalConsumptionRequest struct {
	Workspace     string
	InteractionID string
	Revision      int64
	Origin        interactions.Origin
}

type ToolApprovalGrant struct {
	InteractionID     string
	Revision          int64
	OriginExecutionID string
	// OriginArgumentHash is the trusted binding stored with the suspended
	// interaction. Fresh approval arguments may differ after retained
	// time-bound tool state expires, but consumption must spend this binding.
	OriginArgumentHash string
}

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 *toolshared.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 {
	ToolCallID       string
	Tool             string
	Duration         time.Duration
	ForLLMLen        int
	ForUserLen       int
	IsError          bool
	Async            bool
	ResultHash       string
	Suspended        bool
	InteractionID    string
	DiagnosticResult string
}

type ToolExecSkippedPayload struct {
	ToolCallID string
	Tool       string
	Reason     string
}

type ToolExecStartPayload struct {
	ToolCallID string
	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 ToolLoopDecisionPayload struct {
	Tool      string
	ArgsHash  string
	Action    string
	Code      string
	Count     int
	Threshold int
}

type ToolLoopOutcome struct {
	Control                ToolControl
	FinalContent           string
	AbortCause             TurnAbortCause
	SuspendedInteractionID string
	JournalErr             error
}

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

type ToolSuspensionDisposition struct {
	InteractionID string
	Durable       bool
}

type ToolSuspensionRequest struct {
	Workspace        string
	Prompt           interactions.SuspensionRequest
	Route            interactions.Route
	Origin           interactions.Origin
	ApprovalAction   string
	ExecutionContext *bus.InboundContext
	Resolution       func(context.Context, interactions.Outcome) error
}

type TurnAbortCause int

type TurnActionRecord struct {
	Source        string `json:"source"`
	Tool          string `json:"tool,omitempty"`
	Text          string `json:"text"`
	Error         bool   `json:"error,omitempty"`
	VerifiedWrite bool   `json:"verified_write,omitempty"`
}

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
	DeliveryExpected      bool
	Iterations            int
	Duration              time.Duration
	LLMCalls              int
	PromptTokens          int
	CompletionTokens      int
	TotalTokens           int
	FinalContentLen       int
	UserMessage           string
	FinalContent          string
	ActiveSkills          []string
	AttemptedSkills       []string
	FinalSuccessfulPath   []string
	SkillContextSnapshots []SkillContextSnapshot
	ToolKinds             []string
	ToolExecutions        []ToolExecutionRecord
	InteractionID         string
}

type TurnEndStatus string

type TurnPhase string

type TurnStartPayload struct {
	UserMessage string
	MediaCount  int
	Workspace   string
}

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