loop

type Boundary int

type Compactor interface {
	Compact(ctx context.Context, history []Message, lastUsage *llm.TokenUsage, force bool) (out []Message, notes []string, changed bool)
}

type Env struct {
	Mode           Mode
	Workspace      string
	Registry       *tools.Registry
	Checker        *permissions.Checker
	ToolMode       tools.RuntimeMode
	MCP            *mcp.Manager
	Indexer        *codegraph.Indexer
	Hooks          *hooks.Runner // tool hooks run in Registry; nil when loading failed
	Files          *checkpoints.FileTracker
	Snapshots      *checkpoints.SnapshotManager
	ProjectContext string // grimoire, context files, code-graph summary
	GitSnapshot    string
	// Memories is the "# Project Memories" block. It follows git in the
	// prompt (W5 ruling 8); GrimoireContext still shows it.
	Memories         string
	GrimoireContext  string // grimoire and "# Project Memories" (the /grimoire view)
	CodeGraphSummary string // the code graph's project summary (the /index view)
	// Rules are the stream rules for this workspace (2.0 W3): built-ins,
	// ~/.celeste/rules/*.md, then the grimoire's "## Stream Rules" (a repo
	// grimoire's only once trusted, like a repo hook).
	Rules *rules.Set
	// SandboxPolicy is bash's OS sandbox (2.0 W4): defaults, the user's
	// "sandbox" settings, then the workspace's (loosening only once
	// trusted). A nested Env in the same workspace inherits it; one in
	// another workspace resolves its own.
	SandboxPolicy sandbox.Policy
	// contains filtered or unexported fields
}

type Event struct {
	Kind      EventKind
	Turn      int
	Text      string
	ToolNames []string
	Usage     *llm.TokenUsage
	Elapsed   time.Duration
	Call      ToolCall
	Msg       Message
	Metadata  map[string]any // EventToolResult: the tool's ToolResult.Metadata (images, subagent names)
	IsError   bool
	History   []Message
	Result    Result
	Err       error
	// At is EventToolStart's start time, taken on the loop's goroutine, so
	// it precedes every message the loop stamps after the call (C5).
	At time.Time
}

type EventKind int

type Gate interface {
	Ask(ctx context.Context, req tools.PermissionRequest) tools.PermissionResponse
}

type GateFunc func(ctx context.Context, req tools.PermissionRequest) tools.PermissionResponse

type LLM interface {
	SendMessageStreamEvents(ctx context.Context, messages []tui.ChatMessage, tools []tui.SkillDefinition, cb llm.StreamEventCallback) error
	// GetSkills is the tools a request offers, and so the only ones the
	// loop runs: an implementation that offers none returns an empty,
	// non-nil slice (nil places no restriction; test stubs only).
	GetSkills() []tui.SkillDefinition
}

type Limits struct {
	MaxTurns           int           // <=0: DefaultMaxTurns
	MaxCallsPerTurn    int           // calls beyond it are dropped before the turn is recorded
	IdenticalCalls     int           // stop when the identical call batch repeats this many turns
	NoProgressTurns    int           // stop when tools return identical results this many turns
	SpillBytes         int           // results larger than this spill to disk
	ToolTimeout        time.Duration // <=0: DefaultToolTimeout; a tools.Timeouter overrides it
	RequestTimeout     time.Duration // per-request deadline; the client's per-attempt deadline still applies
	MaxInvalidArgTurns int           // stop after this many turns in a row with bad tool arguments
	TextToolCalls      bool          // parse <tool_call> blocks from text when a turn has no native calls
	// KeepToolMetadata puts an image result's ToolResult.Metadata on its
	// tool message (read_file for vision models), with a marker in the
	// content. The chat sets it; agent and MCP runs send text only.
	KeepToolMetadata bool
	// MaxRuleInterrupts bounds re-runs of one turn by steering (W3);
	// <=0: DefaultMaxRuleInterrupts.
	MaxRuleInterrupts int
	// HookBudget is how long PreToolUse/PostToolUse hooks may add to a call
	// before the watchdog abandons it (tool timeout + budget; gated runs:
	// counted from the Gate's answer). <=0: DefaultHookBudget.
	HookBudget time.Duration
}

