stitchkit 0.122.1 → 0.122.2

package/llms/agent-runtime.4.txt

@@ -1,113 +1,546 @@
-# stitchkit/agent-runtime — stitchkit docs slice, part 4 of 4
+# stitchkit/agent-runtime — stitchkit docs slice, part 4 of 5
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/agent-runtime.5.txt`.
 
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
-- `llms/agent-runtime.4.txt`: API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
+- `llms/agent-runtime.4.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
+- `llms/agent-runtime.5.txt`: API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
-# API reference: `stitchkit-tui`  (docs/api/reference.md)
+# Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
-## `stitchkit-tui`
+## Observability
 
-Separate optional evolving Bun/OpenTUI package over a caller-composed headless harness.
+`createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
+reuses the same bounded sink lifecycle as request/tool observability without
+sending new event kinds to existing request sinks. Product events omit provider
+causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
+set `includeInternalCause` and own its retention policy.
 
-| Export | Kind | Summary |
-|--------|------|---------|
-| `defineAgentTui` | function | typed config for title, `theme` (a `TerminalPalette` override) and `themeMode`, status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
-| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override; it closes the session and exits the process on Ctrl-C and every signal OpenTUI catches unless `exitSignals: []` |
-| `defineTuiCommand` / `resolveTuiCommand` | function | typed composable slash-command registry; unknown slash input remains an ordinary model prompt |
-| `createAgentTuiController` | function | single admission, selection, approval, interruption and conversation-switch owner over the harness |
-| `startAgentTuiSessionHost` / `createAgentTuiClient` | function | authenticated mode-`0600` Unix-socket host/client for status, submit and interrupt through that controller |
-| `listAgentTuiSessions` | function | discover live local terminal session IDs and their current conversation |
-| `createAgentTuiComposer` / `navigateAgentTuiHistory` | function | multiline draft and reversible prompt-history state |
-| `defaultAgentTuiStatusLine` / `AgentTuiStatusLineFormatter` | function / _type_ | terminal-native default rows and a host formatter over model capacity, durable snapshot, activity, workspace and local identities; `statusLine: false` hides the rows |
-| `createAgentTuiDiagnosticRecorder` / `AgentTuiDiagnosticEventSchema` | function / schema | bounded per-session metadata journal that rejects prompt, reasoning, tool-input and provider-cause payloads before disk admission |
-
-The `stitchkit-agent` binary runs React's production build unless `NODE_ENV` says otherwise and loads `stitchkit.agent.ts` by default and also exposes `sessions`,
-`status`, `send` and `interrupt`. `--workspace` addresses a host outside the caller's cwd,
-`send --idempotency-key` accepts caller-owned retry identity, and `interrupt` defaults to the
-active run returned by `status`. Session descriptors and sockets are local control credentials,
-not a remote API.
-Interactive `/resume` and `/sessions` open the durable conversation picker. `/clear` creates a new
-conversation and keeps the previous one available there; it is not a viewport-only operation.
-The slash palette owns its highlighted selection: Up/Down move it, Tab completes it, Enter runs
-the exact command and Escape dismisses it. Partial input is never submitted while the palette is
-active; unknown slash text with no match remains an ordinary model prompt.
-
-### `stitchkit-tui/core`
-
-Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor the agent runtime.
+### What a run says it spent
 
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createTerminalCollection` / `reduceTerminalCollection` | function | identity-stable live collection selection, reconciliation, windowing and resize |
-| `createTerminalFeedViewport` / `reduceTerminalFeedViewport` | function | generic follow-tail, history anchoring, unseen and bounded visible-range state |
-| `createTerminalPaneState` / `reduceTerminalPaneState` | function | bounded split-pane focus, resize and single-pane collapse |
-| `createTerminalCommandPalette` / `terminalCommandMatches` | function | bounded command filtering and keyboard selection over a collision-validated registry |
-| `resolveExactTerminalCommand` / `validateTerminalCommands` | function | exact dispatch and fail-closed name/alias validation |
-| `createTerminalOperationState` / `reduceTerminalOperationState` | function | confirmation and single-pending-operation lifecycle |
-| `createTerminalTable` / `reduceTerminalTable` / `projectTerminalTable` | function | live table: typed columns, rows validated on entry, sort with key tie-break and missing values last, tree expansion pruned to present rows, filter on displayed text, selection kept across data; a row's `tone` and a column's `tone(value, row)` colour state |
-| `layoutTerminalTableColumns` / `formatTerminalTableCell` / `visibleTerminalTableRows` / `terminalTableTreePrefix` | function | fixed and flexible column widths, `—` for missing values, the virtualized window, tree indentation |
-| `createTerminalList` / `reduceTerminalList` / `visibleTerminalListLines` | function | picker with sections, fuzzy query with title highlight ranges, multi-select, disabled items and "more above/below" counts |
-| `createTerminalForm` / `reduceTerminalForm` / `readTerminalForm` / `terminalFormFieldsFromJsonSchema` | function | typed fields (text, secret, number, integer, boolean, choice, JSON) from a JSON Schema, relative text edits, validation on leave and submit |
-| `createTerminalTabs` / `reduceTerminalTabs` | function | tabs with badges, wrap-around movement, digit selection and reconcile that keeps the selected tab |
-| `createTerminalNavigation` / `reduceTerminalNavigation` / `terminalBreadcrumbs` | function | screen stack keeping each level's state, root never popped |
-| `createTerminalFocus` / `reduceTerminalFocus` | function | focus ring plus layers that take the keyboard and give it back |
-| `createTerminalNotices` / `reduceTerminalNotices` / `nextTerminalNoticeExpiry` | function | bounded toasts on a caller clock, replaced by id |
-| `createTerminalTimeSeries` / `appendTerminalSample` / `sampleTerminalTimeSeries` | function | time window bounded by duration and sample count, value-in-force sampling with explicit gaps |
-| `terminalBrailleChart` / `terminalSparkline` / `terminalTimeAxis` / `terminalChartScale` | function | multi-series braille line or area chart as toned runs, sparkline, time axis |
-| `terminalMeter` / `layoutTerminalMeterGrid` | function | eighth-block bar toned by thresholds, unmeasured as muted; column-major core grid |
-| `terminalProgress` / `terminalSpinnerFrame` / `terminalIndeterminateBlock` / `formatTerminalDuration` | function | ratio, rate and ETA only when knowable; spinner frames; indeterminate bar; elapsed time |
-| `defineTerminalKeymap` / `matchTerminalKey` / `fitTerminalKeyHints` | function | conflict-checked bindings that both answer keys and draw a footer fitted to the width |
-| `terminalTableKeymap` / `terminalTableKey` / `terminalTabsKeymap` / `terminalTabsKey` | function | htop-style table bindings and tab bindings as keymaps |
-| `matchTerminalSearch` / `searchTerminalItems` / `terminalHighlightRuns` | function | multi-word fuzzy match with ranges, stable ranking, highlight runs |
-| `sanitizeTerminalText` / `terminalTextWidth` / `truncateTerminalText` / `fitTerminalText` / `wrapTerminalText` | function | strip escape and control sequences; measure, cut, pad and wrap by terminal cells |
-| `terminalTextEdit` / `applyTerminalTextEdit` | function | one-line edits as relative actions, so fast input is never lost |
-| `terminalJsonLines` / `layoutTerminalDetails` | function | toned, sanitized JSON lines; aligned key/value pairs |
-| `terminalPalettes` / `resolveTerminalPalette` / `TerminalPalette` / `TerminalTone` | value / function / _type_ | one semantic palette (surfaces plus `primary`, `muted`, `accent`, `success`, `warning`, `danger`) for dark and light terminals |
-| `terminalLabelsEn` / `terminalLabelsRu` / `TerminalLabels` | value / _type_ | every word the widgets draw |
-
-### `stitchkit-tui/widgets`
-
-OpenTUI React widgets over the core state. React, `@opentui/core` and `@opentui/react` are peers;
-this entrypoint never loads `stitchkit`.
+Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
+provenance, **per field**. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD.
 
