agentcore

type AccountScopedProviderState = protocol.AccountScopedProviderState

type AfterToolCall func(ctx context.Context, call ToolCall, result string, runErr error) (rewritten string, terminate bool)

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

type AgentDefinition struct {
	ScopeID     string
	Soul        string      // SOUL.md — who the agent is (always loaded)
	Agents      string      // AGENTS.md — what it works on (always loaded)
	Skills      []Skill     // headers selected by description match; body loads on demand
	SkillLoader SkillLoader // optional deferred content loader for selected skills
}

type AgentEndHook func(ctx context.Context, res RunResult)

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

type ArgPreparer interface {
	PrepareArguments(raw string) string
}

type BackgroundLauncher func(tool, label string, run func(context.Context) (string, error)) (json.RawMessage, error)

type BatchDecision struct {
	// AdditionalContexts are appended after the batch's tool results and
	// persisted, exactly like ToolResultDecision.AdditionalContexts.
	AdditionalContexts []Message
}

type BatchInterceptor interface {
	InterceptBatch(ctx context.Context, calls []ToolCall) BatchDecision
}

type BeforeAgentStartHook func(ctx context.Context, start RunStart) RunStart

type BeforeCompactHook func(ctx context.Context, req CompactRequest) CompactDecision

type BeforeToolCall func(ctx context.Context, call ToolCall) Decision

type BookkeepingTool interface {
	// Bookkeeping reports that calls to this tool are not task progress.
	Bookkeeping() bool
}

type BranchOptions struct {
	// Summarize, when non-nil, distills the messages of the abandoned span (old
	// leaf back to the common ancestor with the target, exclusive) into an
	// EntryBranchSummary appended to the new branch, so context from the
	// abandoned work survives the switch (pi's branch summarization on /tree).
	// A summarizer error or empty summary degrades to a bare leaf move — a
	// rewind never fails on a flaky summarizer. The returned Usage is the
	// summarization call's own spend; Rewind stamps it onto the branch-summary
	// entry so this real provider call is never invisible spend.
	Summarize func(ctx context.Context, abandoned []Message) (string, Usage, error)
}

type BudgetPlugin struct {
	Gate func(ctx context.Context, u Usage) bool
	Step func(ctx context.Context, turn int) error
}

type CallRetrySafeTool interface {
	RetrySafeCall(call ToolCall) bool
}

type CapabilitySupport = protocol.CapabilitySupport

type CardPoint struct {
	Label string  `json:"label"`
	Value float64 `json:"value"`
}

type CardStat struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type ChatDelta = protocol.ChatDelta

type ChatRequest = protocol.ChatRequest

type ChatResponse = protocol.ChatResponse

type CheckpointState struct {
	Model         string   `json:"model,omitempty"`
	ActiveTools   []string `json:"active_tools,omitempty"`
	DisabledTools []string `json:"disabled_tools,omitempty"`
	Goal          string   `json:"goal,omitempty"`
	// Completed records whether an EntryLeaf was already seen before this
	// checkpoint — true only on a chained log whose earlier run finished. Without
	// it a window would report a chained session as unfinished where the whole
	// log reports it finished, and the two reads would disagree about whether
	// there is an answer to reattach to.
	Completed bool `json:"completed,omitempty"`
}

type ChildQuestionError struct {
	SessionID  string          `json:"sessionId"`
	QuestionID string          `json:"questionId"`
	Question   json.RawMessage `json:"question"`
}

type CompactDecision struct {
	// Skip abandons compaction for this turn. The transcript is left as-is, so a
	// hook that skips forever will run the context past its budget; use it to
	// defer (e.g. mid-tool-sequence), not to disable compaction.
	Skip bool
	// Messages, when non-nil, replaces the transcript with a consumer-supplied
	// compaction and suppresses the built-in one. The loop persists the same
	// compaction bracket either way, but no summarization call is billed.
	Messages []Message
}

type CompactRequest struct {
	Turn int
	// Messages is the candidate history the active strategy would compact. For
	// the default strategy it already contains deterministic pruning; Skip still
	// leaves the original live transcript untouched.
	Messages []Message
	// Budget is the run's effective MaxContextTokens ceiling.
	Budget int
	// Settings are the effective compaction settings for this run (already
	// clamped to the budget).
	Settings CompactionSettings
}

type CompactionPlugin struct {
	Settings *CompactionSettings
	Provider LLMProvider
	Model    string
	Strategy Compactor
}

type CompactionRequest struct {
	// Messages is the live transcript, leading system prompt included.
	Messages []Message
	// Budget is the run's context ceiling in estimated tokens
	// (Limits.MaxContextTokens), already defaulted.
	Budget int
	// Turn is the turn about to be taken, for correlating with the durable log.
	Turn int
	// Settings is the retention policy, already clamped against Budget.
	Settings CompactionSettings
	// Provider and Model are the tier the summarization call should use: the
	// dedicated compaction rung when the composition pinned one, otherwise the
	// rung the run has escalated to. A compactor that makes no model call
	// ignores both.
	Provider LLMProvider
	Model    string
}

type CompactionResult struct {
	// Messages is the replacement transcript.
	Messages []Message
	// Usage is what the compaction itself spent — real billable spend on a
	// summarizing backend, zero on a deterministic one. The loop folds it into
	// the run's accounting and stamps it on the durable completion entry, so
	// the audit trail shows what staying inside the window cost.
	Usage Usage
}

type CompactionSettings struct {
	KeepRecentTokens int
	MaxSummaryTokens int
	// PruneProtectedTools exempts tool results from generic age-based pruning.
	// Superseded identical results and stale file reads may still be pruned: a
	// newer result already carries the truth. Nil selects the safe built-ins;
	// an explicitly empty slice disables built-in protection. Add tools whose
	// outputs are non-repeatable artifacts or durable instructions.
	PruneProtectedTools []string
	// PruneCacheWarmSuffixTokens protects deep results while prompt caching is
	// active. A candidate is rewritten only when the estimated message suffix
	// after it is no larger than this value. Zero selects the default; a negative
	// value disables the guard.
	PruneCacheWarmSuffixTokens int
	// PruneMinimumSavingsTokens is the minimum aggregate saving required for
	// generic age-only pruning. Superseded and stale results bypass this floor.
	// <=0 selects the default; the effective value is capped to 10% of Budget.
	PruneMinimumSavingsTokens int
}

type Compactor interface {
	// Name identifies the compactor in diagnostics.
	Name() string
	// ShouldCompact reports whether the transcript has grown past the point
	// where this strategy wants to act. The loop asks once per turn; a
	// compactor that measures pressure differently (message count, a real
	// tokenizer, a provider-reported context length) answers here.
	ShouldCompact(messages []Message, budget int) bool
	// Compact returns the shrunk transcript. It must preserve provider
	// validity — every tool result stays adjacent to the assistant turn that
	// called it — because the loop hands the result straight to the next
	// request. Returning the input unchanged is a legal no-op.
	//
	// An error degrades to "no compaction this turn" rather than failing the
	// run: a transcript that could not be shrunk is still a transcript the
	// model can work with, while a killed run loses everything.
	Compact(ctx context.Context, req CompactionRequest) (CompactionResult, error)
}

