engine

type CompactionSnapshot struct {
	PreCompactionTokenCount  int
	PostCompactionTokenCount int
	FirstPreservedMessageID  types.MessageID
	LastPreservedMessageID   types.MessageID
	PreservedTailHash        string
	BoundaryVersion          int
}

type Config struct {
	MaxTurns             int                   `json:"max_turns"`
	AutoCompact          bool                  `json:"auto_compact"`
	PermissionMode       types.PermissionMode  `json:"permission_mode"`
	Model                types.ModelIdentifier `json:"model"`
	MaxTokens            int                   `json:"max_tokens"`
	WorkingDirectory     string                `json:"working_directory,omitempty"`
	SystemPromptTemplate string                `json:"system_prompt_template"`
	MCPServers           []mcp.ServerConfig    `json:"mcp_servers"`
	EnableMemory         bool                  `json:"enable_memory"`
	EnableMonitoring     bool                  `json:"enable_monitoring"`

	// MaxIterations caps model→tool→model cycles per turn. 0 = loop default (10).
	MaxIterations int `json:"max_iterations"`

	// TurnTokenBudget enables token-budget continuation when > 0.
	TurnTokenBudget int `json:"turn_token_budget"`

	// BudgetContinuationLimit caps how many budget-continuation cycles may occur.
	// 0 = loop default.
	BudgetContinuationLimit int `json:"budget_continuation_limit"`

	// ContinuationNudgeLimit caps how many text-signal nudges the loop sends.
	// 0 = loop default (3).
	ContinuationNudgeLimit int `json:"continuation_nudge_limit"`

	// StopHooks are post-turn policy hooks that may request one more cycle.
	StopHooks []StopHook `json:"-"`

	// MaxConsecutiveDenials is the number of back-to-back permission denials that
	// trigger orchestrator fallback. 0 = use the default (3).
	MaxConsecutiveDenials int `json:"max_consecutive_denials"`

	// PromptStage sets the execution stage overlay injected into the dynamic
	// section of the system prompt every turn.
	PromptStage prompt.ExecutionStage `json:"prompt_stage,omitempty"`

	// PromptStageOverrides replaces built-in stage overlay text per stage.
	PromptStageOverrides map[prompt.ExecutionStage]string `json:"-"`

	// PromptToolHints provides per-tool extra guidance appended to provider-facing
	// tool descriptions. Key is the canonical tool name.
	PromptToolHints map[string]string `json:"-"`

	// AppendSystemPrompt is appended to the system prompt after all other sections.
	AppendSystemPrompt string `json:"append_system_prompt,omitempty"`

	// BrowserManager manages native browser sessions for browser tools.
	BrowserManager browsercore.Manager `json:"-"`

	// DisableStreaming opts out of server-sent-event streaming. Streaming is
	// enabled by default; set this to true only when the provider or test
	// harness does not support SSE.
	DisableStreaming bool `json:"disable_streaming,omitempty"`
}

type ContinueTransition struct {
	// Reason explains why we're continuing
	Reason string

	// RecoveryType indicates the type of recovery (if any)
	RecoveryType RecoveryType
}

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

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

type LoopConfig struct {
	MaxIterations                int        `json:"max_iterations"`
	AutoCompact                  bool       `json:"auto_compact"`
	MaxTurns                     int        `json:"max_turns"`
	EnableStreaming              bool       `json:"enable_streaming"`
	MaxOutputTokensRecoveryLimit int        `json:"max_output_tokens_recovery_limit"`
	ContinuationNudgeLimit       int        `json:"continuation_nudge_limit"`
	TurnTokenBudget              int        `json:"turn_token_budget,omitempty"`
	BudgetContinuationLimit      int        `json:"budget_continuation_limit,omitempty"`
	BudgetCompletionThreshold    float64    `json:"budget_completion_threshold,omitempty"`
	BudgetDiminishingThreshold   int        `json:"budget_diminishing_threshold,omitempty"`
	StopHooks                    []StopHook `json:"-"`
	// StopHookConfig controls stop hook execution behavior
	StopHookTimeout         int    `json:"stop_hook_timeout,omitempty"`           // milliseconds, 0 = no timeout
	StopHookMode            string `json:"stop_hook_mode,omitempty"`              // "first" (default) or "all"
	StopHookContinueOnError bool   `json:"stop_hook_continue_on_error,omitempty"` // continue if hook errors
	// Additional recovery options
	MaxRecoveryAttempts       int `json:"max_recovery_attempts,omitempty"`       // total recovery attempts per turn
	RecoveryBackoffMultiplier int `json:"recovery_backoff_multiplier,omitempty"` // milliseconds
}

