agent

type Event struct {
	Kind       EventKind
	ToolCallID string // stable correlation key for tool lifecycle events
	Name       string
	Detail     string
	Content    string
	Input      string // bounded, redacted tool input preview
	Output     string // bounded, redacted tool output preview
	// Denied is set only for EventHook: true when this run blocked its tool
	// call (a PreToolUse hook that denied). Renderers use it to give a
	// blocking run a distinct visual treatment from an advisory one.
	Denied bool
	// Program and Tool are set only for EventHook: the hook script's name
	// (not its path) and the tool it fired for. Name already carries the
	// hook's own event (PreToolUse/PostToolUse/Stop) for this kind, so these
	// are separate fields rather than an overload of an existing one.
	Program, Tool string
	// Origin attributes the event to the producing agent (zero = root loop).
	Origin EventOrigin
	// Identity is an optional typed runtime identity supplied by a routed
	// invocation. It contains no content or authorization material.
	Identity *events.Identity
	// Compaction is present only for the post-commit typed progress event. It
	// is not copied into generic content/input/output envelopes.
	Compaction *events.CompactionEvent
	// CacheUsage is present only for the typed prompt-cache accounting
	// event. It is not copied into generic content/input/output envelopes.
	CacheUsage *events.CacheUsageEvent
	// TokenUsage is present only for the typed token accounting event. It is
	// not copied into generic content/input/output envelopes.
	TokenUsage *events.TokenUsageEvent
}

type EventKind string

type EventOrigin struct {
	TaskID string // runtime request/task id - the attribution key
	Agent  string // dispatched subagent/skill name
	Depth  int    // nesting depth (root loop = 0)
	// TaskDescription is a bounded preview of the task this subagent was
	// given (see StampEventOrigin's caller), so a consumer attributing
	// events by TaskID can show what the subagent is actually doing without
	// having to separately correlate the initiating delegate/dispatch_tasks/
	// spawn_agent tool call's own Input. Empty for the root loop (zero
	// EventOrigin) and for any subagent kind that doesn't stamp origin at
	// all (a one-shot delegate has no nested tool calls to attribute).
	TaskDescription string
}

type Loop struct {
	Completer provider.Completer
	Tools     *tools.Registry
	Messages  []provider.Message
	// LastPreparation is retained only after the final provider request
	// succeeds. The owning chat surface commits it; the loop never publishes.
	LastPreparation contextmgr.Preparation
	HasPreparation  bool

	// PreparationErr records an interrupted recovery failure so the session can
	// surface the real cause instead of misreporting a checkpoint conflict.
	PreparationErr error
	// LastFinishReason is the provider finish reason of the last successfully
	// completed step of the most recent Run: "stop", "tool_calls", "length",
	// or another provider vocabulary value. Empty when no step completed. The
	// schema-repair loop reads it to distinguish a reply truncated by the
	// output budget (finish_reason "length") from ordinary invalid JSON, so it
	// can say so honestly instead of re-prompting with the same budget.
	LastFinishReason string
	// Calibration tracks the rolling EWMA correction ratio between estimated
	// and provider-reported token usage. It is updated after every successful
	// provider response that reports usage, and its Ratio is passed to
	// context planning and token usage events. The zero value (Ratio=0) is
	// safe: applyCalibration treats 0 as 1.0 (no correction).
	Calibration contextmgr.Calibration

	// TurnState accumulates bounded, content-free host facts (omitted-message
	// evidence, tool names, changed surfaces, risks, latest assistant state)
	// for the summary envelope of the current run. Reset at Run start; it
	// never leaves the loop and is never consulted by planning, commit, or
	// checkpoint fingerprinting.
	TurnState *contextmgr.TurnState
	// contains filtered or unexported fields
}