type Config struct {
	// NativeProvider executes through engine with AI-owned fallback.
	NativeProvider    *ai.FallbackProvider
	Provider          LLMProvider
	Model             string
	ModelCapabilities ModelCapabilities
	// ContextWindow is the primary model's input window in tokens — the same
	// fact ModelRung.ContextWindow carries for the escalation rungs. 0 means
	// unknown.
	ContextWindow int
	Tools         *ToolSet
	Policy        Policy
	Hooks         Hooks
	Memory        MemoryStore
	Definition    AgentDefinition
	Limits        *Limits
	Env           *Env
	// Compaction overrides the default compaction settings (recent-token budget
	// kept verbatim). nil uses DefaultCompactionSettings().
	Compaction *CompactionSettings
	// CompactionProvider + CompactionModel, when both set, pin the in-loop
	// compaction summary call to a dedicated tier instead of borrowing the run's
	// active escalation rung. Leaving either unset keeps today's behavior (the
	// active rung summarizes). The consumer's tier system maps a "compaction"
	// task kind onto these.
	CompactionProvider LLMProvider
	CompactionModel    string
	// Compactor replaces the transcript-shrinking strategy. nil keeps
	// DefaultCompactor (summarize the older span with a model call).
	Compactor Compactor
	// RefreshKey is an optional per-turn API-key resolver. It is invoked before
	// each turn with the provider name; a non-empty result is pushed into the
	// provider via KeyUpdater. Use it for short-lived / rotating BYO credentials.
	RefreshKey func(ctx context.Context, provider string) (string, error)
	// Escalation is an optional ordered fallback ladder. When the primary
	// Provider/Model errors on a turn, the loop retries that turn down the ladder
	// before giving up, then sticks with the working rung for later turns.
	Escalation []ModelRung
	// GetSteeringMessages is an optional callback drained at the top of each turn;
	// returned messages are injected before the model reasons (mid-run steering).
	// The consumer owns the source (channel, DB, SSE input) — and its durability:
	// messages it has not yet returned are lost on a crash. Agent.Steer is the
	// durable alternative: it writes the queue into the session log itself.
	GetSteeringMessages func(ctx context.Context) []Message
	// GetFollowUpMessages is an optional callback drained when the agent would
	// stop; returned messages restart the loop instead of ending the run.
	// Agent.FollowUp is the durable equivalent.
	GetFollowUpMessages func(ctx context.Context) []Message
	// Goal, when non-empty, declares the condition under which this run may
	// stop (Claude Code /goal analog; see session.go). The completion contract is
	// appended to the system prompt, and a normal finish whose answer lacks a
	// STATUS: DONE or STATUS: BLOCKED sentinel is re-opened with a keep-going
	// nudge. Uncapped, but still bounded by MaxTurns / MaxToolCalls / the
	// budget gate, and a repeated identical answer breaks the loop with
	// StopReason "goal_stalled". The goal is recorded in the durable log
	// (EntryGoal), so a resumed run stays gated even when the resuming caller
	// cannot re-supply it. Empty — the default — disables the gate.
	Goal string
	// PrepareNextTurn is an optional save-point hook called after each turn; the
	// returned TurnState (model / tools / system) drives the next turn. nil keeps
	// the model, tools, and prompt fixed for the whole run. Model and tool-set
	// changes are durable (EntryModelChange / EntryActiveToolsChange), so a
	// crash-resumed run rebuilds them; a system change is not — the prompt is
	// re-derived on every run.
	PrepareNextTurn func(ctx context.Context, state TurnState) TurnState
	// BudgetGate is an optional per-turn ceiling check (#4). Consulted with the
	// run's accumulated usage at the top of each turn; returning true triggers a
	// one-turn graceful stop that summarizes and halts. nil leaves the run
	// uncapped (bounded only by MaxTurns / MaxToolCalls).
	BudgetGate func(ctx context.Context, u Usage) bool
	// Session + SessionID enable durable, resumable runs (P9): when both are set
	// the loop appends typed entries to the append-only SessionStore. Leaving
	// either unset keeps the run in-memory only.
	Session   SessionStore
	SessionID string
	// ProviderSession and ProviderSessionID are independent of durable run
	// logging. They retain provider transport/compatibility state for a logical
	// conversation even when each user turn gets a fresh Agent and run id.
	ProviderSession   *ProviderSession
	ProviderSessionID string
	// ResumeSession, when true (with Session + SessionID set), continues the
	// existing durable log at SessionID instead of starting a fresh run: the
	// loop rebuilds history from the log (the seed messages are used only if
	// the log turns out empty), re-issues dangling retry-safe tool calls with
	// their ORIGINAL call IDs — reproducing their idempotency keys and child
	// session IDs, so a replayed spawn_subagent reattaches instead of
	// re-running — and closes the remaining dangling calls with interrupted
	// notes. A log that already reached its leaf returns its recorded final
	// answer without any provider call.
	ResumeSession bool
	// StepGate is an optional pause-before-each-turn hook. When set, the loop calls
	// it at the top of every turn and blocks until it returns; a non-nil error
	// halts the run. The Lab's explain mode uses it to step a live run; leaving it
	// nil keeps runs continuous (the production default).
	StepGate func(ctx context.Context, turn int) error
	// Retry overrides the same-model backoff policy applied before escalation. nil
	// uses DefaultRetryPolicy(); a partial override fills its zero fields from it.
	Retry *RetryPolicy
	// PromptCacheKey, when set, opts every provider call into prompt caching under
	// this key (typically the session id). PromptCacheRetention hints the window
	// ("" | "short" | "long" | "24h"). Empty key leaves caching off — the default.
	PromptCacheKey       string
	PromptCacheRetention string
	// SeedDisabledTools pre-disables the named tools for this run's circuit
	// breaker. A resume passes the tools that were disabled in the crashed run
	// (recovered from its durable log) so a persistently broken tool is not
	// retried from scratch after resume. Empty starts every tool enabled.
	SeedDisabledTools []string
	// MaxTokens caps the model's output tokens per turn. 0 lets the provider use
	// its own default. Set this for agents that emit large artifacts so the
	// gateway's default cap doesn't truncate output with stop_reason:"length".
	MaxTokens int
	// ReasoningEffort, when set ("low" | "medium" | "high"), asks reasoning
	// models to spend that much thinking effort per turn (OpenAI-wire
	// reasoning_effort). Providers without the knob ignore it; empty sends
	// nothing.
	ReasoningEffort string
	// OutputSchema, when non-nil, constrains every text answer this agent
	// produces to the given JSON Schema (grammar-constrained decoding at the
	// provider: OpenAI response_format json_schema strict, Anthropic
	// structured-outputs output_format). Meant for verdict-shaped agents —
	// moderation / classification presets that must return machine-parseable
	// verdict×confidence JSON — not general chat: any plain-text turn must fit
	// the schema. Providers without the capability ignore it, so callers still
	// validate the answer. nil — the default — leaves output free-form.
	OutputSchema *OutputSchema
	// ToolChoice optionally constrains model tool use on every ordinary turn.
	// The zero value keeps provider defaults. Required/named choices are removed
	// automatically from the loop's borrowed tool-free finalization turn.
	ToolChoice ToolChoice
	// ParallelToolCalls asks capable providers whether they may emit several
	// tool calls in one assistant turn. nil omits the hint for compatibility.
	// AgentCore still executes only tools that independently opt into ParallelTool.
	ParallelToolCalls *bool
	// Extensions are the run capabilities this agent is built with — spill,
	// background jobs, session retrieval, delegation, the repeated-call
	// reminder, verify-on-stop, log-invariant observation, and whatever a
	// consumer writes next. Each is a value from a package under
	// agentcore/plugins/, and the loop reaches them ONLY through the interfaces
	// in extension.go: it never names one, so the set here is the complete
	// answer to "what can this agent do beyond the core loop?".
	//
	// Empty — the default — is a working agent. It reasons, calls tools, obeys
	// its policy, compacts, and logs; it just has no capability that a plugin
	// would have added.
	Extensions []ExtensionFactory
}