type Loop struct {
	Client  LLM
	Tools   *tools.Registry
	Limits  Limits
	Gate    Gate      // nil: an Ask is denied
	Compact Compactor // nil: no compaction
	// CheckPrompt is UserPromptSubmit for this run (2.0 F2d; nil: none).
	CheckPrompt PromptCheck
	// Steering is stream rules and the watchdog (2.0 W3; nil: none).
	Steering Steering
	// Advisor is jev_gate (2.0 W3; nil: none): it may turn an allowed call
	// into an Ask, never the reverse.
	Advisor tools.AskAdvisor
	// Refuse, when set, is asked for every call to a known tool before it
	// reaches the registry; a non-empty reason settles the call as an
	// error without running it, its hooks or its permission check (the
	// chat's plan mode, 2.0 W4e). It can only take calls away. It runs on
	// Run's goroutine and is read at call time.
	Refuse func(name string) string

	// Tool hooks run inside Tools (F0); the loop fires no hooks itself.
	// SessionID names the spill directory for oversized results.
	SessionID string
	// SpillDir overrides the spill base directory; "" uses the default
	// (ctxmgr.ToolResultsBaseDir). Only tests set it. recall_tool_result
	// reads from the default base, so with a custom SpillDir the recall id
	// in a capped result's marker does not resolve: the spill file is still
	// written and named, but only that path reaches it.
	SpillDir string
	// SpillCounter numbers spill files across Loops that share it (the chat
	// starts one Loop per turn, 2.0 F2d), so a call ID repeated in a later
	// run never overwrites an earlier spill. nil: counted per Loop.
	SpillCounter *atomic.Int64
	// contains filtered or unexported fields
}

type Message = tui.ChatMessage

type Mode int

type NestedOptions struct {
	// Workspace is the child's workspace; "" means the parent's. A different
	// one (an isolated worktree) gets its own hooks, project context and
	// code graph.
	Workspace string
	// Warn receives the child's own setup warnings; nil means the parent's
	// sink. A shared hooks runner reports to the sink in the ctx of the run
	// that fired the hook (hooks.WithWarn), else to the parent's.
	Warn func(string)
	// Notice receives the child's timing notices (a git snapshot or
	// code-graph update that ran out of time); nil means Warn when Warn is
	// set, else the parent's.
	Notice func(string)
}

type Nester interface {
	Nested(NestedOptions) (*Env, error)
}

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

type PromptCheck func(ctx context.Context, msg Message) (Message, PromptVerdict, error)

type PromptOptions struct {
	// Contract is the agent operating contract (agent mode only).
	Contract string
	// Sliders overrides slider.json (a subagent's persona override).
	Sliders *config.SliderConfig
	// Session is one run's SessionStart context; it never enters the Env.
	Session string
	// Level is the persona level: "" is the mode's profile (chat full,
	// agent spine); prompts.PersonaOff for typed explore and review
	// subagents (2.0 W4e) and orchestrator lanes.
	Level prompts.PersonaLevel
	// Window is the run's model's context window; 0 uses the Env's.
	Window int
}

type PromptVerdict struct {
	Blocked bool
	Reason  string // for the person, never the model
}

type Reminder struct {
	Source string // "rule:<name>" or "watchdog"
	Text   string
}

type Result struct {
	FinalText         string // last assistant text, verbatim
	ToolCallsLastTurn int
	NoToolTurns       int // consecutive tool-free turns at the end of this Run
	StopReason        StopReason
	Turns             int // turns started this Run (an overflow retry is the same turn)
	ToolCalls         int // tool calls executed this Run
	// HistoryEdited: the returned history holds an edit (a prune, or
	// provider blocks stripped after BlocksRejected) that no History
	// snapshot event carried, because the run ended first. A consumer that
	// mirrors the snapshots takes the returned history (2.0 F3).
	HistoryEdited bool
}

type SetupOptions struct {
	SessionID string       // hooks' session_id and checkpoint session; "" = "<mode>-<pid>-<start nanos>"
	Warn      func(string) // setup and hook warnings; nil = stderr
	// Notice gets timing notices (a git snapshot or code-graph update that
	// ran out of time). They depend on the machine, not the configuration.
	// nil = Warn.
	Notice func(string)
	// Approve asks the person to trust a repo hook. Only ModeChat uses it
	// (non-interactive modes never approve, F0); nil there means a terminal
	// prompt when stdin and stderr are terminals.
	Approve hooks.ApproveFunc
	// GlobalMCPOnly skips the workspace's MCP configs in ModeChat too, as
	// every other mode does: a chat whose user cannot be asked before a
	// repo's server starts (ACP, where the editor passes its own servers).
	GlobalMCPOnly bool
}

type Steering interface {
	// Request is called before each request. interrupt cuts that request
	// short; it is a no-op once the request has returned, and nil when the
	// turn has used its re-runs (Observe's answer is then ignored too).
	Request(turn int, interrupt func())
	// Observe sees every event before consumers do. True interrupts the
	// request in flight (only text deltas arrive during one).
	Observe(ev Event) bool
	// Calls sees a turn's complete tool calls before they are recorded or
	// run. True drops the turn's reply and re-runs it.
	Calls(turn int, calls []ToolCall) bool
	// Reminders removes and returns the reminders due at b.
	Reminders(b Boundary) []Reminder
}

type StopReason string

type StreamEnder interface {
	EndStream() bool
}

type ToolCall struct {
	ID    string
	Name  string
	Input map[string]any
	// Key names this one invocation, unique in the process: a model's IDs
	// may repeat or be empty, so whatever binds a permission ask to the
	// call it shows (ACP) keys on Key, never on ID. It is also on the
	// call's context (tools.CallKeyFromContext). Empty outside runCalls.
	Key string
}

type TurnTimeoutError struct {
	Timeout time.Duration
	Err     error
}