-| Export | Kind | Summary |
-|--------|------|---------|
-| `TerminalAppShell` / `TerminalPanel` / `TerminalStatusBar` / `TerminalKeyHints` | component | breadcrumbs, status lines, body, fitted key hints and toast overlay; titled rounded panels with a focus frame |
-| `TerminalTable` | component | virtualized live table with header sort marks, tree, filter line and htop keys; row and cell tones in the palette, bold or dim where colour is missing |
-| `terminalToneAttributes` | function | the text attribute that carries a tone without colour: `danger` and `warning` bold, `muted` dim |
-| `TerminalList` | component | sections, fuzzy search line with highlights, `›` cursor, meta, badges, multi-select, description |
-| `runTerminalApp` / `RunTerminalAppOptions` / `RunningTerminalApp` | function / _type_ | start an application: renderer, theme and labels providers, the error boundary, and an exit with 128 + signal after `onClose` on Ctrl-C and every signal OpenTUI catches — a closed window leaves no orphan |
-| `TerminalErrorBoundary` / `TERMINAL_EXIT_SIGNALS` / `TerminalExitSignal` | component / value / _type_ | draws a render error and its stack in place of the screen, where OpenTUI's own boundary renders nothing under production React |
-| `TerminalForm` | component | fields edited in place, cycling choices, masked secrets, inline errors; a form without fields says so and submits `{}` on Enter |
-| `TerminalTextView` / `TerminalJsonView` | component | pager over sanitized wrapped text or toned JSON |
-| `TerminalMeter` / `TerminalMeterGrid` / `TerminalChart` / `TerminalSparkline` | component | htop meters and core grid; btop braille charts with axis |
-| `TerminalTabs` / `TerminalDialog` / `TerminalSpinner` / `TerminalProgressBar` / `TerminalAsyncView` / `TerminalDetails` / `TerminalNotices` / `TerminalHelp` | component | views, confirmation, loading, progress, async states, details, toasts, key help |
-| `TerminalThemeProvider` / `useTerminalPalette` / `useTerminalThemeMode` | component / hook | palette from the terminal's reported background (`auto`) or a fixed mode |
-| `TerminalLabelsProvider` / `TerminalFocusProvider` / `useTerminalFocused` | component / hook | product language and shared focus |
+Read the provenance before the number (→ ADR 0109):
+
+- **`provider-reported`** — the provider handed us exactly this. On
+  `step-finished`, that is what a step's figures are.
+- **`computed`** — a total, added up over steps. **Every figure on a terminal
+  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
+  performed, not a number a provider reported for the run. It is not a figure to
+  bill against unchanged.
+- **`unavailable`** — nobody reported it. Not zero.
+
+Two rules follow from that last one, and they differ by field on purpose:
+
+- **A token total with an unreported step is a floor**, labelled `computed`. A
+  token count is a diagnostic, and a floor is a useful one.
+- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
+  people bill against, and "at least $1.00" reported as `$1.00` is the same class
+  of lie this whole section exists to remove. One step that did not report its
+  cost makes the run's cost unknown — not smaller. It also stays unknown: later
+  steps reporting normally cannot revive it.
+
+**A terminal event always carries `usage`.** A run that ended before the provider
+reported anything — superseded, interrupted, timed out, shut down, failed —
+carries every field `unavailable`. That is deliberately different from a run that
+spent nothing, and an omitted object could not tell you which one you had.
+
+Two costs in different currencies do not add: the sum reports `unavailable`
+rather than picking a label. The core records a currency and never converts one.
+
+`step-finished.response` identifies the provider response for that one step. The terminal event
+does not copy the last response: response identity remains per-step, while every terminal usage
+figure remains a `computed` aggregate.
+
+**A run's figure is durable, and that is where to read it when a channel loses
+it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
+record, so a crashed process leaves behind what it had already spent and a
+dropped event is not a lost number:
+
+```ts
+const snapshot = await store.loadSnapshot(conversationId)
+const spent = snapshot.runs.find((run) => run.id === runId)?.usage
+```
+
+Two gaps are open and are stated rather than left to be discovered:
+
+- **Both event sinks are bounded and drop under load**, by arrival order — the
+  event carrying the money is exactly as droppable as the one carrying nothing.
+  The run record is the recovery, and this paragraph is the only place that says
+  so.
+- **`AgentRuntimeResult.metrics` is `undefined` when this executor did not win
+  the terminal race.** Read `result.run.usage` — the durable figure — rather than
+  `result.metrics`, which is the channel that can go missing.
+- **Compaction spend is invisible unless you report it.** `config.history.compact`
+  calls a model inside the turn and produces no step and no event of its own.
+  Return `usage` from `AgentCompactionResult` and it joins the run's figure;
+  omit it and the run under-reports by whatever summarising cost.
+
+What stitchkit does **not** keep is a ledger: one figure, on the run that
+produced it, never aggregated and never reconciled against a provider invoice
+(→ ADR 0110).
+
+### Reconciling with the provider's own accounting
+
+Whether a provider bills for a call that was aborted mid-flight cannot be known
+inside the process: the authoritative number arrives later, from the provider's
+accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
+is an absorbing state, and a write that reached it through the conversation
+aggregate could conflict a concurrent compaction into discarding a summary it had
+just paid a model to produce.
+
+The join is yours, and `runId` is the key:
+
+```ts
+// when the run terminates — write what the runtime observed
+await ledger.record({
+  runId: terminal.run.id,
+  conversationId: terminal.run.conversationId,
+  // The durable figure, not `terminal.metrics` — that one is absent whenever
+  // this executor did not win the terminal race.
+  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
+  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
+})
+
+// later — the provider's accounting names the same generation
+await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```
+
+Record the row even when the figure is `unavailable`: that row is the evidence
+that a run happened and cost something nobody has counted yet, and it is what the
+provider's later figure attaches to. A run with no row is a run you cannot
+reconcile.
+
+The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
+outbox.
+
+## Deterministic race and adapter proof
+
+`stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
+`createAgentRaceTrace` and `runAgentStoreConformance` — agent testing tools live beside the agent
+runtime, and `stitchkit/testing` imports none of it. Barriers have bounded teardown, traces assert exact partial order, and the
+helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
+coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
+causal queued-history order, durable interrupt priority, compaction and recovery invariants against
+any fresh durable adapter.
+
+It picks its conversation identities itself and passes them to `createStore(context)` **before the
+first mutation**, so an adapter whose runtime rows reference an application-owned conversation row
+can provision those parents; the optional `cleanup(context)` removes them again, and runs once
+whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
+keeps working unchanged.
+
+## Plain completions and shared invocation receipts
+
+Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
+completion and an agent must share causal provider evidence. It uses the existing
+runtime store, not a second database. The completion path sends exactly one user
+prompt, no framework instructions and no tools. It never starts an agent loop.
+
+```ts
+import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
+
+const invocations = createModelInvocationLedger({
+  store, // the same AgentRuntimeStore object passed to createAgentRuntime
+  models, // an existing defineModelRegistry result
+  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
+  authorize: async ({ context, conversationId, action, trace }) => {
+    const session = await authenticate(context);
+    await authorizeConversation(session, conversationId, action, trace);
+    return { subject: session.subject }; // verified identity, never a body field
+  },
+});
+
+const completion = await invocations.complete({
+  conversationId: 'evaluation-42',
+  idempotencyKey: 'summary-case-3',
+  trace: {
+    operationId: 'summary-42', purpose: 'summarize', project: 'example',
+    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
+  },
+  prompt: 'Summarize these supplied facts.',
+  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
+  settings: { maxOutputTokens: 500 },
+  timeoutMs: 30_000,
+}, authenticatedContext);
+
+// Add to the existing createAgentRuntime configuration:
+const receiptConfig = {
+  ledger: invocations,
+  trace: ({ run }) => ({
+    operationId: run.id, purpose: 'assistant-turn', project: 'example',
+  }),
+};
+// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
 