type ContentPart = protocol.ContentPart

type ContextContributor interface {
	RunContext(ctx context.Context) context.Context
}

type ContextHook func(ctx context.Context, msgs []Message) []Message

type ContextPruneRequest struct {
	Messages          []Message
	Budget            int
	Settings          CompactionSettings
	PromptCacheActive bool
}

type ContextPruner interface {
	// PruneContext returns a provider-valid replacement and whether it differs
	// from messages. Implementations must not mutate messages. Returning the
	// original slice with false is the no-op path.
	PruneContext(req ContextPruneRequest) ([]Message, bool)
}

type CredentialResolver interface {
	Resolve(ctx context.Context, args string) (string, error)
}

type Decision struct {
	Allow  bool
	Reason string
}

type DefinitionPlugin struct {
	Definition AgentDefinition
	Limits     *Limits
	Env        *Env
}

type DenyAll struct{}

type Diagnostic struct {
	Severity Severity `json:"severity"`
	Part     string   `json:"part"`
	Message  string   `json:"message"`
}

type Embedder = protocol.Embedder

type Env struct {
	// Sandbox is the optional isolation substrate for tools that execute
	// untrusted code (shell, file, browser). nil when no such tools are wired —
	// the analytics tools never touch it. The concrete backend lives outside
	// this leaf package and is injected by the host. This field records the
	// backend for diagnostics; the host must also bind it to each tool that uses
	// it. Setting this field alone does not sandbox a tool.
	Sandbox Sandbox
	// Credentials is the optional secret resolver. When set, tool arguments are
	// passed through it at the trust boundary — after the call has been traced
	// and gated, immediately before the tool executes — so opaque {{cred:NAME}}
	// placeholders the model emits become real secret values the tool can use
	// (an API key, a scoped DB DSN) without the model, the persisted trace, or
	// the before-hooks ever seeing the literal. nil = no resolution; arguments
	// reach the tool unchanged.
	Credentials CredentialResolver
}

type Extension interface {
	// Name identifies this extension instance.
	Name() string
}

type ExtensionFactory interface {
	// Name identifies the extension in diagnostics and in Agent.Describe.
	Name() string
	// BeginRun builds the per-run instance. An error aborts the run before any
	// provider call, so a misconfigured extension fails loudly rather than
	// silently doing nothing.
	BeginRun(ctx context.Context, info RunInfo) (Extension, error)
}

type FauxProvider struct {
	Responses []ChatResponse

	Recorded []ChatRequest
	// contains filtered or unexported fields
}

type GoalReviser interface {
	// Native Pi integrations must call RecordGoalRevision in a governed tool
	// context before publishing the condition. The drain then refreshes the
	// prompt; durability already belongs to that tool's physical effect.
	// ReviseGoal returns the run's new completion condition and true when one
	// has been set since the last call. It is drained, not polled: returning
	// (x, true) twice for the same revision would write the same EntryGoal every
	// turn for the rest of the run.
	ReviseGoal() (goal string, ok bool)
}

type GoalRevision struct {
	Previous string `json:"previous"`
	Goal     string `json:"goal"`
	Reason   string `json:"reason"`
}

type HookErrorPolicy string

type Hooks struct {
	Before []BeforeToolCall
	After  []AfterToolCall

	// BeforeAgentStart runs in order once per run, on the assembled system
	// prompt + seed messages, each seeing the previous one's output.
	BeforeAgentStart []BeforeAgentStartHook
	// TurnStart observers run in order at the top of every turn, before any of
	// the turn's work (compaction, steering, the provider call).
	TurnStart []TurnHook
	// TurnEnd observers run in order once a turn is complete, on every path out
	// of that turn (final answer, tool round, guard stop, abort).
	TurnEnd []TurnHook
	// BeforeCompact runs in order when the active strategy proposes pruning or
	// compaction; the first decisive answer (Skip, or replacement Messages) wins.
	BeforeCompact []BeforeCompactHook
	// AgentEnd observers run in order as the run returns, on every exit path.
	AgentEnd []AgentEndHook

	// Context runs in order before every provider request, each transforming the
	// message view the next one sees (a reducer over the message list).
	Context []ContextHook
	// PiContext is the native counterpart of Context, used by the Pi host.
	PiContext []PiContextHook
	// BeforeProviderRequest runs in order on the assembled request, each seeing
	// the previous one's output.
	BeforeProviderRequest []ProviderRequestHook
	// MessageEnd observers run in order after each assistant message completes.
	MessageEnd []MessageEndHook

	// ErrorPolicy governs handler panics/errors. Zero value == HookContinue.
	ErrorPolicy HookErrorPolicy
	// OnError, when set, receives every attributed hook failure (source + error)
	// regardless of policy, so a consumer can log/meter it. Source is a stable
	// identifier like "context[1]" or "before_tool_call[0]".
	OnError func(source string, err error)
}

type HooksPlugin struct {
	Label    string
	Hooks    Hooks
	Priority Priority
}

type InboxItem struct {
	ID      string
	Lane    string
	Message Message
}

type KeyUpdater = protocol.KeyUpdater

type LLMProvider = protocol.LLMProvider

type LabSkillRef struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

type LabStep struct {
	NativeTrace json.RawMessage `json:"native_trace,omitempty"`
	SessionKey  string          `json:"session_key,omitempty"`
	Depth       int             `json:"depth,omitempty"`
	Index       int             `json:"index"` // 0-based position in the step list
	Turn        int             `json:"turn"`  // 1-based agent turn this step belongs to
	Kind        LabStepKind     `json:"kind"`

	// Assembled context + prompt as it entered this step.
	System  string    `json:"system"`  // the full assembled system prompt
	Persona string    `json:"persona"` // the Identity (SOUL) section of the prompt
	Memory  []string  `json:"memory"`  // recalled-memory bullet lines
	Context []Message `json:"context"` // the messages sent to the model this turn

	// Skills: advertised (headers in the prompt) vs loaded (read_skill calls seen
	// up to and including this step).
	SkillsAdvertised []LabSkillRef `json:"skills_advertised"`
	SkillsLoaded     []string      `json:"skills_loaded"`

	// Tools available this turn (advertised schemas, by name) and the tool calls
	// the model made this turn paired with their results.
	Tools     []string      `json:"tools"`
	ToolCalls []LabToolCall `json:"tool_calls"`

	Response   string `json:"response"`
	StopReason string `json:"stop_reason,omitempty"`
	Error      string `json:"error,omitempty"`

	// Compaction (Kind == LabStepCompaction): the summary kept in place of the
	// dropped span. Context holds the retained tail.
	Summary string `json:"summary,omitempty"`

	// Per-step and cumulative accounting (real provider numbers).
	TokensIn     int     `json:"tokens_in"`
	TokensOut    int     `json:"tokens_out"`
	CostUSD      float64 `json:"cost_usd"`
	CumTokensIn  int     `json:"cum_tokens_in"`
	CumTokensOut int     `json:"cum_tokens_out"`
	CumCostUSD   float64 `json:"cum_cost_usd"`
}

type LabStepKind string

