agent

type ApprovalDecision uint8

type ApprovalHandler interface {
	RequestApproval(ctx context.Context, name string, args map[string]any) ApprovalDecision
}

type CompactResult struct {
	// Summarized is how many model-visible messages the summary replaced.
	Summarized int
	// Kept is how many messages remain verbatim after the boundary.
	Kept int
	// Summary is what the summarizer produced, after clamping to its budget.
	Summary string
	// Reason explains a pass that compacted nothing. Empty when it did.
	Reason string
}

type CompactionHistory interface {
	MessageHistory
	// PriorSummary returns the summary stored by the most recent compaction, or "" when the
	// history has never been compacted.
	PriorSummary() string
	// AddCompaction advances the compaction boundary by summarizedCount messages and stores summary.
	//
	// It returns an error because a durable history commits here. Compaction
	// changes what the model sees, so a boundary that failed to reach storage
	// would leave the next turn reading a different conversation than this one
	// ended with.
	AddCompaction(summary string, summarizedCount int) error
}

type ContextCompactor interface {
	// Usage is what the summarization itself cost. It is returned rather than
	// left to the implementation to report because compaction is a model call
	// the run caused: a total that omits it understates exactly the long
	// sessions where it matters most. A compactor that does not call a model
	// returns the zero Usage.
	Compact(ctx context.Context, msgs []llm.Message) (summary string, usage llm.Usage, err error)
}

type ContextSources struct {
	// ProjectID names the scope shared memory belongs to, empty for a run that
	// has none.
	ProjectID string `json:"project_id,omitempty"`
	// Workspace is the root this run executed against, which for a Project with
	// several worktrees is not derivable from ProjectID.
	Workspace string `json:"workspace,omitempty"`
	// Instructions are the system-prompt layers, in order. Written even when
	// there is nothing beyond the runtime prompt: an absent list would read as
	// "nobody looked" rather than "there was nothing else".
	Instructions []PromptLayer `json:"instructions,omitempty"`
	// Memory is every fallible recall source this run loaded.
	Memory []MemorySourceInfo `json:"memory,omitempty"`
	// HistoryProjection describes what stood in for messages the run no longer
	// holds in full.
	HistoryProjection HistoryProjection `json:"history_projection"`
}

type DelegatedStats struct {
	// Runs counts delegated runs, not the calls that started them.
	Runs             int
	PromptTokens     int
	CompletionTokens int
	CacheReadTokens  int
	CacheWriteTokens int
	ToolCalls        int
	Cost             *llm.Cost
	CostIncomplete   bool
}

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

type Event struct {
	Kind EventKind

	// EventIterStart, EventLLMStart, EventLLMEnd, EventUserInput, EventUserInputBlocked
	Iter int

	// EventLLMDelta, EventLLMEnd, EventUserInput, EventUserInputBlocked
	Content string

	// EventLLMEnd
	HasToolCalls bool

	// EventLLMStart, EventLLMEnd
	ContextTokens    int
	ContextWindow    int
	PromptTokens     int
	CompletionTokens int
	// CacheReadTokens and CacheWriteTokens are the run's cached prompt so far.
	// They are a breakdown of PromptTokens, not an addition to it.
	CacheReadTokens  int
	CacheWriteTokens int

	// EventLLMEnd
	//
	// The counts above are the run's totals so far; these are what this one
	// call did. Both are carried because they answer different questions —
	// what the run has spent, and which turn spent it — and deriving the
	// second by subtracting consecutive records is a trap for anyone reading a
	// trace where a call failed in between.
	CallUsage llm.Usage
	// CallCost is what this call is estimated to have cost, nil when the model
	// was unpriced. Zero would read as a free call.
	CallCost *llm.Cost

	// EventToolStart, EventToolEnd, EventToolDenied
	ToolName   string
	ToolCallID string
	ToolArgs   string // JSON-encoded arguments

	// EventToolEnd
	ToolResult   string
	ToolDuration time.Duration
	// ToolErrorKind names how the call failed, empty when it did not.
	//
	// It reports a call that could not complete, not a task that went badly.
	// A tool that ran and reported a bad outcome — a command exiting non-zero,
	// a search matching nothing — succeeded at this boundary, and reading this
	// field as a failure rate would flatter exactly the runs that are going
	// worst.
	ToolErrorKind string

	// EventToolDenied, EventUserInputBlocked
	DenyReason string

	// EventContextCompacted
	//
	// CallUsage and CallCost above are set here too: compaction is a model
	// call the run paid for, so it is priced like any other.
	Summarized int
	Kept       int

	// EventRunEnd
	Stats RunStats
	Err   error // nil on success or graceful cancellation
}