type Options struct {
	Model       string
	Temperature *float64
	MaxTokens   *int
	// AdvertisedToolSpecs, when non-nil, is the tools[] array Run serializes
	// on every step of this turn - the host's pinned, binding-lifetime
	// snapshot (plan tools-advertising/01), computed once from the session's
	// admissible union and byte-identical across turns and admissions. Run
	// falls back to Tools.OpenAITools() when nil, which is today's behavior:
	// subagent and workflow-engine loops that never set this field are
	// unaffected.
	AdvertisedToolSpecs []provider.ToolSpec
	// Reasoning is the selected model's reasoning dial, carried onto every
	// request this loop makes. Its zero value sends nothing.
	Reasoning  reasoning.Setting
	MaxSteps   int
	WorkLimits runtime.WorkLimits
	// PreserveWorkLimits keeps cumulative reservations across a corrective
	// re-entry of the same task invocation.
	PreserveWorkLimits    bool
	DisableProviderReplay bool
	// MaxContextTokens sets the approximate token limit for the prompt context.
	// Pruning is hysteretic, mirroring contextmgr.Plan: history is left
	// untouched below 80% of the budget, and once that trigger is crossed old
	// turns are dropped (keeping system prompt and recent turns) down to ~50%,
	// so one provider prompt-cache miss buys many cache hits before the next.
	// 0 or negative means no pruning.
	MaxContextTokens int
	// MaxToolResultChars caps each tool result stored in conversation history,
	// in BYTES despite the name (it bounds len() of the UTF-8 body; see
	// capToolResult). This prevents a single large output (e.g. read_file of
	// 256KB) from exceeding the context budget. 0 means no cap (use full
	// result); per-tool Capability.MaxResultBytes budgets still apply. To bound
	// one oversized result against the prompt budget while keeping full results
	// the default, set BatchResultBudgetBytes < 0 (derived batch budget)
	// instead.
	MaxToolResultChars int
	// BatchResultBudgetBytes bounds the bytes ONE tool batch may add to
	// history, across all its parallel calls together. Per-call caps cannot
	// see each other, so N calls each honestly under its own cap still blow
	// the context when they land in the same step; this is the only bound that
	// sees the batch as a whole.
	//
	// 0 (the default) disables the mechanism entirely - shapeBatch is not
	// invoked and the append path is byte-identical to having no budget.
	// Negative derives it from MaxContextTokens (inert when that is unset).
	// Positive is the literal byte budget. Scope is one runToolBatch: nothing
	// is charged across compaction boundaries, where cross-batch growth is
	// already compaction's job.
	BatchResultBudgetBytes int
	// RefOnlyTools lists tool names whose results are never inlined into the
	// model context when they exceed BatchDegradeFloorBytes; instead the whole
	// body is spooled to RemainderSpool and the notice names a remainder ref
	// (read_output) that the model can fetch. Empty/absent names keep normal
	// degrade behavior.
	RefOnlyTools         []string
	MaxToolCallsPerBatch int
	MaxConcurrentTools   int
	ToolTimeout          time.Duration
	// ToolRunTimeout is the SDK tool-registry's registry-wide run-timeout
	// backstop for tools that declare no Capability.Timeout (the [tools]
	// tool_run_timeout_seconds knob). <= 0 (the default) maps to the SDK's
	// TimeoutNone: no registry-wide cap, because the dispatcher shim
	// already arms every call's Capability.Timeout / ToolTimeout as a real
	// deadline and the SDK backstop must never be tighter than those
	// declared budgets. Positive is the literal bound.
	ToolRunTimeout time.Duration
	RequestTimeout time.Duration
	ParentID       string
	TurnID         string
	SessionID      string
	Role           string
	Depth          int
	// Step is the loop's 1-based model-step index, stamped per step on the
	// loop's own Options copy before tool calls are dispatched (plan:
	// step-scoped tool dedup). 0 means unset/legacy.
	Step       int
	Budget     int
	Dispatcher *runtime.Dispatcher
	// StagedToolMessage returns the denial message for a tool call to a name
	// staged for loading (load_tools) but not yet published to the live tool
	// surface, plus true. The loop calls it only when the name is absent from
	// its registry. The returned message announces why publication is pending;
	// nil means no check and the generic denial message is used. It must be
	// safe for concurrent calls.
	StagedToolMessage func(name string) (string, bool)
	// UnadmittedToolHandler is checked when a call names a tool absent from
	// the live registry AND StagedToolMessage found no pending stage for it.
	// It lets the host recognize a tool that IS advertised (plan
	// tools-advertising/01: the wire tools[] array now includes every
	// deferred candidate, not just admitted ones) but not yet admitted for
	// execution: auto-stage it for native publication at the next step
	// boundary (so later calls in the turn need no special handling), AND
	// serve THIS call synchronously against the full authorized tool set
	// when possible, so the model never sees an error for a call it already
	// made correctly. Handled=false means the name is not recognized at all
	// (a hallucinated tool) and the caller falls through to the generic
	// denial. Nil disables the check. Must be safe for concurrent calls.
	UnadmittedToolHandler func(ctx context.Context, name string, args json.RawMessage) UnadmittedToolResult
	// ApprovalGate is the synchronous user-approval bridge for tool calls.
	// It is invoked by executeToolTask and by the SDK-path approval wrapper
	// before Dispatcher.Invoke for any tool whose capability.Class >=
	// tools.ExecutionWrite; tools of class ExecutionRead or Unclassified
	// skip the call. The function MUST be safe to call concurrently from
	// multiple goroutines (parallel tool batches). A nil gate is equivalent
	// to "approve every call": the loop runs as if there were no approval
	// surface at all, matching pre-Phase-4 behavior.
	ApprovalGate func(ctx context.Context, name string, args json.RawMessage) sdkadapter.ApprovalResult
	// ApprovalStanding is consulted BEFORE ApprovalGate to honor "always"
	// decisions ("a always" / "D deny always"). It is keyed on tool name
	// and carries a verdict (approved or denied) plus a class tag so the
	// same call short-circuits the gate for the rest of the session.
	// Nil is safe: every call falls through to ApprovalGate. The same
	// instance backs the SDK-path wrapper so a "always" decision persists
	// across legacy and SDK turns within one session.
	ApprovalStanding *sdkadapter.ApprovalStanding
	// ApprovalPolicy controls tool execution approval policy ("write-only", "auto" / "never" [yolo], "always").
	ApprovalPolicy string
	// RemainderSpool, when non-nil, stores truncated tool-result bodies under
	// content refs so the model can page them via read_output. Nil means
	// truncation notices omit refs (legacy plain notices).
	RemainderSpool *remainder.Spool
	OnEvent        func(Event)
	EventBus       *events.Bus // publishes agent events to extensible delivery
	// EventIdentity is a validated public identity snapshot for this turn.
	EventIdentity *events.Identity
	// UsageWriter, when non-nil, durably records token/cache/compaction usage
	// measurements alongside the existing EventBus publish. Nil keeps usage
	// events exactly as ephemeral as they are today (subagent/workflow-engine
	// loops that never set this field are unaffected).
	UsageWriter usage.UsageWriter
	FinalWriter io.Writer
	// RequireFinalText fails a turn that produced no assistant text anywhere
	// instead of reporting an empty success. Interactive surfaces set it: a turn
	// that renders as "done" with no answer is indistinguishable from the agent
	// stopping for no reason. Sub-agents leave it false, because buildResult
	// discards a task's output whenever its error is non-nil, and a task that
	// did its work through tools and then stopped without prose did succeed.
	RequireFinalText bool
	// PreparationManager is an optional root-owned preparation capability. It
	// has no checkpoint publisher and is therefore safe to pass to nested loops.
	PreparationManager contextmgr.PreparationManager
	PreparationInput   contextmgr.PrepareInput
	// SummaryConfig wires the optional LLM summarizer into the request path. A
	// nil Summarizer keeps the loop structural-only: no summary provider call,
	// no injected message, byte-identical requests. Redaction is the host's
	// compiled redaction policy applied to summary input and output through
	// the summary validators.
	SummaryConfig SummaryConfig
	// BeforeStep, when set, is called on the loop goroutine at the top of each
	// step before history pruning and request build (plan 53.03). Returned
	// messages are appended to the loop history. Nil is a no-op.
	BeforeStep func() []provider.Message
	// InterruptCh, when non-nil, resolves the channel a parent can signal to
	// softly interrupt the in-flight LLM call (plan 54). It is re-read once
	// per LLM call. Nil disables the signal path. A steer never cancels a tool
	// batch: only the LLM-scoped context is cancelable.
	InterruptCh func() <-chan struct{}
	// MailboxPending, when non-nil, reports whether ANY message is waiting in
	// the mailbox. The watchdog path cancels only when it returns true, so a
	// stale signal after a drain can never cancel a call. The interrupt-signal
	// path uses the stricter MailboxPendingInterrupt, so a stale signal paired
	// with a later non-interrupt message is never a cancel.
	MailboxPending func() bool
	// MailboxPendingInterrupt, when non-nil, reports whether an
	// Interrupt-flagged steer is queued. The watcher's signal branch cancels
	// only when it returns true; the watchdog branch keeps gating on
	// MailboxPending (any pending message bounds non-urgent steer latency).
	// Nil disables the signal gate.
	MailboxPendingInterrupt func() bool
	// WatchdogInterval bounds steer latency when no interrupt signal is wired:
	// with a steer pending, the in-flight LLM call is softly interrupted at
	// most this often. 0 disables the watchdog.
	WatchdogInterval time.Duration
	// SoftInterruptCooldown caps soft-interrupt frequency across calls: at
	// most one interrupt per window. 0 disables the cooldown (tests). The
	// production 5s default lives in the subagents wiring, NOT here.
	SoftInterruptCooldown time.Duration
	// Surface, when non-nil, is invoked by Loop.Run at the top of EVERY step
	// iteration (before runStep, hence before BeforeStep inside prepareStep) to
	// fetch that step's host surface. Non-nil fields of the returned Surface
	// are applied to that step only; nil fields leave the loop's own state
	// unchanged. The host must supply Registry, Dispatcher, and ToolSpecs from
	// one consistent read so the registry/dispatcher/spec agreement invariant
	// (M3) holds for the step. Nil is a no-op.
	Surface func() Surface
}