type LabToolCall struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Args    string `json:"args"`   // {{cred:NAME}} placeholder form — never a literal
	Result  string `json:"result"` // the tool-result message content, if recorded
	Allowed bool   `json:"allowed"`
	Error   string `json:"error,omitempty"`
}

type Limits struct {
	MaxTurns         int // hard cap on LLM calls
	MaxToolCalls     int // hard cap on tool executions across the run
	MaxToolResultLen int // byte cap per tool result before it reaches the LLM
	MaxContextTokens int // soft budget; old turns are compacted above it (§5.2)
}

type MemoryCurator interface {
	// Supersede retracts the entry id within scopeID, optionally naming the
	// entry that replaces it ("" retracts without a successor). It must
	// report not-found when no live entry with that id exists in the scope —
	// a silent no-op would tell the model a memory is gone when it is not.
	Supersede(ctx context.Context, scopeID, id, replacementID string) error
	// Update replaces the content of the entry id within scopeID: the new
	// entry is written and the old one retracted to it, atomically, so a
	// failure never leaves a retracted memory with no successor.
	Update(ctx context.Context, scopeID, id string, entry MemoryEntry) error
}

type MemoryEntry struct {
	ID         string     `json:"id"`
	ScopeID    string     `json:"scope_id"`
	Kind       MemoryKind `json:"kind"`
	Content    string     `json:"content"`
	Tags       []string   `json:"tags"`
	Confidence float64    `json:"confidence"`
	SourceRun  string     `json:"source_run_id"`
	CreatedAt  time.Time  `json:"created_at"`
}

type MemoryKind string

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

type MemoryStore interface {
	// Recall returns long-term entries relevant to the query for a scope.
	Recall(ctx context.Context, scopeID, query string, limit int) ([]MemoryEntry, error)
	// Remember persists a long-term entry (PII already redacted by the caller).
	Remember(ctx context.Context, entry MemoryEntry) error
}

type Message = protocol.Message

type MessageEndHook func(ctx context.Context, msg Message)

type ModelCapabilities = protocol.ModelCapabilities

type ModelCapabilityError struct {
	Provider string
	Model    string
	Feature  string
}

type ModelCapabilityProvider = protocol.ModelCapabilityProvider

type ModelPlugin struct {
	NativeProvider    *ai.FallbackProvider
	Provider          LLMProvider
	Model             string
	Capabilities      ModelCapabilities
	ContextWindow     int
	Escalation        []ModelRung
	Retry             *RetryPolicy
	RefreshKey        func(ctx context.Context, provider string) (string, error)
	MaxTokens         int
	ReasoningEffort   string
	OutputSchema      *OutputSchema
	ToolChoice        ToolChoice
	ParallelToolCalls *bool
	PromptCacheKey    string
	CacheRetention    string
}

type ModelRung struct {
	Provider LLMProvider
	Model    string
	// Capabilities is an optional discovery/config snapshot for this exact
	// provider/model rung. It overlays the provider adapter's defaults.
	Capabilities ModelCapabilities
	// ContextWindow is this model's input window in tokens, which caps the
	// compaction budget while this rung is answering. 0 means unknown and the
	// configured MaxContextTokens stands alone.
	//
	// It lives on the rung rather than in Limits because a ladder is routinely
	// built from models with different windows, and the loop switches between
	// them mid-run. A single run-wide number is therefore wrong for every rung
	// but one — too high and the loop never compacts before the provider
	// rejects the request, which no retry or escalation can rescue.
	//
	// agentcore does not know any model's window and must not learn: the value
	// is supplied by whoever built the rung.
	ContextWindow int
}

type NativeContextContributor interface {
	Extension
	TransformNativeContext(context.Context, []json.RawMessage) ([]json.RawMessage, error)
}

type NativeRun struct {
	// Commands are explicit host controls, keyed by installed extension name.
	Commands map[string]json.RawMessage
	// ControlOnly applies commands and checkpoints without making a model request.
	ControlOnly bool
	State       json.RawMessage
	Input       []Message
	Task        string
	Sink        StreamSink
	// Lifecycle receives bounded setup steps that happen before the provider
	// loop starts, such as recalling relevant memory.
	Lifecycle  func(string)
	Compaction *nativehost.CompactionPolicy
	Telemetry  telemetry.Context
}

type NativeStateContributor interface {
	NativeState() (json.RawMessage, error)
	RestoreNativeState(json.RawMessage) error
}

type ObservePhase string

type OutputSchema = protocol.OutputSchema

type ParallelTool interface {
	Parallel() bool
}

type PiArgumentPreparer interface {
	PiArgumentPreparation() string
}

type PiCompletedTurn struct {
	Info              StopInfo
	Usage             Usage
	Model, StopReason string
	Calls             []ToolCall
	Outcomes          []PiToolOutcome
}

type PiContextHook func(context.Context, []json.RawMessage) ([]json.RawMessage, error)

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

type PiToolOutcome struct {
	Trace              ToolTrace           `json:"trace"`
	Invocations        []ToolInvocation    `json:"invocations,omitempty"`
	AdditionalContexts []Message           `json:"additionalContexts,omitempty"`
	Parked             bool                `json:"parked,omitempty"`
	QuestionID         string              `json:"questionId,omitempty"`
	ChildQuestion      *ChildQuestionError `json:"childQuestion,omitempty"`
	Executed           bool                `json:"executed"`
	Terminate          bool                `json:"terminate,omitempty"`
}

type PiTurnDecision struct {
	StopDecision
	End    bool
	Parked bool
}

type PiTurnPreparation struct {
	Messages     []Message
	DisableTools bool
	StopReason   string
	Note         string
}

type Plugin interface {
	// Name identifies the plugin. Two plugins with the same name in one
	// composition is a configuration error, not a silent overwrite.
	Name() string
	// Register contributes services and extension points. Returning an error
	// aborts the whole composition — a plugin that cannot install its capability
	// must not leave a half-built agent behind.
	Register(r *Registry) error
}

type Policy interface {
	// Allow is consulted in the beforeToolCall preflight, after arguments are
	// schema-validated and before execution.
	Allow(ctx context.Context, call ToolCall) Decision
	// PermittedTools filters the advertised tool names down to those the policy
	// currently allows, so the model never sees a tool it cannot use.
	PermittedTools(ctx context.Context, all []string) []string
}

type PolicyPlugin struct {
	Policy Policy
}

type Priority int

type ProcessSandbox interface {
	Sandbox
	// Start must enforce SandboxExec.Constraints.TimeoutSeconds for the whole
	// process lifetime and hard-kill the process group/container when it expires.
	// Retained protocol tools rely on that backend-independent lifetime bound.
	Start(ctx context.Context, req SandboxExec) (SandboxProcess, error)
}

type PromptContributor interface {
	// SystemPrompt returns text to append, or "" to contribute nothing.
	SystemPrompt() string
}

type ProviderError = protocol.ProviderError

type ProviderRequestHook func(ctx context.Context, req ChatRequest) ChatRequest

type ProviderSession = protocol.ProviderSession

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

type ProviderSessionState = protocol.ProviderSessionState

type ReasoningBlock = protocol.ReasoningBlock

type RecoveryPolicy string