type EventKind uint8

type HistoryProjection struct {
	CompactionPresent bool `json:"compaction_present"`
	Chars             int  `json:"chars,omitempty"`
}

type HookDecision string

type HookEvent string

type HookInput struct {
	Event     HookEvent `json:"event"`
	SessionID string    `json:"session_id,omitempty"`
	Workspace string    `json:"workspace,omitempty"`

	// IsSubagent is true when the event fires inside a subagent run.
	// AgentType identifies which subagent (its def name). Both fields are
	// stamped on every event from a subagent so audit hooks can attribute.
	IsSubagent bool   `json:"is_subagent,omitempty"`
	AgentType  string `json:"agent_type,omitempty"`

	// Populated for HookUserPromptSubmit.
	Prompt string `json:"prompt,omitempty"`

	// Populated for HookPreToolUse, HookPostToolUse, HookPostToolUseFailure,
	// and HookNotification (when tied to an approval flow).
	ToolName   string         `json:"tool_name,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolArgs   map[string]any `json:"tool_args,omitempty"`

	// Populated for HookPostToolUse (result string) and
	// HookPostToolUseFailure (error string).
	ToolResult string `json:"tool_result,omitempty"`
	ToolError  string `json:"tool_error,omitempty"`

	// Populated for HookNotification: see NotificationApprovalRequired /
	// NotificationPermissionDenied. NotificationReason carries any extra
	// human-readable context.
	NotificationKind   string `json:"notification_kind,omitempty"`
	NotificationReason string `json:"notification_reason,omitempty"`

	// Populated for HookPreCompact (about-to-summarize counts) and
	// HookPostCompact (final counts plus summary).
	Summarized int    `json:"summarized,omitempty"`
	Kept       int    `json:"kept,omitempty"`
	Summary    string `json:"summary,omitempty"`

	// Populated for HookStop, HookSubagentStop, HookStopFailure, and
	// HookSessionEnd.
	Stats *RunStats `json:"stats,omitempty"`
	// Populated for HookStopFailure (the failure message).
	Error string `json:"error,omitempty"`

	// Populated for HookWorktreeCreate, HookWorktreeRemove, and
	// HookCwdChanged. Workspace carries where the session is now; these say
	// which tree it is and, for a move, where it came from.
	WorktreePath      string `json:"worktree_path,omitempty"`
	WorktreeBranch    string `json:"worktree_branch,omitempty"`
	PreviousWorkspace string `json:"previous_workspace,omitempty"`

	// Sandbox is the runtime sandbox snapshot for the current run.
	// Populated on HookSessionStart (always) and on every gating event
	// thereafter so hooks can enforce policy like "fail if the sandbox
	// is off on the worker" without having to read settings themselves.
	Sandbox *SandboxInfo `json:"sandbox,omitempty"`
}

type HookOutput struct {
	Decision HookDecision `json:"decision,omitempty"`
	Reason   string       `json:"reason,omitempty"`
}

type HookRunner interface {
	Run(ctx context.Context, in HookInput) HookOutput
}

type MemoryBody struct {
	Name        string
	Description string
	Type        string
	Body        string
}

type MemoryIndex struct {
	ScopeID string
	Entries []MemoryIndexEntry
}

type MemoryIndexEntry struct {
	Name        string
	Description string
}

type MemorySourceInfo struct {
	Name     string `json:"name"`
	Revision int    `json:"revision,omitempty"`
	Digest   string `json:"digest,omitempty"`
	Chars    int    `json:"chars,omitempty"`
	Entries  int    `json:"entries,omitempty"`
}

type MemoryStore interface {
	// Index is called on every model call, so another session's committed
	// write is visible on the next iteration rather than at the end of the run.
	Index() MemoryIndex

	// Read returns the named bodies and, separately, the names that do not
	// exist -- a missing name is an answer, not a failed call. The
	// implementation records what it returned, which is what lets Write refuse
	// a replacement whose body this run has never seen.
	Read(ctx context.Context, names []string) ([]MemoryBody, []string, error)

	// Write creates or replaces one memory. Creating a name that does not exist
	// is always accepted; replacing one requires that this run read it.
	Write(ctx context.Context, upsert MemoryUpsert) (MemoryBody, error)

	// Delete removes one memory.
	Delete(ctx context.Context, name string) error
}

type MemoryUpsert struct {
	Name        string
	Description string
	Type        string
	Body        string
	// VerifiedAt is the date, as YYYY-MM-DD, that a memory caching something
	// expensive was last checked against the source its body names. Empty
	// leaves an existing date alone: rewording is not re-verifying.
	VerifiedAt string
}

type MessageHistory interface {
	HistoryMessages() []llm.Message
	Append(m llm.Message) error
}

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

type NoopSandbox struct{}

type Note struct {
	Text string `json:"text"`
	// WrittenIteration is the loop iteration at which this entry first appeared. Rewriting the list
	// with the same text does not reset it, so the value reflects the entry's age rather than
	// the age of the last write.
	WrittenIteration int `json:"written_iteration,omitempty"`
}

type NoteStore interface {
	Notes() []Note
	// SetNotes replaces the stored notes. Entries whose text is unchanged keep their original
	// WrittenIteration; iter stamps the rest.
	//
	// It returns an error because a durable store commits here, and durable
	// state that silently failed to commit is worse than one that says so: the
	// next turn would render notes the file does not have.
	SetNotes(notes []Note, iter int) error
	Todos() []Todo
	// SetTodos replaces the stored todos. Entries whose content and status are both unchanged
	// keep their original WrittenIteration; iter stamps the rest, so a status change restarts the clock.
	SetTodos(todos []Todo, iter int) error
}

type NotesHistory interface {
	MessageHistory
	NoteStore
}

type PendingInput interface {
	// Dequeue removes and returns the oldest waiting message. The bool is false
	// when nothing is waiting; RunLoop calls it until it reports false.
	Dequeue() (string, bool)
}

type PromptLayer struct {
	Name  string `json:"name"`
	Chars int    `json:"chars"`
}

type RunLoopOpts struct {
	LLMClient    llm.LLMClient
	SystemPrompt string
	// Pricing prices each call as it completes. Zero leaves every cost nil,
	// which is what a model nobody priced — or a managed one, where the server
	// holds the rates and records what it charged — reports.
	//
	// It is priced here rather than after the run because a run is where the
	// rates are known to still be the ones that applied: recomputing later from
	// whatever is configured then restates money already spent.
	Pricing      llm.Pricing
	ToolRegistry llm.ToolRegistry
	// MaxIter caps how many times the loop may call the model. The caller
	// settles it — config.ResolveMaxIterations is where a surface gets one —
	// because the bound belongs to the run being asked for, not to the loop.
	// Zero runs nothing and reports the cap as exceeded.
	MaxIter    int
	History    MessageHistory
	StreamSink llm.StreamSink
	// Policy is consulted before each tool execution. Nil defaults to AllowAllPolicy().
	Policy ToolPolicy
	// Approval is invoked when Policy returns ToolActionAsk.
	// Nil approval with ToolActionAsk denies the call: an unattended surface
	// must not widen Ask into Allow.
	Approval ApprovalHandler
	// PendingInput carries messages the user submitted after this run started.
	// They are appended to the history at the next iteration boundary, so they
	// reach the model after the current batch of tool calls rather than after the
	// whole run. Nil disables mid-run injection entirely.
	PendingInput PendingInput
	// Grants holds approvals the user chose to keep for the session. It is owned
	// by the caller because a session outlives one RunLoop; nil grants nothing,
	// which makes every Ask a fresh prompt.
	Grants *SessionGrants
	// MaxParallelTools bounds how many calls from one assistant message may be
	// grouped to run together. Zero or one keeps every call in its own group,
	// which is the sequential behaviour and the current default on every
	// surface. See docs/design/parallel-tool-execution.md.
	MaxParallelTools int
	// Compactor summarizes old messages when the context window is filling up.
	// Nil disables compaction; TrimHistory is used as a fallback.
	Compactor ContextCompactor
	// Checkpointer is given one turn to save durable state before a compaction discards
	// messages. Nil skips the checkpoint; compaction is unaffected either way.
	Checkpointer StateCheckpointer
	// Invariants is the hard-constraint section of the run's additional system prompt, restated
	// after the message list on every call. That text is already in SystemPrompt and never
	// leaves it; this is about proximity, not storage, so it carries only the part the author
	// marked as non-negotiable. Empty is the normal case.
	Invariants string
	// Memory supplies the resident index of cross-session recall, rendered
	// after the message list and before the session-state anchor. Nil is the
	// normal case for a run that has no such scope -- a worker, an evaluation,
	// a subagent, a session whose user turned memory off -- and costs nothing.
	Memory MemoryStore
	// EventSink receives structured runtime events from the agent loop.
	// Nil disables event emission entirely (zero overhead).
	// The callback may be invoked from the RunLoop goroutine or from a tool
	// worker. The runtime serialises the calls, so a sink sees one event at a
	// time, but it must not block and must not assume one tool is in flight:
	// pair EventToolStart with EventToolEnd by ToolCallID, not by arrival.
	EventSink func(Event)
	// Hooks runs lifecycle hooks at fixed points (PreToolUse, PostToolUse,
	// PostToolUseFailure, Notification, PreCompact, PostCompact, Stop /
	// SubagentStop / StopFailure). Nil disables hooks.
	// PreToolUse and PreCompact hooks may block their respective actions.
	Hooks HookRunner
	// SessionID is forwarded to hook payloads so external scripts can correlate runs.
	// Optional; an empty value is omitted from hook input.
	SessionID string
	// Workspace is forwarded to hook payloads so external scripts can locate files
	// under the active workspace. Optional.
	Workspace string
	// IsSubagent is true when this RunLoop is a subagent execution. It
	// flips the lifecycle event on success from Stop to SubagentStop and
	// is stamped on every event from this run for audit attribution.
	IsSubagent bool
	// AgentType is the subagent definition name when IsSubagent is true.
	// Empty for main-agent runs.
	AgentType string
	// RedactResult removes a run's materialized Space Secret values from a tool
	// result before it enters the model context, the trace, the hooks, and the
	// application log. It is a plain function so this package depends on no
	// redactor; agentapp supplies one built from the run's grant values. Nil
	// leaves results unredacted, which is what every surface with no Secret
	// grants passes. See docs/design/space-secrets.md §12.
	RedactResult func(string) string
}

type RunStats struct {
	ToolCalls        int
	PromptTokens     int
	CompletionTokens int
	CacheReadTokens  int
	CacheWriteTokens int
	// Cost is the run's estimated spend, nil when no call in it could be
	// priced. CostIncomplete says a call did work that could not be priced, so
	// the total understates the run rather than covering it.
	Cost           *llm.Cost
	CostIncomplete bool
	// Delegated is what subagent runs this one started spent. It is a
	// breakdown of the token and cost fields above, not an addition to them:
	// the totals are what the run cost, whoever executed the calls. Nil when
	// the run delegated nothing.
	Delegated *DelegatedStats
}

type SandboxInfo struct {
	Enabled    bool     `json:"enabled,omitempty"`
	Mode       string   `json:"mode,omitempty"`
	Backend    string   `json:"backend,omitempty"`
	Sources    []string `json:"sources,omitempty"`
	Downgraded bool     `json:"downgraded,omitempty"`
}

type SandboxView interface {
	// Enabled reports whether the sandbox is active for this run. When
	// false, tools should fall back to current (pre-sandbox) behavior.
	Enabled() bool

	// Mode is "auto_allow" or "regular". See docs/design/sandbox-boundaries.md §5.
	// Returns "" when Enabled() is false.
	Mode() string

	// Backend identifies the OS backend providing isolation
	// ("seatbelt", "bwrap", "none"). Returns "none" when the sandbox
	// is enabled in settings but the OS backend is unavailable.
	Backend() string

	// WrapBashCommand returns the (binary, argv) the Bash tool should
	// exec to run the given command isolated by the active backend.
	// `shell` is the inner shell the backend should invoke
	// (e.g. "/bin/bash"); on unsupported platforms or when not wrapping
	// the caller should fall back to its own default invocation.
	//
	// When (name == "" && err == nil) the caller must run the command
	// unwrapped. This is how NoopSandbox signals "do nothing." Phase B
	// fills in the real wrap; Phase A only ships NoopSandbox.
	//
	// ctx allows cancellation of any backend preparation (writing a
	// Seatbelt profile to disk, etc.).
	WrapBashCommand(ctx context.Context, command, shell string) (name string, args []string, err error)

	// ShouldSandboxCommand reports whether the command should be wrapped.
	// Honors the excluded_commands list (commands the user has opted
	// out of the sandbox). Returns false when Enabled() is false.
	ShouldSandboxCommand(command string) bool

	// HostAllowed reports whether outbound network requests to host are
	// permitted by the sandbox policy, plus a short reason when denied.
	// When Enabled() is false this returns (true, "") — no enforcement.
	//
	// Non-bash tools (WebFetch, the http hook driver) consult this
	// before issuing requests so the same allow-list governs every
	// network egress path in the agent. The bash sandbox enforces the
	// same policy at the OS level via the in-process proxy.
	HostAllowed(host string) (ok bool, reason string)

	// ProxyAddress returns the listen address of the in-process HTTP
	// proxy ("127.0.0.1:<port>") when one is running, otherwise "".
	// Surfaces in `buildmax sandbox status`; backends use it to direct
	// child processes via HTTP_PROXY env.
	ProxyAddress() string

	// ScrubEnv returns env with secret-shaped variables removed. Applied
	// by the Bash tool before composing the sandboxed child env so
	// agent-process secrets (API keys, tokens, worker auth) do not
	// leak into untrusted subprocesses. Returns input unchanged when
	// Enabled() is false.
	ScrubEnv(env []string) []string

	// AllowUnsandboxed reports whether the per-call
	// `dangerously_disable_sandbox` arg is honored. When false ("strict
	// sandbox mode"), the arg is ignored and the call is wrapped
	// regardless. Mirrors Claude Code's allowUnsandboxedCommands.
	AllowUnsandboxed() bool

	// ChildEnv returns env-var "KEY=VALUE" entries the caller should add
	// to spawned child processes when the sandbox is active. Includes
	// HTTP_PROXY routing so cooperating tools (curl, wget, git http)
	// reach the network through the host-filtered proxy. Returns nil
	// when no injection is needed. Unlike backend-specific env knobs
	// (bwrap --setenv, sandbox-exec -D), this entry point works on every
	// platform because the bash tool sets cmd.Env itself.
	ChildEnv() []string
}

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

type StateCheckpointer interface {
	Checkpoint(ctx context.Context, discarded []llm.Message) error
}

type Todo struct {
	Content    string `json:"content"`
	Status     string `json:"status"`
	ActiveForm string `json:"active_form,omitempty"`
	// WrittenIteration is the loop iteration at which this entry last changed status. It is what
	// makes "in progress for 40 iterations" reportable.
	WrittenIteration int `json:"written_iteration,omitempty"`
}

type ToolBoundaryHistory interface {
	MessageHistory
	// ToolExecutionStarted records that these approved calls are about to run.
	// It must not return until that record is durable, because everything it
	// is for depends on surviving the tool it precedes.
	ToolExecutionStarted(calls []ToolCallStart) error
	// AppendToolResult records one call's observed outcome and projects it into
	// the conversation, replacing the tool-role Append a plain history takes.
	AppendToolResult(out ToolOutcome) error
}

type ToolCallStart struct {
	ID   string
	Name string
}

type ToolOutcome struct {
	ID     string
	Name   string
	Status string
	Result string
	Parts  []llm.ContentPart
}

type ToolPolicy interface {
	Check(name, scope string, args map[string]any) (llm.ToolAction, bool)
}