type SummaryConfig struct {
	// Summarizer is the captured provider/model/policy binding. Nil disables
	// summary injection entirely.
	Summarizer *contextmgr.Summarizer
	// UnavailableReason names the setup-time failure that prevented a Summarizer
	// from being wired, when Summarizer is nil.
	UnavailableReason string
	// Redaction is the host's compiled redaction policy. It classifies every
	// envelope field and every provider output before anything reaches the
	// wire or storage.
	Redaction contextstate.RedactionPolicy
}

type Surface struct {
	Registry       *tools.Registry
	Dispatcher     *runtime.Dispatcher
	ToolSpecs      []provider.ToolSpec
	RemainderSpool *remainder.Spool
}

type UnadmittedToolResult struct {
	// Handled is false when the handler has no opinion on this tool name at
	// all (not advertised, a hallucinated name); the caller falls through to
	// its own generic "not available" denial. True for every other case.
	Handled bool
	// Ran is true when the tool was actually executed synchronously and
	// Content is its real, successful result: the caller must render it
	// exactly like an ordinary successful tool call - no "error: " prefix,
	// no failed tool_end, no denial framing anywhere the model or the
	// operator can see. False means Content is a human-readable denial
	// reason instead (e.g. staged but could not run synchronously); the
	// caller applies its own "error: " framing as before.
	Ran bool
	// Content is the tool's real result (Ran) or the denial text (!Ran).
	Content string
	// HookRuns are the lifecycle hooks that executed for this call, for the
	// OPERATOR's view. Set on the Ran path AND on a !Ran path whose cause
	// was a PreToolUse block - the case an operator most needs to see, since
	// it is the run that stopped the call. It must be nil for a dedup-served
	// duplicate: a duplicate is answered with the OWNER's runs (DC-9), which
	// did not execute for THIS call, so reporting them would show a hook
	// firing that never fired here. Nil when the handler never reached the
	// dispatcher at all.
	HookRuns []runtime.HookRun
	// HookContext is the advisory text lifecycle hooks produced for this
	// call, for the MODEL. The caller frames it through appendHookContext,
	// so it gets the same delimiting and tag-neutralization the ordinary
	// dispatcherShim.Run path applies. Unlike HookRuns it IS set for a
	// dedup-served duplicate: DC-9 answers a duplicate with the owner's
	// post-hook Result, and the shim appends that context too. Set but
	// currently unused on a !Ran (denial) result: the denial text is left
	// unchanged until a PreToolUse block's own advisory context is threaded
	// too (see runDeferredToolNow's doc comment).
	HookContext string
}