type ReducedState struct {
	Messages          []Message
	Model             string
	ActiveTools       []string
	DisabledTools     []string // tools the circuit breaker disabled (EntryToolDisabled)
	Completed         bool     // an EntryLeaf was seen
	PendingCompaction bool     // a compaction start with no completion
	Goal              string   // goal-gate condition of the unfinished tail run (EntryGoal)
	LastTurn          int
	// Inbox holds queued steering/follow-up messages never delivered before the
	// crash (EntryInbox with no matching EntryInboxDone). Side records are read
	// from the raw log — they are not tree nodes — so a pending inbox survives
	// even when it was appended mid-turn between two buffered entries.
	Inbox []InboxItem
	// Draft is the partial assistant text the in-flight turn had produced when
	// the run died (the newest trailing EntryAssistantFrame), "" when the last
	// turn settled or produced no text.
	Draft string
	// ToolProgress maps a tool-call ID to the newest partial output it reported
	// before the crash (trailing EntryToolProgress records), for calls whose
	// result never landed.
	ToolProgress map[string]string
	// ToolOutcomes holds completed physical executions whose canonical result
	// message may not have reached the transcript before a crash. Recovery
	// chooses them by the assistant's original call order.
	ToolOutcomes map[string]ToolOutcomeRecord
}

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

type ReplayProvider struct {
	Records []TurnRecord
	// contains filtered or unexported fields
}

type ResultCard struct {
	Title  string      `json:"title"`
	Kind   string      `json:"kind"`           // "stat" | "series"
	Unit   string      `json:"unit,omitempty"` // optional label for the values
	Stats  []CardStat  `json:"stats,omitempty"`
	Points []CardPoint `json:"points,omitempty"`
}

type ResumePlan struct {
	Messages        []Message
	Model           string
	ActiveTools     []string
	DisabledTools   []string   // tools the circuit breaker disabled; re-applied on resume
	Completed       bool       // run already reached a leaf; nothing to resume
	Goal            string     // goal-gate condition of the interrupted run, re-armed on resume
	Interrupted     bool       // the last turn did not complete
	RerunCompaction bool       // an unfinished compaction must be re-run first
	RetryCalls      []ToolCall // dangling calls whose tools are retry-safe
	DroppedCalls    []ToolCall // dangling calls left for the model (not retry-safe)
	// Answers is the out-of-band tool results recorded while the run was parked:
	// call id -> the human's answer, from EntryAnswer entries. A dangling call
	// with an entry here is closed with the answer as its result — it is neither
	// retried nor interrupted.
	Answers map[string]string
	// Inbox holds steering/follow-up messages queued but never delivered before
	// the crash (pi's durable inbox). The resumed run drains them at their
	// lane's point and settles each with EntryInboxDone.
	Inbox []InboxItem
	// Draft is the partial assistant text the in-flight turn had produced;
	// surfaced to the resumed run as context, not replayed as a message.
	Draft string
	// ToolProgress maps a dangling call's ID to the last partial output it
	// reported, so its interrupted note can say how far it got.
	ToolProgress map[string]string
	// ToolOutcomes are completed calls recovered from side records. They are
	// neither retried nor marked interrupted; the resume path materializes their
	// messages beside unresolved siblings in original source order.
	ToolOutcomes map[string]ToolOutcomeRecord
}

type RetryPolicy = protocol.RetryPolicy

type RetrySafeTool interface {
	RetrySafe() bool
}

type RichTool interface {
	RunRich(ctx context.Context, args string) (ToolOutput, error)
}

type Role = protocol.Role

type RunChapter struct {
	// Index is the chapter's 0-based position.
	Index int `json:"index"`
	// FirstStep and LastStep are inclusive indices into the step list, so a
	// client turns a chapter into a page request without a second lookup.
	FirstStep int `json:"first_step"`
	LastStep  int `json:"last_step"`
	// FirstTurn and LastTurn are the run turns the chapter spans.
	FirstTurn int `json:"first_turn"`
	LastTurn  int `json:"last_turn"`
	// Title is a one-line label drawn from the closing summary — the model's own
	// words, not a generated paraphrase.
	Title string `json:"title"`
	// Summary is the compaction summary that CLOSED this chapter: what the agent
	// had accomplished by the end of the span. The final chapter has none (the
	// run ended before the next compaction), which is the honest answer — its
	// outcome is the run's final answer, not a summary.
	Summary string `json:"summary,omitempty"`
	// Steps is how many steps the chapter contains, and ToolCalls how many tool
	// calls were made in it — the two numbers that say whether a chapter is
	// worth opening.
	Steps     int `json:"steps"`
	ToolCalls int `json:"tool_calls"`
	// TokensIn/TokensOut/CostUSD are the chapter's own spend, differenced from
	// the cumulative totals the fold already computed.
	TokensIn  int     `json:"tokens_in"`
	TokensOut int     `json:"tokens_out"`
	CostUSD   float64 `json:"cost_usd"`
}

type RunCloser interface {
	CloseRun()
}

type RunCommandHandler interface {
	HandleRunCommand(context.Context, json.RawMessage) (json.RawMessage, error)
}

type RunController interface {
	ControlRun(context.Context, StepInfo) (reason string, err error)
}

type RunFinalizer interface {
	FinalizeRun(context.Context, RunResult, error) error
}

type RunInfo struct {
	// SessionID is the durable session, or "" on an in-memory run.
	SessionID string
	// Owner is a stable token identifying THIS run, used to fence run-scoped
	// resources (a background job started here must not be visible to another
	// run). It equals SessionID on a durable run and is otherwise unique.
	Owner string
	// ScopeID is the running agent's own memory/persona scope — the same value
	// recall reads under (def.ScopeID). Extensions that write agent-private
	// state pin to it so a model-supplied value can never widen the scope.
	ScopeID string
	// Limits are the run's effective bounds.
	Limits Limits
	// Depth is the delegation depth: 0 for a top-level run, higher inside a
	// spawned sub-agent.
	Depth int
	// Durable reports whether a session store is recording this run.
	Durable bool
	// Session is the store recording this run, or nil. It is handed over so a
	// retrieval extension can read the run's OWN log without the consumer
	// wiring the same store twice and risking the two disagreeing about which
	// session is being searched. Read-only by convention: the loop owns every
	// write, which is what keeps "model-visible means logged" enforceable.
	Session SessionStore
	// Goal is the run's completion condition when one is set — the configured
	// goal, or the one recovered from the durable log on a resume. Empty means
	// the run is ungated. It is carried here so a gate extension never has to
	// read the log itself; only the loop writes and recovers the record.
	Goal string
	// Bookkeeping reports whether a tool's calls are administrative rather than
	// progress toward the task (see BookkeepingTool). Never nil.
	//
	// It exists so an extension can treat such calls differently — a loop
	// detector must not count a plan updater's repeats as a stuck chain —
	// WITHOUT depending on the package that provides the tool. Asking the
	// question generically is what keeps capabilities from importing each
	// other.
	Bookkeeping func(tool string) bool
	// Agent is the running agent, non-nil. It is here for the one capability
	// that cannot be built without it — delegation, which needs Fork to produce
	// a child whose scope provably only narrows. Most extensions ignore it.
	Agent *Agent
}

type RunObserver interface {
	// ObserveMessages is called with the live history immediately before each
	// provider request, and again after any rewrite (compaction, context edit)
	// so an observer tracking history can rebase.
	ObserveMessages(ctx context.Context, phase ObservePhase, turn int, msgs []Message)
}