-The `stitchkit-tui-gallery` binary shows every widget live.
+const page = await invocations.read({
+  conversationId: 'evaluation-42', limit: 100,
+}, authenticatedContext);
+// Continue with fromSeq: page.nextSeq while it is defined.
+```
 
-### `stitchkit-tui/build`
+`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
+returns the existing ID without provider execution or replaying plaintext. Changed
+input, trace or caller under the same key is a conflict. Model attempts are explicit
+and bounded to eight; SDK retries are disabled. Only provider failures trigger the
+next attempt. Abort, audit refusal and configuration errors do not. An admitted call
+whose process died stays claimed: inspect the receipt before choosing a new key.
 
-Build-time only; imports Bun and no React.
+The agent retains its existing prompt, tools and loop. Both modes produce
+`invocation/started`, `provider/request`, `provider/response` and
+`invocation/finished` records through `read`. Each attempt has its own ID; response
+usage is counted once and keeps `unavailable` distinct from measured zero. Requested
+registry selection, sent adapter identity and effective provider identity are
+separate. Effective identity is null when not reported. A gateway's hidden retries
+are not visible as additional attempts.
+
+`currentModelInvocationAttempt()` returns the causal context inside a provider's
+`fetch` callback or streamed read. Use it to join a host transport audit to
+`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
+`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
+SDK payload hashes are not represented as hashes of HTTP wire bytes.
+
+Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
+hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
+`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
+bytes and is copied at construction. Keep it outside the event store/backups; retain
+the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
+(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
+that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
+the answer itself is never cut. A receipt that cannot be written never changes an
+outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
+answer keeps its `text`. Request headers
+are excluded. Protect existing agent history independently: enabling receipts does
+not encrypt its ordinary conversation records.
+
+The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
+must implement its once-only check and append atomically, returning the original
+event on a duplicate key scoped by conversation and kind. A factory without this
+capability refuses receipt setup. The driver-backed implementation finds the keyed
+event by its identity through the driver's optional `events.find` — one index probe
+in SQLite — so admission costs the same on a long conversation as on a new one; a
+custom driver without `find` falls back to paging the log in one transaction.
+`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
+Invocation payload artifacts are keyed by their artifact id the same way.
+
+### Migration from direct SDK completions
+
+**Who must act:** applications opting into shared completion/agent receipts.
+Replace the direct `generateText` call with `invocations.complete`, configure host
+authorization and a retained payload key, and pass the same ledger in the agent's
+`invocations` option. Use the returned invocation ID and the paginated `read` method
+for receipt queries; do not import runtime internals. Available since 0.100.0;
+existing runtime configurations need no migration.
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime`
+
+Server-only optional application runtime. See the
+[agent runtime guide](../guide/agent-runtime.md).
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `compileTerminalApp` / `CompileTerminalAppOptions` | function / _type_ | one standalone executable for any Bun compile target, from any machine, with React's production build defined |
-| `terminalNativePlugin` / `TerminalNativePluginOptions` | function / _type_ | the `Bun.build` plugin behind it: the target's `@opentui/core-<os>-<arch>` at the pinned version from the registry, verified against `bun.lock`; other platforms' packages throw; musl refused |
-| `terminalNativeTarget` / `TerminalNativeTarget` | function / _type_ | the native package a compile target needs |
+| `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and winner-only terminal publication; reconciles same-owner terminal/interrupt/head CAS races before releasing the lane |
+| `createDeferredAgentToolSurface` | function | bounded canonical catalog search plus durable same-run activation of direct `mountAgent` tools; supports one immutable surface or a finite identity-specific registry |
+| `DeferredAgentToolSearchInputSchema` / `DeferredAgentToolMatchSchema` / `DeferredAgentToolReceiptSchema` | schema | bounded search input, public match and versioned durable selection receipt |
+| `DeferredAgentToolSurfaceConfig` / `DeferredAgentToolCommonConfig` / `DeferredAgentToolSurfaceDefinition` / `DeferredAgentToolController` | _type_ | finite catalogs, selector, pin, budget and `mount`/`prepareStep` composition contracts |
+| `DeferredAgentRuntimeToolDefinition` / `DeferredAgentToolMountConfig` | _type_ | peer-free Agent-only runtime definition and canonical mount configuration accepted by the controller |
+| `DeferredAgentToolManifestEntry` / `DeferredAgentToolSearchContext` / `DeferredAgentToolReceipt` | _type_ | canonical selector input and inferred durable receipt records |
+| `DeferredAgentToolEvent` | _type_ | PII-free search/step evidence with surface, provenance, counts, canonical schema bytes and ceilings |
+| `defineAgentProtocol` | function | declare context, input metadata, canonical parts and optional pre-CAS terminal acceptance (`allow-empty`, `require-output` or callback) |
+| `hasAgentTerminalOutput` | function | generic `require-output` predicate for non-blank text, generated files, structured provider parts and explicit tool-only policy stops |
+| `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
+| `AgentRunQueuePrioritySchema` | schema | durable opt-in priority for queued `interrupt-next` runs |
+| `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
+| `BranchAgentConversationInputSchema` / `BranchAgentConversationInput` | schema / _type_ | strict branch request: stable request key, empty destination, settled conversation boundary or archive bytes, fresh artifact authorization |
+| `AgentConversationBranchReceiptSchema` / `AgentConversationBranchReceipt` | schema / _type_ | durable lineage: request fingerprint, source/destination identities, source sequence/version/digest and creation time |
+| `AgentConversationBranchResultSchema` / `AgentConversationBranchResult` | schema / _type_ | `created` or `duplicate` with the same durable receipt; `AgentRuntimeStore.branchConversation` is optional for hand-written stores |
+| `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
+| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history, a **required** `events: { append, list }` ledger table, an optional `archive: { export, import }` for driver-owned durable payloads, and indexed run recovery; optional `{ access: 'read' }` selects a coherent read transaction while absent options remain write-safe |
+| `recordAgentRetryDecision` / `AgentRetryPolicy` | function / _type_ | `loop.retry` policy and the ledger record of a retry decision: explicit retryability and backoff at a durable provider-step boundary |
+| `AgentRuntimeHeadSchema` | schema | constant-size conversation identity plus monotonic runtime version |
+| `AgentStoredRunSchema` | schema | canonical normalized run with an optional retained terminal assistant |
+| `AgentAdmissionReceiptSchema` | schema | durable idempotency receipt with canonical input and assigned run/assistant identities |
+| `AgentHistoryMutationSchema` | schema | typed canonical message mutation applied inside the winning state transaction |
+| `RecoverAgentRunSchema` | schema | explicit abandon/requeue recovery decision; acquired runs require replay-safe evidence |
+| `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
+| `purgeAgentConversation` | function | dispatch optional atomic deletion; returns `unsupported`, `active`, `conflict`, `purged` or `already_purged` |
+| `AgentConversationPurgeInputSchema` / `AgentConversationPurgeInput` | schema / _type_ | conversation ID and optional expected snapshot version |
+| `AgentConversationPurgeResultSchema` / `AgentConversationPurgeResult` | schema / _type_ | typed deletion/refusal outcomes; active refusal includes run IDs |
+| `AgentConversationPurgedError` | class | runtime mutation rejected because its conversation ID is permanently purged |
+| `AgentConversationPurgeDriver` | _type_ | optional `driver.conversations` capability: serialized tombstone read and atomic removal of all owned records |
+| `projectAgentHistory` | function | asynchronously project canonical records and resolved multimodal files into provider-valid AI SDK messages |
+| `defineModelRegistry` | function | typed language-model descriptors, capabilities and provider construction |
+| `AgentModelCatalogSchema` / `AgentModelCatalog` | schema / _type_ | provider-neutral complete/partial model catalog with separately sourced popularity, metrics, prices and observation time |
+| `AgentModelCatalogEntrySchema` / `AgentModelCatalogEntry` | schema / _type_ | one canonical provider model descriptor with optional price, popularity and metric evidence |
+| `AgentModelPriceSchema` / `AgentModelPrice` | schema / _type_ | normalized per-token input/output pricing and source currency |
+| `AgentModelPopularitySchema` / `AgentModelPopularity` | schema / _type_ | independently sourced ranked popularity observation with window and timestamp |
+| `AgentModelMetricSchema` / `AgentModelMetric` | schema / _type_ | independently sourced benchmark measurement with provenance and observation time |
+| `AgentModelCatalogProvider` | _type_ | abortable live catalog loader supplied by a provider adapter or application |
+| `AgentModelSearchInputSchema` / `AgentModelSearchInput` | schema / _type_ | bounded catalog text query and result ceiling |
+| `AgentModelSearchResultSchema` / `AgentModelSearchResult` | schema / _type_ | exact bounded catalog projection with total match count |
+| `searchAgentModelCatalog` | function | deterministic bounded search over a loaded canonical catalog |
+| `AgentModelSelectionSchema` / `AgentModelSelection` / `AgentModelSelectionStore` | schema / _type_ | durable per-conversation model choice; runtime resolvers receive run and snapshot to recover the model pinned to input metadata |
+| `createMemoryAgentModelSelectionStore` | function | process-local selection reference adapter |
+| `AgentConversationReader` | _type_ | optional bounded conversation-summary and message-history reader; `messages` takes `includeCompacted` and every page names its `compacted` ids; not part of the required runtime store contract |
+| `AgentConversationSummarySchema` / `AgentConversationSummary` | schema / _type_ | bounded durable conversation list item with version, activity and preview |
+| `AgentConversationPageSchema` / `AgentConversationPage` | schema / _type_ | cursor-paged conversation summaries |
+| `AgentConversationMessagePageSchema` / `AgentConversationMessagePage` | schema / _type_ | cursor-paged durable message history |
+| `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
+| `SeedConversationInputSchema` / `SeedConversationInput` | schema / _type_ | atomic once-seeding input; partial imported identity sets are refused |
+| `AgentSeedReceiptSchema` / `AgentSeedReceipt` | schema / _type_ | durable seed receipt retained beyond compaction and implemented by custom store drivers |
+| `StepRunOptions` | _type_ | per-step options of the durability engine (`stitchkit/tools`) as the runtime drives it |
+| `DURABILITY_STEP_EVENT_KIND` | const | the ledger event kind a recorded step is written under |
+| `StepResultDecodeError` / `StepResultNotSerializableError` / `StepAbortedError` / `ParkRecordDecodeError` / `ParkAbortedError` | class | fail-closed decode of a recorded step or park, a body whose result cannot be serialized, an aborted step, and a park collapsed around an aborted waiter |
+| `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
+| `selectCompactableHistory` | function | which oldest whole complete turns may be summarised away — the half of compaction that needs no store (→ ADR 0142) |
+| `SelectCompactableHistoryOptions` / `CompactableHistory` | _type_ | message list, retained-turn count and evidence policy in; `leadingSummary`, `compactable` and `retained` out |
+| `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
+| `AgentRuntimeStopPolicy` | _type_ | named stop rule persisted and published on policy stop; `when` receives the AI SDK `steps` plus the run context `prepareStep` gets (`context`, `run`, `signal`, `toolFenceLifecycle`, `contextUsage`) |
+| `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
+| `AgentContextOverflowError` | class | deliberate application budget refusal thrown from `loop.prepareStep`; terminalizes as `context_overflow` without classifying arbitrary error text |
+| `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
+| `AgentRuntimeAdmission` | _type_ | canonical committed input, assigned run, pending assistant projection, compatibility IDs and snapshot version |
+| `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
+| `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` says the provider never reported the run finished, so the figure beside it is not a confirmed total |
+| `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with causal per-conversation scheduling, context resolver and explicit evidence policy |
+| `AgentRuntimeAbandonInput` | _type_ | one known orphan identity, expected revision and mandatory stale-owner evidence for `runtime.abandon()` |
+| `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
+| `AgentRunUnsettledError` | class | rejects `result` when the store never answered: `.run` is still active with no executor, close it with `runtime.abandon()` |
+| `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
+| `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
+| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
+| `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent`; compose beside application idempotency for [durable operations](../guide/mcp-and-agents.md#durable-application-owned-execution) |
+| `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/run-operation/terminal projections |
+| `AgentRunOperationKindSchema` / `AgentRunOperationPhaseSchema` / `AgentRunOperationSchema` / `AgentRunOperation` | schemas / _type_ | latest durable model-request or compaction phase with operation/step identity and original timestamps; request admission is awaited before provider invocation |
+| `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
+| `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
+| `AgentProviderResponseSchema` / `AgentProviderResponse` | schema / _type_ | provider-assigned response ID and the optional upstream provider the model's own adapter resolves, shared by `step-finished.response` and durable `provider/response` facts |
+| `AgentStepFinishedEventSchema` / `AgentStepFinishedEvent` | schema / _type_ | one completed provider step with required usage and provider response identity |
 
-### `stitchkit-tui/testing`
+### Durable capability layer
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `renderTerminalTest` / `TerminalTestScreen` / `TerminalTestOptions` | function / _type_ | a screen inside the kit's providers on a test terminal; `press`, `type`, `burst`, `advance`, `waitForText`, `resize` run inside React's `act` and wait out a lone Esc |
-| `TerminalTestKey` / `TerminalTestModifiers` | _type_ | the mock input's key names and modifiers |
+| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive (`canonicalAgentJson` is `canonicalJson` with the node and byte limits at their maximum, reading `-0` as `0` like `z.json()`) with exact ledger events, recovery projection and durable spill payloads |
+| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary (including `provider/request` and `provider/response`) and bounded page |
+| `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
+| `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
+| `AgentStoreTransitionRecordSchema` / `AgentStoreTransitionRecord` | schema / _type_ | persisted journal payloads: full runtime mutations or hash-only streaming checkpoint observations with numeric part/byte counts; inspection does not authorize replay |
+| `defineAgentProjection` / `AgentProjectionDefinition` / `AgentProjectionValue` / `createAgentProjectionRegistry` / `createSqliteAgentProjectionStore` | functions / _type_ | deterministic folds with persisted version and honest `uptoSeq` checkpoints |
+| `agentSummaryProjection` / `agentUsageProjection` / `agentOutlineProjection` | constants | built-in list summary, provenance-carrying usage and request outline projections |
+| `agentConversationCardProjection` / `agentStateSlotsProjection` / `agentScheduleSummaryProjection` | constants | focused card, durable-state and schedule lifecycle projections |
+| `defineStateSlot` / `AgentStateSlotDefinition` / `AgentStateSlotStore` / `AgentStateSlotValue` / `AnyAgentStateSlot` / `createAgentStateSlotStore` / `renderAgentStateSlots` | functions / _types_ | typed durable state written as ledger events and injected on every provider request |
+| `agentGoalStateSlot` / `agentTodoStateSlot` / `createAgentStateTools` | constants / function | built-in goal/todo state and bound `goal_*` / `todo_write` Agent tools |
+| `AgentSandboxGradeSchema` / `AgentSandboxGrade` / `AgentSandboxRestrictionSchema` / `AgentSandboxRestriction` / `AgentProcessSandbox` | schema / _type_ | host-provided process sandbox capability and explicit restriction vocabulary |
+| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | probe cached per sandbox object (keep the sandbox long-lived), fail-closed required-gap calculation and durable probe record; a probe that throws or returns no valid grade resolves to `unavailable` with a fixed reason, its cause emitted as a process warning (the coding tools instead carry it as the refusal's `cause` to the mount's `onToolError` hook) |
+| `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
+| `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
+| `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
+| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure (any other returned value delivers), `maxAttempts` (default 1000) per occurrence — a one-off ends `failed`, a recurring schedule skips to its next slot — bounded dispatch and fenced stable occurrence identity (ADR 0202) |
+| `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
+| `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
+| `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
+| `AgentToolDefinition` | _type_ | peer-neutral shape returned by the bound agent-only state, search, schedule and child tool factories |
+| `AgentProviderStreamCutError` | class | explicit retryable provider stream truncation evidence |
+
+### Complete runtime inventory
+
+The entrypoint deliberately exports the schemas beside their inferred types so persistence and
+transport adapters validate the same records. Runtime composition types are `AgentRuntime`,
+`AgentRuntimeConfig`, `AgentRuntimeInput`, `AgentRuntimeProtocolInput`, `AgentRuntimeRunContext`,
+`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeAbandonInput`, `AgentRuntimeRecoveryInput`,
+`AgentRuntimeRecoveryDecision`, `AgentRuntimeRecoveryOutcome`, `AgentRuntimePublisher`,
+`AgentInputPolicy`, `AgentStopReason`, `AgentCoordinatedRun`, `AgentRunTicket`,
+`AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
+`StructuredCompactionConfig`.
+
+A provider refusal is classified rather than phrased. `classifyProviderFailure` returns an
+`AgentProviderFailure` — an `AgentProviderFailureReason` (`insufficient-credits`, `rate-limited`,
+`model-unavailable`, `context-overflow`, `timeout`, `cancelled`, `unknown`), the provider's `status`
+when it supplied one, whether the same request is `retryable` unchanged, and the `evidence` the
+answer rests on: `status` is the provider stating its own answer, `message` is us reading its prose,
+and `none` is an honest refusal to guess. The sentence a user reads stays with the application —
+its tone and its decision about what to admit are not the core's to make. `isToolResultFailure`
+recognises a failure carried inside a *successful* tool result, in both the bare and the
+`{ value: … }` envelope. Both are plain functions and need no runtime. → ADR 0141
+
+`normalizeOpenRouterUsage` is the same normalisation `openRouterProvider`
+applies, exported so an application calling the SDK directly gets provenance-correct numbers
+without adopting the runtime. Pass each completed SDK step's usage, including `raw`.
+Token provenance comes from the original OpenRouter fields: missing fields remain
+`unavailable`, even when the SDK substitutes zero. Aggregate usage without `raw` cannot
+establish reported token counts. Explicit zero remains `provider-reported`; cost is never
+estimated from token prices.
+
+`AgentContextUsage` reaches every step through `AgentRuntimeRunContext.contextUsage`: how full the
+model's context is, as `usedTokens` (an `AgentUsageValue`, so it carries the provenance that says
+where the number came from) beside the model's declared `contextWindow`. It is the **last completed
+step's prompt size**, not the run's cumulative input tokens — cumulative counts every step's prompt
+again and is a multiple of the real fill. Before the first step lands there is no provider-reported
+number and the provenance is `unavailable`, which is a different fact from zero. No fraction is
+exposed: dividing is one line where it is rendered, and the output reserve belongs to the
+consumer's prompt budget rather than to this layer.
+
+Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentTerminalAcceptance`,
+`AgentTerminalAcceptanceInput`, `hasAgentTerminalOutput`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
+`AgentTimestampSchema`, `AgentJsonObjectSchema`, `AgentProviderEnvelopeSchema`,
+`AgentProviderEnvelope`, `AgentMessagePartSchema`, `AgentMessagePart`, `AgentTextPartSchema`,
+`AgentReasoningPartSchema`, `AgentFilePartSchema`, `AgentSourcePartSchema`,
+`AgentToolCallPartSchema`, `AgentToolResultPartSchema`, `AgentOpaquePartSchema`,
+`AgentControlPartSchema`, `AgentMessageRoleSchema`, `AgentMessageStatusSchema`, `AgentMessage`,
+`AgentAssistantPlaceholderSchema`, `AgentAssistantPlaceholder`, `AgentRunStateSchema`,
+`AgentTerminalReasonSchema`, `AgentTerminalReason`, `AgentRunQueuePrioritySchema`,
+`AgentRunQueuePriority`, `AgentRun`, `AgentSnapshot`,
+`AgentUsageValueSchema`, `AgentCostValueSchema`, `AgentUsageSchema`, `AgentUsage` and
+`AgentRunMetrics`.
+
+`AgentProvenanceSchema` / `AgentProvenance` is the entrypoint's single vocabulary for **how a
+number came to be known**: `provider-reported` (the provider stated it about a request it served),
+`measured` (this process counted it exactly, before any request was made), `computed` (arithmetic
+over other values — a sum of exact numbers is still `computed`), `estimated` (a heuristic) and
+`unavailable` (not known, so `value` is absent, which is a different fact from a reported zero).
+Each surface declares the subset it can produce: `AgentUsageValueSchema` and `AgentCostValueSchema`
+describe a request that has already happened and never say `measured`; `AgentTokenCountSchema`
+describes a prompt being composed and never says `provider-reported`. Every token count is an
+integer — `AgentUsageValueSchema` and `AgentTokenCountSchema` refuse a fractional `value`, and a
+provider figure that is not a whole number is normalised to `unavailable` rather than thrown.
+`AgentCostValueSchema.value` stays fractional, because money is.
+
+`runs.inputPolicy` takes `queue` (default), `inject`, `interrupt`, `interrupt-next` or `supersede`, or a function of
+the raw input returning one. `inject` lets a run in flight take a newly arrived input into its prompt
+at a step boundary and answer it too; the absorption is committed in the **same transaction** as that
+run's terminal record, via `CommitRunTerminal.absorb`, so a run that ends any other way leaves an
+ordinary queued successor. The absorbed run ends with `terminalReason: 'absorbed'`, run state
+`'superseded'`, `absorbedIntoRunId` naming the run that answered it, and **no assistant message of
+its own**; a submission on its idempotency key resolves through that pointer to the answer
+(→ ADR 0113).
+
+`interrupt-next` interrupts the active run, waits for its real settlement and then executes the new
+input before ordinary pending work. Ordinary work is not dropped or re-admitted, and urgent work is
+FIFO within its own class. `AgentRun.queuePriority` persists the pending class;
+`AgentRun.executionSequence` persists the actual first-acquisition order, so recovery and canonical
+history preserve the same `A → C → B` order across equal timestamps and scan pages (→ ADR 0127).
+
+With `queue`, a durable successor admission is not prompt eligibility: the current executor sees
+only records through its own run boundary. Snapshot history is normalized to causal turn order
+(assigned input(s), assistant, then successor input(s)) even when the storage codec physically
+appended the successor before the predecessor checkpoint.
+
+`AgentRuntimeStore` has two **bounded** reads beside `loadSnapshot`:
+`loadRun({ conversationId, runId })` returns an `AgentRunView` — the run, the conversation version it
+was read at, and the retained answer once the run is terminal — or `undefined`; `listActiveRuns(conversationId)`
+returns the runs that have not ended in durable execution/priority order. Neither reads history, so
+neither grows with the length of the conversation, and neither needs anything new from
+`AgentRuntimeStoreDriver`. `loadSnapshot` and every mutation result still carry the whole
+conversation — that is what the store's reducer validates against, and what the runtime builds a
+prompt from (→ ADR 0112).
+
+`AgentRuntimeStore.purgeConversation` is optional; `purgeAgentConversation(store, input)` explicitly
+handles unsupported stores. Official memory and initialized SQLite stores refuse active runs,
+remove every owned payload and reserve the conversation ID permanently. Empty snapshots are not
+deletion receipts. Consumer metadata, files, event logs and UI cache invalidation remain outside
+the transaction. See [purging a conversation](../guide/agent-runtime.md#purging-a-conversation).
+
+Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
+`AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
+`CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AgentRunView`, `AgentRunViewSchema`,
+`runStateForTerminalReason`,
+`ACTIVE_AGENT_RUN_STATES`, `RecoverAgentRun`, `ReplaceCompactedRange`,
+`ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
+`AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
+`AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
+`AgentRuntimeHead`, `AgentStoredRun`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
+`AgentRecoverableDescriptor`, `AgentRecoverableDescriptorSchema`, `AgentRecoverablePage` and
+`AgentRecoverablePageSchema`.
+
+History and context-budget exports are `projectAgentHistoryDetailed`,
+`AgentHistoryProjectionDecision`, `AgentHistoryProjectionResult`, `selectAgentHistory`,
+`SelectAgentHistoryOptions`, `AgentHistoryBudgetDecision`, `AgentHistoryBudgetResult`,
+`AgentPromptBudget`, `AgentPromptSection`, `AgentPromptSectionContext`, `AgentTokenCount`,
+`AgentTokenCountSchema`, `ComposeAgentPromptOptions` and `ComposedAgentPrompt`. Whole-turn history
+selection never splits a tool chronology and reports why every canonical record was retained or
+removed. `AgentHistoryEvidencePolicy` is the shared opt-in for marked failed-assistant evidence in
+projection, budgeting and structured compaction; `isAssistantHistoryEvidence` applies it. The
+compatibility default omits it. Approval message schemas are
+`AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
+
+With `failedAssistant: 'assistant-marked'`, `selectCompactableHistory` and
+`structuredCompaction` admit a failed prefix only when the entire turn's tool chronology
+is complete. `eligibleMessages` stays raw: the summarizer must use the same policy in
+`projectAgentHistoryDetailed` and preserve non-success/uncertain outcomes in its summary.
+Even an empty opted-in failed assistant carries a non-success marker in that projection.
+Use `incompleteToolTurn: 'error'` to refuse a range the projector cannot represent.
+Compaction never deletes canonical effect events or the retained terminal receipt;
+chronological completeness does not settle an external effect. See the
+[failed-prefix recovery contract](../guide/agent-runtime.md#recovering-a-prefix-after-a-failed-turn).
+
+Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
+`AgentModelCapabilitySchema`, `AgentModelDescriptor`,
+`AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,
+`AgentModelRegistrySnapshot`, `AgentModelRegistrySnapshotSchema`, `AgentModelSnapshotPolicy`,
+`AgentResolvedModel` and `validateAgentModelSnapshot`. Registry `preflight` validates availability,
+provider and required capabilities without constructing the model; runtime `models.preflight`
+runs before durable admission.
+
+Delivery exports are `AgentAdmissionEventSchema`, `AgentAttemptResetEventSchema`, `AgentCheckpointEventSchema`,
+`AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
+`AgentTransientDeltaEventSchema`,
+`AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
+`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentToolProgressEventSchema` (what a
+running tool reported through `ctx.reportProgress`, transient and never part of the model's input),
+`AgentRuntimeEvent`,
+`AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,
+`advanceAgentRuntimeEventCursor`, `agentDurableEventId`, `AgentRuntimeEventSink`,
+`AgentRuntimeEventSinkConfig` and `createAgentRuntimeEventSink`. Cursor gaps require a canonical
+snapshot reload; the bounded sink isolates transport failure and supports a typed projection step.
+
+Managed effects and operator telemetry additionally export `AgentToolFenceConfig`,
+`AgentToolFenceContext`, `AgentObservability`, `AgentRunEvent`, `AgentRunEventSchema`,
+`AgentRunStartedEvent`, `AgentRunStartedEventSchema`, `AgentStepFinishedEvent`,
+`AgentStepFinishedEventSchema`, `AgentRunTerminalEvent`, `AgentRunTerminalEventSchema`,
+`AgentRunSinkConfig`, `AgentRunSinkDrop` and `AgentRunSinkError`. A monotonic run `fencingToken`
+may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
+operator-only observability sink explicitly opts in.
+
+### Completion and agent invocation receipts
+
+`createModelInvocationLedger` constructs a `ModelInvocationLedger` from
+`ModelInvocationConfig`: the existing store and model registry, a 32-byte payload
+key, required host authorization, optional bounded payload size and `onAttempt`.
+`complete(input, context, signal?)` executes only the supplied prompt, with no tools
+or framework instructions; repeated keys return the existing invocation ID. It
+resolves `{ invocationId, outcome, text?, receiptError? }`: `receiptError` says a
+receipt could not be written and never changes `outcome` or drops `text`.
+`read(input, context)` returns a bounded event page shared by agent and completion;
+`readPayload(input, context)` requires a separate authorization action to decrypt
+one protected artifact. See the [guide and migration example](../guide/agent-runtime.md#plain-completions-and-shared-invocation-receipts).
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `CompletionInvocationInputSchema` / `CompletionInvocationInput` | schema/type | strict prompt, model-attempt list, deadline, idempotency key and trace input |
+| `ModelInvocationTraceSchema` / `ModelInvocationTrace` | schema/type | operation, purpose, project, parent trace and optional experiment/case/profile |
+| `ModelInvocationRecordSchema` / `ModelInvocationRecord` | schema/type | discriminated invocation start/finish and per-attempt requested/sent/effective evidence |
+| `ModelInvocationAttemptContext` | type | conversation, operation, invocation, attempt, step and optional agent run identity |
+| `currentModelInvocationAttempt` | function | returns causal IDs inside the provider transport; undefined outside an invocation |
+
+The runtime `invocations` option takes this ledger and a trace callback; it requires
+the same store and preserves the existing tool loop. `AgentRuntimeStore.appendEventOnce`
+is an optional atomic capability required by receipt admission, and
+`AgentRuntimeStore.findEventOnce` reads the event it wrote by kind and key. Built-in
+stores supply both; custom adapters must honor the once-only transaction contract.
+A driver's optional `events.find(transaction, { conversationId, eventId })` makes
+both one lookup instead of a scan of the conversation log.