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"`
	TitleModel     types.ModelIdentifier `json:"title_model,omitempty"`
	// CompactSummaryModel overrides which model generates compaction summaries.
	// Zero value means "use Model" (the session's own model), so compaction
	// works on any provider without needing an Anthropic key.
	CompactSummaryModel types.ModelIdentifier `json:"compact_summary_model,omitempty"`
	// TrustProjectInstructions gates SESHAT.md/AGENTS.md/.seshat/instructions.md
	// found in the working directory behind project trust before they are
	// injected into the system prompt (see docs/project-trust.md and
	// readTrustedProjectInstructions). nil fails closed: no project's own
	// instructions are ever injected without a host wiring this in - e.g. to
	// the same hash-based trust store it already uses for the project's other
	// configuration files.
	TrustProjectInstructions func(path string, content []byte) bool `json:"-"`
	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
	// (100 - see DefaultLoopConfig; this comment previously said 10, which
	// was never the actual default - M3 in TODO.md).
	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"`

	// ManagedInstructions is text imposed by whoever runs the host (an organization).
	// It is appended after everything else, including a per-session append prompt,
	// so a session setter cannot replace or drop it.
	ManagedInstructions string `json:"-"`

	// 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 is currently dead weight: nothing in this file reads it. The
	// live session-turn limit is engine.Config.MaxTurns, enforced by
	// Session.enforceMaxTurns (M3 in TODO.md - its default used to disagree
	// with this one, 200 vs 100, despite neither mattering here).
	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; base delay for attempt 1, doubled each attempt after
	RecoveryBackoffMaxDelay   int `json:"recovery_backoff_max_delay_ms,omitempty"` // milliseconds; caps the exponential growth, 0 = default (30s)
}

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

	// CompactPreTokens and CompactPostTokens carry the token counts from the
	// most recent compaction this turn (zero unless Compacted is true) - see
	// maybeAutoCompact. Threaded through RunResult/SessionResponse so a host
	// can show a before/after "saved N tokens" toast instead of compaction
	// happening completely silently.
	CompactPreTokens  int
	CompactPostTokens int

	// PreviousResponseID and PreviousResponseMessageCount enable a provider
	// that supports server-side conversation continuation (currently:
	// Codex's Responses API previous_response_id) to send only the messages
	// appended since the last successful same-provider response, instead of
	// resending the whole growing Messages list on every internal iteration
	// of a single turn's tool-use loop (up to MaxIterations). Populated in
	// Loop.recordPreviousResponse after each successful model call;
	// invalidated (reset to zero) the moment compaction changes Messages or
	// a different provider answers, so a stale/mismatched reference can
	// never be sent - worst case on invalidation is just falling back to
	// the existing full-resend behavior. Scoped to a single Loop.Run call
	// (one turn): MutableState is rebuilt fresh per turn, so there is no
	// cross-turn or cross-restart persistence to keep consistent.
	PreviousResponseID           string
	PreviousResponseMessageCount int

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

	// AutoCompactFailureCount carries the session's consecutive auto-compact
	// failure count into this turn, so the circuit breaker in
	// compact.Engine.AutoCompact persists across turns instead of resetting
	// to zero every Run. The caller (Session.SubmitMessage) is responsible
	// for threading RunResult.AutoCompactFailureCount back in on the next turn.
	AutoCompactFailureCount int `json:"auto_compact_failure_count,omitempty"`
}

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"`
	CompactPreTokens   int                      `json:"compact_pre_tokens,omitempty"`
	CompactPostTokens  int                      `json:"compact_post_tokens,omitempty"`
	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:"-"`
	// AutoCompactFailureCount is the session's consecutive auto-compact
	// failure count after this turn. The caller must store it (e.g. on
	// SessionState) and pass it back in as the next turn's
	// RunRequest.AutoCompactFailureCount for the circuit breaker to work
	// across turns.
	AutoCompactFailureCount int `json:"auto_compact_failure_count,omitempty"`
}

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"`
	CompactPreTokens  int                    `json:"compact_pre_tokens,omitempty"`
	CompactPostTokens int                    `json:"compact_post_tokens,omitempty"`
	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"`
	CompactPreTokens  int                    `json:"compact_pre_tokens,omitempty"`
	CompactPostTokens int                    `json:"compact_post_tokens,omitempty"`
}

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

	// AutoCompactFailureCount tracks consecutive auto-compact failures across
	// turns, so the circuit breaker in compact.Engine.AutoCompact can actually
	// trip. MutableState's own copy of this is per-turn scratch space seeded
	// from here and folded back after each Run (see Loop.initializeState /
	// Session.SubmitMessage).
	AutoCompactFailureCount 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 TitleGenerator interface {
	GenerateTitle(ctx context.Context, firstUserMsg string) (string, error)
}

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

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