type RunResult struct {
	Final      string      `json:"final"`
	Messages   []Message   `json:"messages"`
	Tools      []ToolTrace `json:"tool_calls"`
	Usage      Usage       `json:"usage"`
	Turns      int         `json:"turns"`
	StopReason string      `json:"stop_reason"`
	// CommandResults contains structured receipts from explicit host controls.
	CommandResults map[string]json.RawMessage `json:"command_results,omitempty"`
	// NativeState and NativeTelemetry retain the original Pi artifacts. When
	// present, Messages is only a display projection and must not seed a run.
	NativeState     json.RawMessage `json:"native_state,omitempty"`
	NativeTelemetry json.RawMessage `json:"native_telemetry,omitempty"`
	NativeRevision  string          `json:"native_revision,omitempty"`
	// UnpersistedEntries counts durable session entries the run buffered but
	// could not commit because the session store kept failing through the final
	// flush. Zero on a healthy (or storeless) run. Non-zero means the durable
	// log holds a valid prefix of the run — recovery stays safe (the
	// conservative resume never re-runs non-idempotent work) but the tail of
	// this run cannot be reconstructed (pi's Faulted state, degraded to a
	// flagged result instead of a halt).
	UnpersistedEntries int `json:"unpersisted_entries,omitempty"`
	// Parked is true when the run ended inside a tool call that is waiting on a
	// human (the ask tool): the call stays dangling in the durable log behind an
	// EntryQuestion, and the run resumes when an EntryAnswer lands. Distinct
	// from every other stop — the run is neither done nor failed, it is paused.
	Parked bool `json:"parked,omitempty"`
	// Question carries the parked call's validated arguments when Parked is
	// true, so a consumer can render the prompt/options directly from RunResult.
	Question json.RawMessage `json:"question,omitempty"`
}

type RunStart struct {
	// System is the assembled system prompt. It has not yet been prepended to
	// Messages — the loop does that after the hooks run.
	System string
	// Messages are the seed messages (the user prompt, or a continued thread).
	// They never include the system message.
	Messages []Message
	// Task is the recall/skill-selection task string for this run. Read-only:
	// changing it here has no effect (memory recall already happened).
	Task string
}

type Sandbox interface {
	// Exec runs one command to completion inside an ephemeral sandbox and
	// returns its captured output. It MUST NOT inherit the host process
	// environment; only req.Env is exposed inside. A non-zero exit code is a
	// SandboxResult, not an error — error is reserved for the sandbox itself
	// failing to run (backend unavailable, image missing).
	Exec(ctx context.Context, req SandboxExec) (SandboxResult, error)
}

type SandboxExec struct {
	// Argv is the command and its arguments; Argv[0] is resolved against the
	// sandbox image's PATH, not the host's.
	Argv []string
	// Stdin is fed to the command's standard input.
	Stdin string
	// Env is the ONLY environment visible inside the sandbox. The host process
	// environment is never inherited — this is the property that stops a
	// prompt-injected command from reading DB creds or API keys.
	Env map[string]string
	// Mounts are explicit host paths exposed to the sandbox. Backends must reject
	// mounts they cannot enforce; callers provide only paths already narrowed by a
	// workspace guard.
	Mounts []SandboxMount
	// Workdir overrides the working directory the command starts in. Empty keeps
	// the backend default (the ephemeral scratch workdir). Set it to a mount
	// target so the command runs against shared workspace files.
	Workdir string
	// Session, when non-empty, requests persistent execution: a SessionSandbox
	// reuses one long-lived container keyed by this id across calls, so installed
	// packages and written files survive between tool invocations. Empty (the
	// default) runs the command in a fresh, throwaway container — the fail-safe
	// path every backend supports. The container's network/mount/limit envelope
	// is fixed by the first call that opens the session.
	Session string
	// Image, when non-empty, requests a specific sandbox image for this exec,
	// overriding the backend's default image selection. It lets distinct tools run
	// in purpose-built images within one host (e.g. computer_use in a doc-toolchain
	// image, browser_use in a Chrome image) without sharing a container. A backend
	// that cannot honor it MUST ignore it and fall back to its default — the
	// fail-safe path; agentcore stays generic and never interprets the value.
	Image string
	// Constraints are the resource + isolation caps for this execution.
	Constraints SandboxLimits
}

type SandboxLimits struct {
	Network      bool     // false (default) = no network egress at all
	NetworkAllow []string // when Network is true and non-empty, egress is confined to these hosts (+subdomains) via the sandbox filtering proxy; empty = open network
	WritableFS   bool     // false (default) = read-only root + small writable workdir
	// RunAsHostUser requests the host process UID/GID inside a container while
	// preserving a read-only root. It is for writable bind-mounted workspaces:
	// nobody often cannot modify a 0755 host directory, while container-root
	// would leave root-owned files behind. Backends that cannot map numeric host
	// identities may ignore it and retain their unprivileged default.
	RunAsHostUser  bool
	MemoryMB       int     // 0 = backend default
	CPUs           float64 // 0 = backend default
	PidsLimit      int     // 0 = backend default
	TimeoutSeconds float64 // 0 = backend default; negative disables the HostSandbox deadline; positive hard-kills after this elapses
}

type SandboxMount struct {
	Source   string
	Target   string
	ReadOnly bool
}

type SandboxProcess interface {
	Stdin() io.WriteCloser
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
	Wait() (SandboxResult, error)
	Kill() error
}

type SandboxResult struct {
	ExitCode   int
	Stdout     string
	Stderr     string
	Killed     bool   // true if the timeout fired and the command was killed
	KillReason string // human-readable kill cause, set when Killed
}

type SelfGated interface {
	// SelfGated reports that this tool bypasses the permission gate.
	SelfGated() bool
}