type MutableState struct {
	// Messages are the conversation messages
	Messages []types.Message

	// ToolUses are all tool uses executed
	ToolUses []types.ToolUseContent

	// ToolResults are all tool results
	ToolResults []tool.CallResult

	// DiscoveredDeferred tracks deferred tools discovered during the current run.
	DiscoveredDeferred []string

	// Usage is token usage information
	Usage *types.TokenUsage

	// StopReason is why the loop stopped
	StopReason string

	// Compacted indicates if compaction occurred
	Compacted bool

	// Iterations is the number of iterations performed
	Iterations int

	// TurnCount is the turn count
	TurnCount int

	// MaxOutputTokensRecoveryCount is recovery attempt count
	MaxOutputTokensRecoveryCount int

	// HasAttemptedReactiveCompact indicates if reactive compact was tried
	HasAttemptedReactiveCompact bool

	// MaxOutputTokensOverride is the override for max tokens
	MaxOutputTokensOverride int

	// ContinuationNudgeCount is continuation nudge count
	ContinuationNudgeCount int

	// Transition is the previous transition (undefined on first iteration)
	Transition Transition

	// StopHookActive indicates if a stop hook is active
	StopHookActive *bool

	// AutoCompactFailureCount tracks consecutive auto-compact failures.
	AutoCompactFailureCount int

	// TotalTurnTokens accumulates API usage across iterations of the turn.
	TotalTurnTokens int

	// BudgetContinuationCount tracks how many budget-based continuations fired.
	BudgetContinuationCount int

	// LastBudgetCheckTokens is the previous total token count seen by budget logic.
	LastBudgetCheckTokens int

	// LastBudgetDelta stores the last token delta for diminishing-returns checks.
	LastBudgetDelta int

	// RecoveryContext tracks details needed to properly resume after interruption
	RecoveryContext *RecoveryContext

	// CurrentStage is the prompt.ExecutionStage detected at the start of the last
	// iteration. Used to avoid redundant system-prompt rebuilds.
	CurrentStage prompt.ExecutionStage

	// PermissionContext is the evolving permission context owned by the loop
	// during this turn. Initialized from RunRequest at turn start; updated after
	// each tool execution batch. Session reads it back via RunResult.
	PermissionContext *types.PermissionContext

	// PermissionMode mirrors PermissionContext.Mode for fast access without a
	// nil check on every iteration.
	PermissionMode types.PermissionMode
}

type PromptRefresh struct {
	SystemPrompt       string
	SystemPromptBlocks []types.SystemPromptBlock
}

type RecoveryContext struct {
	LastTransitionReason string
	LastRecoveryType     RecoveryType
	LastStopReason       string
	CompactionSnapshot   *CompactionSnapshot
	TurnProgress         *TurnProgress
}

type RecoveryType string

type RunRequest struct {
	Messages           []types.Message           `json:"messages"`
	SystemPrompt       string                    `json:"system_prompt"`
	SystemPromptBlocks []types.SystemPromptBlock `json:"system_prompt_blocks,omitempty"`
	ProviderTools      []types.APIToolDefinition `json:"tools,omitempty"`
	Tools              map[string]tool.Tool      `json:"-"`
	// Toolsets are resolved dynamically at the start of each iteration.
	// Their tools are merged into Tools each iteration (Toolset wins on name collision).
	Toolsets            []tool.Toolset                                                                                                                      `json:"-"`
	ToolRegistry        *tool.Registry                                                                                                                      `json:"-"`
	RefreshSystemPrompt func(ctx context.Context, tools map[string]tool.Tool, pendingDeferred []string, stage prompt.ExecutionStage) (PromptRefresh, error) `json:"-"`
	// AutoDetectStage enables per-iteration stage detection. The engine sets this
	// when no static PromptStage is configured so that stage overlays fire
	// automatically without manual configuration.
	AutoDetectStage       bool                         `json:"-"`
	SessionID             types.SessionID              `json:"session_id"`
	TurnID                types.TurnID                 `json:"turn_id"`
	WorkingDirectory      string                       `json:"working_directory,omitempty"`
	PermissionMode        types.PermissionMode         `json:"permission_mode"`
	PermissionContext     *types.PermissionContext     `json:"-"`
	PermissionCheck       types.CanUseToolFn           `json:"-"`
	DenialTracking        *types.DenialTrackingState   `json:"-"`
	Model                 types.ModelIdentifier        `json:"model"`
	MaxTokens             int                          `json:"max_tokens"`
	ProgressCallback      func(types.ToolProgress)     `json:"-"`
	ResponseChunkCallback func(types.APIResponseChunk) `json:"-"`
	// EventQueue receives every streaming chunk emitted during this turn.
	// Callers read from EventQueue.Recv() in a separate goroutine to avoid
	// blocking the loop. Overflow is counted but never blocks.
	EventQueue      *execution.EventQueue `json:"-"`
	TurnTokenBudget int                   `json:"turn_token_budget,omitempty"`

	// OutputSchema, when set, constrains the model to return JSON matching the
	// schema. Passed through to types.APIRequest.OutputSchema.
	OutputSchema *schema.StructuredOutputInfo `json:"-"`
}