type Session struct {
	ID        string    `json:"id"`
	ScopeID   string    `json:"scope_id"`
	ParentID  string    `json:"parent_id,omitempty"` // set when forked
	Messages  []Message `json:"messages"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type SessionBatchStore interface {
	AppendBatch(ctx context.Context, sessionID string, entries []SessionEntry) error
}

type SessionEntry struct {
	Seq      int              `json:"seq"` // append order, assigned by the store
	Kind     SessionEntryKind `json:"kind"`
	ID       string           `json:"id,omitempty"`        // stable entry id (writer-assigned)
	ParentID string           `json:"parent_id,omitempty"` // tree parent; for outcome side records, the intent anchor
	Target   string           `json:"target,omitempty"`    // EntryLeafMove: the new active leaf
	Turn     int              `json:"turn,omitempty"`
	Message  *Message         `json:"message,omitempty"` // EntryMessage
	Model    string           `json:"model,omitempty"`   // EntryModelChange
	Tools    []string         `json:"tools,omitempty"`   // EntryActiveToolsChange
	Tool     string           `json:"tool,omitempty"`    // EntryToolDisabled
	// Lane selects which queue an EntryInbox feeds: "steer" drains at the top
	// of the next turn, "follow" drains when the run would stop.
	Lane string `json:"lane,omitempty"`
	// CallID links a side record to the tool call it concerns: an
	// EntryToolProgress reports on it, an EntryQuestion parks it, an
	// EntryAnswer resolves it (the provider's call id, stable across a resume).
	CallID string `json:"call_id,omitempty"`
	// Content carries a side record's payload: the accumulated text for an
	// EntryAssistantFrame, the accumulated partial output for an
	// EntryToolProgress. Snapshots, not deltas — the newest wins.
	Content string `json:"content,omitempty"`
	Goal    string `json:"goal,omitempty"`    // EntryGoal: the run's completion condition
	Summary string `json:"summary,omitempty"` // EntryCompaction (completion) / EntryBranchSummary
	Final   bool   `json:"final,omitempty"`   // EntryCompaction completion marker
	// Retained is the transcript a completed EntryCompaction left behind: the
	// summary (or elided fallback) plus the recent tail kept verbatim, MINUS the
	// run's own leading system prompt, which every run re-derives and prepends
	// itself. It makes the compaction a self-contained checkpoint (pi's
	// CompactionEntry.retainedTail): reduce restarts history here instead of
	// replaying the span the summary already represents.
	//
	// Without it a resumed run silently rebuilds the FULL pre-compaction
	// history — measured at 3.75x the messages and 2.8x over the context budget
	// on a 60-turn run — then pays to summarize it all again, and the fresh
	// summary is not the one the original run reasoned over. Nil on a legacy
	// entry (and on the start half of the bracket), which reduces exactly as
	// before.
	Retained []Message `json:"retained,omitempty"`
	// State is the rest of the reduced run state as of a completed
	// EntryCompaction — everything the fold accumulated that Retained does not
	// carry. Retained makes the checkpoint self-contained for the TRANSCRIPT;
	// this makes it self-contained for the run, which is what lets a resume read
	// a suffix of the log instead of all of it (see SessionWindowStore).
	//
	// Nil on a legacy entry, and on the start half of the bracket. A nil State is
	// why a windowed read is an optimization a store opts into rather than the
	// default: a log whose newest checkpoint predates this field has no suffix
	// that reduces to the same answer, so it is read whole.
	State *CheckpointState `json:"state,omitempty"`
	// Usage records what the summarization call itself cost (EntryCompaction
	// completion / EntryBranchSummary). Compaction and branch summaries are real
	// billable provider calls; without this they are invisible spend (pi #6671).
	Usage *Usage `json:"usage,omitempty"`
	// Question is the parked call's validated arguments (EntryQuestion), kept
	// verbatim so a consumer can re-render the prompt and options without
	// knowing the tool's schema.
	Question json.RawMessage `json:"question,omitempty"`
	// Answer is the human's reply to a parked question (EntryAnswer): the text
	// recovery feeds back as the call's tool result.
	Answer string `json:"answer,omitempty"`
	// Outcome is populated only for EntryToolOutcome. CallID is kept on the
	// envelope so stores and recovery can identify it without decoding a nested
	// message first.
	Outcome   *ToolOutcomeRecord `json:"outcome,omitempty"`
	CreatedAt time.Time          `json:"created_at"`
}

type SessionEntryKind string

type SessionLeaseStore interface {
	AcquireSessionLease(ctx context.Context, sessionID string) (leaseCtx context.Context, release func() error, err error)
}

type SessionNode struct {
	Entry    SessionEntry
	ID       string
	ParentID string
}

type SessionPlugin struct {
	Store             SessionStore
	ID                string
	Resume            bool
	SeedDisabledTools []string
	ProviderState     *ProviderSession
	ProviderSessionID string
}

type SessionSandbox interface {
	Sandbox
	// CloseSession reaps the persistent container for id, if any. It is
	// idempotent: closing an unknown or already-closed session is not an error.
	CloseSession(id string) error
}

type SessionStore interface {
	// Append records one entry; the store assigns its Seq. It MUST be safe for
	// concurrent use on the same sessionID: a run's loop appends serially, but
	// Steer/FollowUp enqueue and side-record writes race it from other
	// goroutines, and a sibling process resuming the same log appends too. A
	// store that assigns Seq by read-max-then-insert must resolve collisions
	// (retry on a unique violation, or serialize per session) — a lost or
	// duplicated Seq silently corrupts the fold.
	Append(ctx context.Context, sessionID string, entry SessionEntry) error
	// Log returns the full ordered entry log for a session.
	Log(ctx context.Context, sessionID string) ([]SessionEntry, error)
}

type SessionWindowStore interface {
	// LogFrom returns the session's entries with Seq >= sinceSeq, in order.
	LogFrom(ctx context.Context, sessionID string, sinceSeq int) ([]SessionEntry, error)
	// CheckpointSeq reports the Seq of the newest completed EntryCompaction that
	// carries BOTH Retained and State (0 when there is none), and whether the
	// session contains any EntryLeafMove. Zero is unambiguous as "none" whatever
	// a store's Seq origin: a compaction always follows the messages it
	// summarizes, so it is never a log's first entry.
	//
	// Both facts are needed because both can defeat a window. Without State the
	// suffix loses the model, tools, and goal the fold had accumulated; with a
	// leaf move the newest checkpoint by Seq may sit on an ABANDONED branch, and
	// resuming from it would continue work the log says was rewound away.
	//
	// A third fact defeats it the same way: an EntryInbox queued BEFORE the
	// checkpoint and still unsettled (no EntryInboxDone naming it). The fold
	// reads pending inbox items from the raw log, so a window that starts past
	// one silently drops queued human input. A store that sees such an item
	// reports seq=0 — the full read is the only correct answer.
	CheckpointSeq(ctx context.Context, sessionID string) (seq int, branched bool, err error)
}

type Severity string

type Skill struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Body        string `json:"body,omitempty"`
	Enabled     bool   `json:"enabled"`
}

type SkillLoader func(ctx context.Context, ids []string) (map[string]string, error)

type SteeringPlugin struct {
	Steer           func(ctx context.Context) []Message
	FollowUp        func(ctx context.Context) []Message
	PrepareNextTurn func(ctx context.Context, state TurnState) TurnState
}

type StepDecision struct {
	// AdditionalContexts are prepended to the step's messages and persisted.
	// Use it to tell the model something that became true between turns — a
	// background job finished, an external state changed.
	AdditionalContexts []Message
}

type StepInfo struct {
	Turn int
	// BookkeepingTurns is the number of completed administrative turns refunded
	// against MaxTurns. Turn itself remains monotonic for hooks and observers.
	BookkeepingTurns int
	// Model is the rung in use for this step.
	Model string
	// Usage is the run-to-date total.
	Usage Usage
}

type StepInterceptor interface {
	BeforeStep(ctx context.Context, info StepInfo) StepDecision
}

type StopDecision struct {
	// Continue re-opens the run instead of accepting the answer.
	Continue bool
	// Inject is the message explaining why, added to the conversation and
	// persisted. Continue with nothing to inject would spin the loop against an
	// unchanged conversation, so it is treated as accepting the finish.
	Inject []Message
	// Note is a short, user-facing progress line. The raw Inject text is
	// internal rail scaffolding and is deliberately NOT shown to the end user.
	Note string
	// StopReason overrides the recorded reason when this extension gives up
	// (a stalled goal, an exhausted guard).
	StopReason string
}

type StopInfo struct {
	// Final is the answer the model produced.
	Final string
	Turns int
	// Tools is the run's tool trace, so a guard can check what evidence exists.
	Tools []ToolTrace
	// Attempt counts how many times THIS extension has already re-opened the
	// run, so a guard can bound itself.
	Attempt int
}

type StopInterceptor interface {
	TurnStopping(ctx context.Context, info StopInfo) StopDecision
}

type StreamDecision struct {
	// Abort cuts the in-flight assistant message: the loop cancels the
	// provider stream, discards the partial text, appends Inject to the
	// conversation, and retries the turn's provider call from the same point.
	// Abort with nothing to Inject would retry against an unchanged
	// conversation — the model would emit the same tokens and abort again — so
	// it is treated as "no opinion" and the stream completes.
	Abort bool
	// Inject is the correction the retried turn must see — the rule body the
	// matched pattern violated. The LOOP appends it to the history and persists
	// it like a steer, so a resumed run replays the conversation the retry was
	// actually given.
	Inject []Message
}

type StreamEvent struct {
	Type     StreamEventType
	Token    string          // set when Type == StreamToken
	Tool     *ToolTrace      // set when Type == StreamTool
	Note     string          // set for StreamProgress and textual tool updates
	Card     *ResultCard     // set when Type == StreamCard
	Question json.RawMessage // set when Type == StreamQuestion (the parked call's args)
	Turn     int
}

type StreamEventType string

type StreamInterceptor interface {
	InterceptStreamDelta(ctx context.Context, accumulated string) StreamDecision
}

type StreamSink func(StreamEvent)

type StreamingTool interface {
	RunStreaming(ctx context.Context, args string, emit func(partial string)) (string, error)
}

type StringTool struct {
	ToolName, Description string
	Properties            map[string]any
	Required              []string
	Execute               func(context.Context, map[string]string) (string, error)
}

type Tool interface {
	// Name is the stable identifier the model calls.
	Name() string
	// Schema advertises the tool to the model (JSON Schema parameters).
	Schema() ToolSchema
	// Run executes with validated JSON arguments and returns a result string
	// (already truncated by the loop before reaching the model).
	Run(ctx context.Context, args string) (string, error)
}

type ToolCall = protocol.ToolCall

type ToolChoice = protocol.ToolChoice

type ToolChoiceMode = protocol.ToolChoiceMode

type ToolContributor interface {
	// Tools returns this extension's tools for this run. Called once, after
	// BeginRun, so the set may depend on run state (depth, durability).
	Tools() []Tool
}

type ToolDenialReason string

type ToolGate struct {
	CallID  string `json:"call_id"`
	Allowed bool   `json:"allowed"`
	Reason  string `json:"reason,omitempty"`
	Error   string `json:"error,omitempty"`
}

type ToolInterceptor interface {
	InterceptToolResult(ctx context.Context, call ToolCall, result string, runErr error) ToolResultDecision
}

type ToolInvocation struct {
	Trace    ToolTrace `json:"trace"`
	Executed bool      `json:"executed,omitempty"`
}

type ToolInvoker interface {
	InvokeTool(ctx context.Context, name, args string) (ToolOutput, error)
}

type ToolOutcomeRecord struct {
	Message     Message          `json:"message"`
	Trace       ToolTrace        `json:"trace"`
	Invocations []ToolInvocation `json:"invocations,omitempty"`
	Extra       []Message        `json:"extra,omitempty"`
	Terminate   bool             `json:"terminate,omitempty"`
	Executed    bool             `json:"executed,omitempty"`
}

type ToolOutput struct {
	Content string
	Parts   []ContentPart

	// Invocations records governed tools called from inside this tool. It is
	// audit/control metadata, never provider-visible content. Eval uses it to
	// preserve host-tool bridge traces in the outer call's durable outcome.
	Invocations []ToolInvocation
	// AdditionalContexts and Terminate propagate the same decisions a direct
	// nested call would have produced, but the loop applies them only after the
	// outer tool result so provider tool-call/result adjacency remains valid.
	AdditionalContexts []Message
	Terminate          bool
}

type ToolResultArchiver interface {
	ArchiveToolResult(context.Context, ToolCall, string) (string, error)
}

type ToolResultDecision struct {
	// Result replaces the tool's output when Replace is true. Replacing is
	// explicit rather than inferred from a non-empty string, so an interceptor
	// cannot erase a result by returning a zero value.
	// Replacing also tells the loop the result is already bounded, so its own
	// default truncation is skipped — that is what lets a lossless bounding
	// strategy exist at all, since the default is lossy and runs first
	// otherwise.
	Result  string
	Replace bool
	// Meta annotates the trace without entering the model's context (for example
	// a cache verdict). Empty leaves the trace unchanged.
	Meta string
	// ResultRef is an opaque handle that recovers content omitted from Result
	// (for example a spill locator). It is persisted on the tool message and
	// context-reduction paths preserve and surface it in replacement text. Keep
	// unrelated trace metadata in Meta: the model may be shown ResultRef later.
	ResultRef string
	// AdditionalContexts are messages to add to the conversation because of
	// this call. The LOOP appends them after ALL tool results in the batch —
	// never interleaved, which would break tool-call/result adjacency — and
	// persists them to the durable log.
	//
	// Persistence is the loop's job precisely so it cannot be forgotten: an
	// extension that injects a message the model sees but the log misses would
	// make a resumed run replay a different conversation. Plugins get the
	// injection; the core keeps the invariant.
	AdditionalContexts []Message
	// Terminate ends the run cleanly after this batch (a terminal tool).
	Terminate bool
}

type ToolSchema = protocol.ToolSchema

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

type ToolStrictness = protocol.ToolStrictness

type ToolTrace struct {
	// CallID is the provider's id for this specific invocation. It is what makes a
	// trace addressable: two concurrent calls to the same tool differ in nothing
	// else, so a consumer keying on name (or on array position, which shifts as
	// the list grows) reconciles the wrong one onto the other. Empty only for a
	// synthesized trace with no originating model call.
	CallID     string `json:"call_id,omitempty"`
	Tool       string `json:"tool"`
	Args       string `json:"args"`
	Allowed    bool   `json:"allowed"`
	Reason     string `json:"reason,omitempty"`
	Error      string `json:"error,omitempty"`
	ResultMeta string `json:"result_meta,omitempty"`
	LatencyMS  int64  `json:"latency_ms,omitempty"` // wall-clock of the tool execution (0 when not executed)
	// IdempotencyKey is the framework-derived dedupe key handed to the tool
	// (empty on runs without a durable session). Persisting it lets an external
	// side effect be correlated back to the exact logical call that caused it.
	IdempotencyKey string `json:"idempotency_key,omitempty"`
	// SpillLocator is set when the result was too large for the context and its
	// full text was saved to a spill artifact (plugins/spill). It makes the complete
	// output recoverable from the trace long after the run, not just by the model
	// mid-run — an oversized result is no longer lost to observability either.
	SpillLocator string `json:"spill_locator,omitempty"`
}

type ToolsPlugin struct {
	Label string
	Tools []Tool
}

type TurnHook func(ctx context.Context, info TurnInfo)

type TurnInfo struct {
	Turn int
	// Model is the rung actually in use for this turn.
	Model string
	// Usage is the run-to-date total at the boundary.
	Usage Usage
	// StopReason is set at turn end only (empty at turn start) and carries the
	// provider's reason for the turn that just completed.
	StopReason string
}

type TurnRecord struct {
	NativeTrace     json.RawMessage
	SessionKey      string
	Depth           int
	Messages        []Message        // the request messages sent to the model this turn
	Response        string           // assistant text returned
	ReasoningBlocks []ReasoningBlock // opaque provider replay blocks returned with the assistant turn
	ToolCalls       []ToolCall       // the tool calls the model requested this turn
	// ToolGates is the gate outcome of each call in ToolCalls. Empty means the
	// recording predates this field (or the turn requested no tools) — FoldSteps
	// then keeps the historical default rather than inventing denials. See ToolGate.
	ToolGates  []ToolGate
	Tools      []string // advertised tool names this turn
	StopReason string
	Error      string
	TokensIn   int
	TokensOut  int
	CostUSD    float64
}

type TurnState struct {
	Model    string
	Tools    *ToolSet
	System   string
	Messages []Message
}

type Usage = protocol.Usage