type RunResult struct {
	Messages           []types.Message          `json:"messages"`
	StopReason         string                   `json:"stop_reason"`
	ToolUses           []types.ToolUseContent   `json:"tool_uses"`
	ToolResults        []tool.CallResult        `json:"tool_results"`
	Usage              *types.TokenUsage        `json:"usage"`
	PermissionContext  *types.PermissionContext `json:"-"`
	Compacted          bool                     `json:"compacted"`
	Iterations         int                      `json:"iterations"`
	DiscoveredDeferred []string                 `json:"discovered_deferred,omitempty"`
	Error              error                    `json:"error,omitempty"`
	// RecoveryContext captures the turn execution state at loop exit.
	// Persisted by the engine into session metadata so that interrupted or
	// errored sessions can expose what was in-flight at the time of failure.
	RecoveryContext *RecoveryContext `json:"-"`
}

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

type RunnerConfig struct {
	MaxIterations int  `json:"max_iterations"`
	AutoCompact   bool `json:"auto_compact"`
	MaxTurns      int  `json:"max_turns"`
}

type RunnerRequest struct {
	Messages         []types.Message            `json:"messages"`
	SystemPrompt     string                     `json:"system_prompt"`
	Tools            map[string]tool.Tool       `json:"-"`
	SessionID        types.SessionID            `json:"session_id"`
	TurnID           types.TurnID               `json:"turn_id"`
	PermissionMode   types.PermissionMode       `json:"permission_mode"`
	PermissionCheck  types.CanUseToolFn         `json:"-"`
	DenialTracking   *types.DenialTrackingState `json:"-"`
	Model            types.ModelIdentifier      `json:"model"`
	MaxTokens        int                        `json:"max_tokens"`
	ProgressCallback func(types.ToolProgress)   `json:"-"`
	PromptVariables  map[string]string          `json:"prompt_variables,omitempty"`
}

type RunnerResult struct {
	Messages    []types.Message        `json:"messages"`
	StopReason  string                 `json:"stop_reason"`
	ToolUses    []types.ToolUseContent `json:"tool_uses"`
	ToolResults []tool.CallResult      `json:"tool_results"`
	Usage       *types.TokenUsage      `json:"usage"`
	Compacted   bool                   `json:"compacted"`
	Iterations  int                    `json:"iterations"`
}

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

type SessionResponse struct {
	Messages    []types.Message        `json:"messages"`
	StopReason  string                 `json:"stop_reason"`
	ToolUses    []types.ToolUseContent `json:"tool_uses"`
	ToolResults []tool.CallResult      `json:"tool_results"`
	Usage       *types.TokenUsage      `json:"usage"`
	TotalTokens int                    `json:"total_tokens"`
	TurnNumber  int                    `json:"turn_number"`
	Compacted   bool                   `json:"compacted"`
}

type SessionState struct {
	SessionID           types.SessionID
	TurnID              types.TurnID
	Messages            []types.Message
	Tools               map[string]tool.Tool
	DiscoveredDeferred  []string
	PermissionContext   *types.PermissionContext
	DenialTracking      *types.DenialTrackingState
	TurnNumber          int
	TotalTokens         int
	Metadata            *types.SessionMetadata
	LastCompaction      *types.CompactionMetadata
	CompactionCount     int
	CanonicalTranscript int
}

type SessionStore interface {
	SaveSessionState(sessionID types.SessionID, metadata *types.SessionMetadata, previousMessages []types.Message, currentMessages []types.Message) error
}

type StopHook interface {
	Name() string
	Priority() int
	Execute(ctx context.Context, input StopHookInput) (StopHookResult, error)
}

type StopHookConfig struct {
	// Timeout in milliseconds, 0 = no timeout
	Timeout int
	// Mode: "first" stops at first Continue, "all" runs all hooks
	Mode string
	// ContinueOnError continues loop if hook errors
	ContinueOnError bool
}

type StopHookInput struct {
	SessionID  types.SessionID
	TurnID     types.TurnID
	StopReason string
	Messages   []types.Message
	ToolUses   []types.ToolUseContent
	Usage      *types.TokenUsage
	Iterations int
	Compacted  bool
	// Additional context for richer hook decisions
	RecoveryContext *RecoveryContext
	TotalTurnTokens int
	Model           types.ModelIdentifier
}

type StopHookResult struct {
	Continue bool
	Messages []types.Message
	// Error indicates a hard failure (stops the loop)
	Error error
}

type TerminalTransition struct {
	// Reason explains why we're stopping
	Reason string

	// StopReason is the API stop reason
	StopReason string
}

type Transition interface {
	IsContinue() bool
	IsTerminal() bool
}

type TurnProgress struct {
	IterationsCompleted    int
	LastAssistantMessageID types.MessageID
	PendingToolUses        []types.ToolUseContent
	PendingToolResults     []tool.CallResult
	TotalTokensUsed        int
}