stitchkit 0.122.0 → 0.122.2

package/llms/agent-runtime.3.txt

@@ -1,4 +1,4 @@
-# stitchkit/agent-runtime — stitchkit docs slice, part 3 of 4
+# stitchkit/agent-runtime — stitchkit docs slice, part 3 of 5
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
@@ -7,539 +7,780 @@
 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)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
-## Observability
+## What happens to a run when new input arrives
+
+`runs.inputPolicy` decides. It takes five values, or a function returning one:
+
+| policy | the run in flight | what it already produced |
+|--------|-------------------|--------------------------|
+| `queue` (default) | finishes first | kept |
+| `inject` | continues, and answers the new input too | kept, and built on |
+| `interrupt` | ends | kept, and marked as cut off |
+| `interrupt-next` | ends; this input runs before ordinary queued work | kept, and marked as cut off |
+| `supersede` | ends | discarded from the prompt, kept in the record |
+
+`interrupt-next` is the explicit priority path for an urgent input. If A is
+running, ordinary B is queued, and urgent C arrives, the coordinator aborts A,
+waits for A to settle and then runs C before B. B keeps its durable identity and
+eventually runs. Urgent inputs remain FIFO among themselves. They do not
+coalesce into an ordinary pending run: that would erase the priority boundary.
+
+`interrupt` and `supersede` differ in exactly one thing, and the question that
+picks between them is **not** "was the run interrupted" but **"did anyone see
+what it produced"**:
+
+- The user pressed **stop**. The partial answer was streamed to their screen and
+  they read it. It belongs in the conversation — dropping it makes the history
+  lie to the model about what the human has seen. That is `interrupt`.
+- A newer message **superseded** the run. Whether the partial reached anyone
+  depends on the delivery surface: a token stream shows it as it is produced, a
+  surface that sends nothing until the run is done never showed it at all. When
+  it reached nobody, it is not part of the conversation. That is `supersede`.
+
+**Stitchkit cannot answer that question for you** — delivery belongs to the
+transport, and the runtime sees an abort, not a screen. Hence a declared policy
+(→ ADR 0108), and hence `inputPolicy` accepting a function, so one application
+can hold two surfaces with different rules without the core learning which is
+which:
 
-`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.
+```ts
+runs: {
+  inputPolicy: (input) =>
+    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
+}
+```
 
-### What a run says it spent
+`input.context` is the **raw** context here — admission runs before the runtime
+parses it, so the callback narrows it itself with the protocol it already has.
 
-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.
+A superseded run ends with `terminalReason: 'superseded'`, run state
+`'superseded'` and an assistant message of status `'superseded'`. **The record
+is kept** — excluded from the projection, not deleted — so an operator can see
+what was thrown away, and run identity, admission receipts and the terminal CAS
+keep the row they depend on. Compaction leaves it alone for the same reason: a
+turn whose answer is never spoken is not a turn that may be summarised into one,
+because that would both feed the discarded text to the summariser and drop the
+record in `replacedMessageIds`.
 
-Read the provenance before the number (→ ADR 0109):
+It is also outside the token budget. `selectAgentHistory` removes it with reason
+`'superseded'` and does not count it, so an abandoned fragment cannot push a
+real turn out of a context it never occupies.
 
-- **`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.
+### How an interrupted turn reaches the model
 
-Two rules follow from that last one, and they differ by field on purpose:
+An interrupted turn is projected, and says so:
 
-- **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.
+```text
+{ role: 'assistant', content: [
+    { type: 'text', text: 'We are the team, where would you like' },
+    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
+]}
+```
 
-**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.
+`history.interruptedAssistant` chooses the form, and the difference between the
+first two is structural rather than cosmetic. **An assistant turn in provider
+history is a commitment**: the model reads its own previous turn as something it
+said and stays consistent with it. A system line is context.
 
-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.
+| value | form | right when |
+|-------|------|-----------|
+| `assistant-marked` (default) | assistant turn plus a marker | the human read the text |
+| `system-note` | `[interrupted] partial response: …` as a system line | the fragment reached nobody |
+| `omit` | not projected at all | you want it gone from the request |
 
-`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.
+There is deliberately no value that reproduces what the projection used to do,
+which was to send the partial as an ordinary assistant turn and drop its
+`control` marker on the way. That was the defect, not a behaviour to stay
+compatible with.
 
-**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:
+`projectAgentHistoryDetailed` reports what reached the provider, including part
+types that no projected content stands for:
 
 ```ts
-const snapshot = await store.loadSnapshot(conversationId)
-const spent = snapshot.runs.find((run) => run.id === runId)?.usage
+const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
+// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
+//      omittedParts: ['source', 'provider'] }
+// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
 ```
 
-Two gaps are open and are stated rather than left to be discovered:
+`runtime.stop(key, 'supersede')` is the same decision taken by hand: the
+process-local escape hatch chooses the reason, so a caller that knows the answer
+was never delivered can discard it without a newer input arriving.
+
+### An input that joins a run in flight
+
+`inject` is right when the new input **refines** rather than redirects, and the
+steps already taken are still worth something: *"summarise this thread… actually,
+in bullet points"* should not throw away the reading the first message paid for.
+
+What happens:
+
+1. The input is admitted exactly like any other — a committed user message and a
+   **queued run**, durable before anything else happens.
+2. At the running loop's next step boundary, that input joins its prompt. Only
+   that input: an unrelated queued submission is never carried in.
+3. When the run finishes, its terminal commit — **one transaction** — records
+   the input as one the run answered and settles the queued successor with
+   `terminalReason: 'absorbed'` and `absorbedIntoRunId` naming the run that
+   answered it. Every ticket for that successor resolves to the same answer.
+
+Nothing durable happens between 1 and 3, and that is the design (→ ADR 0113).
+A run that crashes, is closed, or is interrupted after taking an input on
+commits no absorption at all, so what is left behind is an ordinary queued
+successor — the state every other policy already produces and recovery already
+handles. **There is no ordering in which an accepted input becomes
+unanswerable.** Only a run that *completes* may absorb; an interrupted one took
+the input into its prompt and then stopped, and does not get to say it answered
+it.
+
+An absorbed run has **no assistant message of its own** — it produced none, and
+writing an empty one would be a record claiming otherwise. Its answer is
+reachable through `absorbedIntoRunId`, and the store follows that pointer itself
+when a submission arrives on the absorbed run's idempotency key, so a retry
+after a restart returns the answer rather than an empty terminal record.
+
+It does publish one more `run-state` event, carrying `'superseded'`. It never
+enters the run executor, so that event is the only thing that tells a delivery
+surface following its `runId` that it is no longer queued.
+
+With `coalescePending`, one successor can carry several inputs, and an
+absorption covers a successor **whole or not at all** — a partial one would
+leave a terminal run with inputs nobody answered. Inputs that coalesce before
+the absorbing run's last step boundary join the same absorption. One that
+arrives after it cancels the absorption: the successor then answers all of its
+inputs itself, and the absorbing run has answered one of them too. A duplicate
+answer, never a missing one.
+
+(0.63.0 shipped a version of this that committed the absorption at the step
+boundary, before the answer existed, and it was withdrawn in 0.65.0. ADR 0113
+records what that ordering broke.)
+
+With `runs.coalescePending: true`, an active lane has at most one queued
+successor. Every later accepted input is atomically appended to that successor;
+its `AgentRun.inputMessageIds` records the whole batch and every input ticket
+resolves to the same terminal run. Coalescing never mutates the active run.
+
+`AbortSignal.aborted` is only a cooperation request. A successor does not begin
+while the predecessor still owns managed callbacks. A hung predecessor blocks
+the lane in the first version.
+
+Shutdown is two-phase, and both budgets carry the names they carry everywhere
+else in Stitchkit:
 
-- **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).
+```ts
+const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+if (!closed.settled) {
+  console.warn(`exiting with ${closed.remaining} run(s) still in flight`)
+}
+```
 
-### Reconciling with the provider's own accounting
+`close` first rejects new process-local admissions and gives active runs
+`gracePeriodMs` to finish on their own. Only after that budget expires does it
+abort them with reason `shutdown`; `forceTimeoutMs` then bounds the settlement
+wait for a non-cooperative model or tool, measured from the abort — the two
+budgets add up rather than overlapping.
+
+**`close()` reports what it achieved rather than promising an outcome it cannot
+reach.** The result is `{ settled, timedOut, remaining }`: `settled` when every
+in-flight run finished, `timedOut` with a `remaining` count when the force
+budget expired first. There is no combination of budgets that is both bounded
+and guaranteed to leave nothing in flight — that is the trade the budgets exist
+to make, and the result is where you read which side of it you got:
+
+| budgets | behaviour | can return with a run in flight |
+|---------|-----------|---------------------------------|
+| neither | aborts immediately, waits for settlement | no — unbounded wait |
+| `gracePeriodMs` only | waits, aborts, then waits for settlement | no — unbounded wait |
+| `forceTimeoutMs` only | aborts immediately, waits at most that long | **yes** — `timedOut` |
+| both | waits, aborts, waits at most that long | **yes** — `timedOut` |
+
+A caller that wants the old shape still writes `await runtime.close(…)` and
+ignores the result. A caller deciding whether to exit the process reads it.
+Durably queued records rejected from the local queue remain recoverable through
+`scanRecoverable`; close never marks them terminal on its own.
+
+Use `await runtime.interrupt({ conversationId, runId })` when the interruption
+must be durable: it first commits `interrupt_requested`, then aborts the local
+coordinator signal. If provider completion races that revision change, the terminal path reloads
+the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
+`interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
+remain retriable while the run is active with the same owner and fencing token. A stale owner or
+fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the
+**delivery** `terminal` event — a loser settles from canonical state without republishing the turn,
+and its `AgentRuntimeResult.metrics` is `undefined`. The **operator** `run-terminal` event is not
+gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its
+own usage. The two channels answer to different readers — delivering a turn twice is a user's
+problem, and omitting a run's cost is an operator's.
+`runtime.stop(key)` is the process-local signal-only escape hatch.
+
+When an operator has positive evidence that another process owning one known
+run is gone, close that run through the runtime boundary rather than updating
+an adapter table or JSON payload directly:
 
-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.
+```ts
+await runtime.abandon({
+  conversationId,
+  runId,
+  expectedRevision: run.revision,
+  staleOwner: true,
+})
+```
 
-The join is yours, and `runId` is the key:
+The revision protects against stale operator evidence. The mutation updates the
+canonical run and failed assistant atomically, removes the run from recovery
+indexes, and publishes the resulting `run-state`. A run that moved since it was
+read returns a conflict; `staleOwner: true` is mandatory evidence, not a default.
+
+The same evidence holds inside one process when a store failure outlives the
+run's own handling. A store call around execution that throws is retried for
+about half a second, then decided by where the run stood. Retries bound a call
+that fails, not one that hangs, so give the store its own timeouts:
+
+| Failure | Outcome of `result` |
+|---|---|
+| reading or acquiring the run, retries spent, or a lost reply to the acquisition | resolves with reason `abandoned`, the cause on the operator's `run-terminal` |
+| the first assistant draft | resolves with reason `runtime_failure`, like a checkpoint later in the turn |
+| a conflict on a run another executor holds | rejects with the conflict; the record stays that executor's |
+| a conflict on a run still queued, behind another run | rejects with `AgentRunUnsettledError`; `recover()` or `resume` picks it up |
+| the terminal commit, or closing the run, retries spent | rejects with `AgentRunUnsettledError` |
+
+`AgentRunUnsettledError.run` is the record as last read, and the store may be ahead
+of it. Nothing in this process executes that run, and later turns of its
+conversation wait behind it. `recover()` skips a `running` run with a live owner, so
+a long-running process closes it itself once the store answers. Read the record
+first: with no owner or with `error.ownerId` it is this runtime's, and any other
+owner is executing it.
 
 ```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',
+const settled = await ticket.result.catch(async (error) => {
+  if (!(error instanceof AgentRunUnsettledError)) throw error
+  const { conversationId, id: runId } = error.run
+  const current = await store.loadRun({ conversationId, runId })
+  if (current && [undefined, error.ownerId].includes(current.run.ownerId)) {
+    await runtime.abandon({
+      conversationId,
+      runId,
+      expectedRevision: current.run.revision,
+      staleOwner: true,
+    })
+  }
+  throw error
 })
+```
+
+A `queued` run lost to a run ahead of it, and `runtime.resume()` can run it instead
+once that one ends.
+
+## Store operations
+
+`AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
+implement the smaller `AgentRuntimeStoreDriver` rather than these eleven members:
+
+- `acceptInputAndAssignRun`
+- `acquireRun`
+- `checkpointRunAssistant`
+- `requestRunInterrupt`
+- `recoverRun`
+- `commitRunTerminal`
+- `replaceCompactedRange`
+- `loadSnapshot` — the whole conversation; see **Reading a conversation** below
+- `loadRun` — one run by id, with the answer it produced if it has ended
+- `listActiveRuns` — the runs of one conversation that have not ended
+- `scanRecoverable` — one **bounded page** of recoverable runs; `recover()`
+  calls this and nothing else, so an adapter that implements the interface has
+  everything recovery needs
+
+### Writing history no run owns
+
+`seedConversationInput` writes messages no run owns, exactly once per `seedKey`; the key is
+recorded beside the history, so compaction or replacement of the messages never brings them
+back. It places them by `placement`:
+
+- absent or `'lead'` — committed user instructions ahead of the whole conversation;
+- `'after-settled'` — an exchange that already happened without a model (a confirmed voice
+  command and its receipt): committed `user` and completed `assistant` messages. They land after
+  the settled history and ahead of the first message of any run still active, so an active run's
+  input and answer stay adjacent and the next run reads the exchange before the input queued
+  behind it. With no active run they are the tail.
 
-// later — the provider's accounting names the same generation
-await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```ts
+await store.seedConversationInput({
+  conversationId,
+  seedKey: `voice:${commandId}`,
+  placement: 'after-settled',
+  inputs: [ownerMessage, receiptMessage],
+})
 ```
 
-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 pair is ordinary history: it is in `loadSnapshot`, compaction may summarize it, and the next
+provider request carries it. No model is called and no run is created.
+
+### Reading a conversation
+
+Two shapes of read, and the difference matters as a conversation grows.
+
+**Bounded.** `loadRun` and `listActiveRuns` read run records and the
+conversation head. Neither touches history, so neither grows with the length of
+the conversation. `loadRun` is how you resolve the `runId` that
+`submit().admission` hands back — it returns the run, the version it was read
+at, and, once the run is terminal, the answer it produced.
+
+**Unbounded.** `loadSnapshot` returns every message and every run, and so does
+every mutation result: the store's reducer validates its invariants against the
+whole conversation, and the runtime builds the next prompt from the snapshot the
+mutation returns. Ask for it when you need the conversation — composing a
+prompt, or compacting — and not to look one run up.
+
+So the cost of a run scales with the length of its conversation, not with the
+length of the turn. **Configure compaction** (see below) for anything
+long-running: it is the only thing in the framework that makes a conversation
+smaller, and without it a year-old assistant thread is read in full on every
+turn. This is a known limit, held deliberately rather than by omission — paged
+history would have to change what a snapshot *is*, and the store's invariants
+with it, and that is a decision on its own (→ ADR 0112).
+
+Every mutation carries an expected run revision or snapshot version. Input
+assignment additionally carries an idempotency identity. A conflict is a
+control outcome; stale data is never silently overwritten.
+
+Acquisition increments an optional monotonic `fencingToken`. The managed runtime carries it through
+checkpoint/terminal CAS and tool context, so a distributed adapter can reject an old owner even if
+an owner label is reused. Lease expiry and renewal remain application-owned.
+
+On startup, `runtime.recover({ resolveContext })` consumes bounded lightweight
+pages, then restores each conversation's durable execution order before any run
+acquires. Persisted `executionSequence` orders work that started; queued
+`interrupt-next` work precedes ordinary queued work with FIFO preserved inside
+each class. Scan identifiers, equal timestamps and page boundaries therefore
+never become queue order. Its safe default resumes queued runs and reports acquired or
+`interrupt_requested` runs as skipped. A policy may requeue acquired work only
+with explicit replay-safe evidence, or abandon it only with stale-owner
+evidence. Each attempted run returns its own outcome/error; a `resumed` or
+`requeued` outcome also exposes the terminal `result` promise. The outcome is
+reported only after durable acquisition, so a lost acquisition is `failed`
+rather than a successful-looking handoff. `pageSize`, `maxRuns`, and `signal`
+bound the pass. `runtime.resume(...)` remains available for one known queued
+record; its `accepted` promise likewise means that the recovered run acquired
+durable ownership, while `result` carries terminal completion.
+
+Canonical records currently write `schemaVersion: 1`. A durable adapter owns
+read-time migration of older rows: migrate to the current shape at its storage
+boundary, validate with the exported schema, and write only the current
+version. Core deliberately does not guess an application's database migration
+or silently accept an unknown future version.
+
+### Purging a conversation
 
-The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
-outbox.
+```ts
+import { purgeAgentConversation } from 'stitchkit/agent-runtime';
 
-## Deterministic race and adapter proof
+const result = await purgeAgentConversation(store, {
+  conversationId,
+  expectedVersion: snapshot.version, // optional stale-intent protection
+});
+```
 
-`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.
+The optional `AgentRuntimeStore.purgeConversation` capability is implemented by the memory and
+initialized Bun/Node SQLite stores. The helper returns `unsupported` for stores without it; it
+never pretends deletion succeeded. Other outcomes are `purged`, `already_purged`,
+`active` (with `runIds`), or `conflict` (with `actualVersion`). Storage failures reject.
+
+Purge refuses queued, running and interrupt-requested runs. It does not interrupt, force-abandon
+or wait for a provider. Authorize the destructive request in the host, close its conversation
+ingress/attachments, then settle runs through normal interruption or explicitly justified recovery.
+Retry purge after they are terminal. An optional expected version must match the current snapshot;
+a version conflict requires a fresh deletion decision, not blind retry with a new version.
+
+Successful purge atomically removes messages (including compacted inactive rows), all runs and
+retained terminal assistants, admissions/idempotency receipts, conversation heads and their owned
+indexes. It retains only a permanent conversation-ID tombstone. Purging an unknown ID reserves it
+as well, so a submit paused before admission cannot create it later. Repeating the call returns
+`already_purged`, regardless of the original expected version. A lost response is safely retried
+with the same ID; **new chats require a new ID**.
+
+Every later runtime mutation rejects with `AgentConversationPurgedError`, including fresh and
+duplicate admissions, checkpoints, recovery and compaction. Existing controller leases grant no
+exception. Existing reads return empty snapshots, absent runs and empty message pages; purged
+conversations disappear from the SQLite catalog and recovery scans. Snapshots retain their
+existing empty `version: 0` shape; use the purge result, not an empty snapshot, as deletion evidence.
+
+SQLite commits the tombstone and all deletions in one `BEGIN IMMEDIATE` transaction. Failure before
+commit rolls everything back; reopen/recovery cannot restore committed deleted records. Same-thread
+connection contention rejects promptly without effects; retry after the competing operation settles.
+Initialization adds the tombstone table and write guards to schema v1 transactionally, without
+changing application tables or `user_version`. Guards also fence older writers. `initialize: false`
+on an original v1 database does not add purge capability; open an initialized writer first.
+
+Consumer-owned model selections, projections, attachment files, delivery/outbox records and event
+logs remain outside this boundary. Retain an authorized cleanup intent plus any needed opaque file
+references in consumer storage, purge first, then retry idempotent consumer cleanup. Invalidate local
+caches/subscriptions so an old delivered event cannot repopulate a UI. The library never traverses
+paths, revokes remote artifacts or claims a cross-store transaction. Nor does logical purge securely
+wipe database free pages, WAL or backups. Memory tombstones last only for that store instance.
+
+Custom normalized drivers may opt in through `AgentConversationPurgeDriver` on `driver.conversations`.
+Their transaction must serialize `isPurged`, head/active-run checks, `remove`, and **all** mutations
+for the same ID, including absent-ID admission. An optimistic head CAS alone is insufficient. `remove`
+must delete every owned payload/index and preserve the tombstone; errors must roll back the entire
+transaction. Drivers without this guarantee must leave the capability absent. See ADR 0138.
+
+## Events and reconnect
+
+A subscriber that switches over `event.type` handles one transient event
+beyond deltas and reasoning: `attempt-reset`, published when `loop.retry`
+starts a new attempt, meaning everything this run streamed before it is
+withdrawn. `reduceAgentControlEvent` does that; a hand-written reducer must,
+or it keeps the failed attempt's partial text on screen.
+
+`publish` receives event classes with different guarantees:
+
+- `admission` follows a successful acceptance CAS and carries the same complete
+  projection as `ticket.admission`;
+
+- `assistant-delta` is transient and ordered by
+  `(runId, runtimeEpoch, sequence)`;
+- `reasoning-start`, `reasoning-delta` and `reasoning-end` are transient and
+  ordered by the same identity; delta carries only the current text fragment,
+  while provider metadata stays inside a validated canonical envelope;
+- `assistant-checkpoint` follows a successful checkpoint CAS;
+- `run-state` follows durable queue/acquire/interrupt transitions;
+- `run-operation` follows a successful operation CAS. Its `operation` is the
+  durable `AgentRun.lastOperation`: `model-request` or `compaction`, with
+  `started`, `first-output`, `completed`, `failed` or `cancelled` phase and the
+  original timestamps. Concrete models use SDK call identity in an awaited model
+  middleware; global provider IDs use a runtime-generated identity during awaited
+  step preparation. Both durably admit the request before entering `doStream`, so a failed
+  write prevents the provider call. This does not claim HTTP transmission is
+  measured. First output is a
+  non-empty text/reasoning/tool-argument delta or complete tool call; metadata,
+  usage, files and sources do not count;
+- `tool-status` is transient lifecycle presentation with JSON-safe input on
+  start and output on completion. A mounted typed failure carries the same safe
+  `{ error, retryable, details?, _hint? }` envelope as the durable result; an unknown
+  internal cause remains generic and stays in local observability only;
+- `tool-progress` is transient: what a running tool handler reported through
+  `ctx.reportProgress` — `message`, `progress` and `total`, the fields an MCP host
+  receives — with the call's `callId` and `toolName`. It never enters the
+  model's input or the durable history. A message longer than
+  `AGENT_TOOL_PROGRESS_MESSAGE_MAX` (280) is cut, reports of one call closer
+  than 250 ms apart are dropped, and a report after the call's terminal
+  `tool-status` or after its attempt was abandoned is dropped; the terminal
+  status carries the final word. `reduceAgentControlEvent` keeps the last
+  report of each running call in `transientByRun[runId].tools[callId]` and
+  removes it on that call's `completed`, `failed` or `interrupted`. The runtime
+  hands its reporter to a call through the SDK tool context, beside its step
+  ledger; a tool that declares its own `contextSchema` keeps that contract and
+  reports nowhere;
+- `terminal` follows the winning terminal CAS.
+
+`loop.checkpointEveryEvents` batches ordinary stream parts (default `20`) and
+does not batch live event delivery. Tool call/result/error/denial, approval
+request/response and step-finish boundaries force an assistant checkpoint and
+reset that batch. The checkpoint is awaited after the managed loop observes the
+normalized boundary. It does **not** promise persistence before a tool side
+effect: tool fencing supplies the real ownership checks around execution, while
+cross-crash effect idempotency stays application-owned. The following model
+step waits for the previous step-finish checkpoint before its own durable
+request admission and provider invocation. → ADR 0174.
+
+`compaction` names invocation of the configured callback, including a
+`not_needed` context-budget check; it does not by itself say that history was
+summarized. Operation timestamps are retained wall-clock observations and may
+move backwards after a clock correction. Do not subtract them for duration;
+phase order comes from durable snapshot versions/event order.
+
+These are post-commit notifications, not a transactional outbox: a process can
+crash between the database commit and `publish`. Reconnect should load canonical
+state. Exactly-once external delivery remains an application-owned outbox.
+
+### External channel ingress and delivery
+
+The executable
+[`external-channel-harness.ts`](../../packages/core/examples/agent-runtime/external-channel-harness.ts)
+is the reference composition for webhooks, polling transports and local-device
+adapters. Its generic boundary injects a runtime, durable store and delivery
+adapter; the optional
+[`external-channel-grammy.ts`](../../packages/core/examples/agent-runtime/external-channel-grammy.ts)
+attaches the same ingress function to grammY polling or webhook lifecycle
+without putting provider types in the agent runtime.
+
+Inbound update identity, principal resolution, conversation mapping and reply
+target are application policy. Persist and deduplicate the update before
+`runtime.submit`, use the stored idempotency key on crash recovery, then persist
+the admitted `runId`. A duplicate arriving after restart resolves to that same
+mapping instead of creating another model turn.
+
+For output, choose `terminal-only` or `streaming` explicitly. Stable durable
+`eventId` values and transient `(runtimeEpoch, sequence)` identities become
+outbox keys; the application store assigns causal ordinals. A bounded channel
+is only a process-local wakeup and never the durable authority. Before sending,
+persist one of these states:
+
+| State | Recovery action |
+| --- | --- |
+| `not-dispatched` | may dispatch once |
+| `possibly-dispatched` | reconcile with the adapter or remain unresolved |
+| `acknowledged` | deduplicate; delivery is complete |
+
+The agent `terminal` event and the adapter's delivery receipt are intentionally
+different records. A successful run does not prove that a reply reached its
+channel, and a delivery failure never rewrites the canonical agent result.
+Shutdown stops ingress, drains accepted process-local work and leaves ambiguous
+outbox records visible for a later reconciliation pass. Stitchkit does not own
+a channel database, durable broker, provider payload schema or application
+identity policy.
+
+Durable event IDs are derived from run, event type and snapshot version. Use
+`advanceAgentRuntimeEventCursor` to classify delivery.
+
+**`gap` is reported for transient events only**, where `sequence` is a per-run
+counter the runtime really does increment once per event. Durable events carry
+the *conversation's* version, which advances on every mutation including the many
+that publish nothing — checkpoints, compaction, an acceptance that has not
+started — so two consecutive durable events are routinely several versions apart
+and adjacency says nothing. A durable loss is not detectable from the cursor;
+reload on reconnect, which is what a bounded fire-and-forget sink asks of you
+anyway. `createAgentRuntimeEventSink` adds a bounded failure-isolated lifecycle and typed
+projection/redaction hook. `onPublishError` records direct publisher failures without changing the
+already committed run.
+
+A named custom stop condition terminalizes with `policy_stop`; its `policyName`
+is persisted on the run and included in the terminal event/result. `max-steps`
+is the reserved built-in policy name. `loop.prepareStep` is the controlled AI
+SDK step boundary for changing active tools, model, instructions or messages.
+It cannot replace the managed tool set or bypass its lifecycle fence.
+
+Context can grow between steps as tool results and deferred schemas enter the
+provider prompt. When application budgeting can prove that the next assembled
+step exceeds the selected model window, refuse it by type before that provider
+call:
 
-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.
+```ts
+prepareStep: (step) => {
+  if (wouldExceedSelectedModelWindow(step)) {
+    throw new AgentContextOverflowError('Prepared step exceeds the selected model window')
+  }
+  return chooseProductStepOptions(step)
+}
+```
 
-## Plain completions and shared invocation receipts
+That deliberate refusal ends the run as `context_overflow` on the durable
+record, delivery terminal and operator event. Stitchkit does not inspect error
+messages — it recognises failures by identity, not by text. A store refusing an
+owned mutation ends the run `storage_conflict`; `protocol.acceptTerminal`
+refusing a finished message ends it `output_rejected`; a check the SDK runs on
+what this runtime handed it ends it `runtime_failure`. Every error the runtime
+cannot identify as its own remains `provider_failure`, and operator-only
+observability retains its original cause in all of them.
 
-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.
+Completion validity belongs to the protocol and is checked before the terminal
+CAS. Protocols that require a visible answer opt in explicitly:
 
 ```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 protocol = defineAgentProtocol({
+  context: ContextSchema,
+  inputMetadata: InputMetadataSchema,
+  terminalAcceptance: 'require-output',
+})
+```
 
-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',
+The built-in rule accepts non-blank text, generated files, structured provider
+parts, and a named tool-only `policy_stop`. The default is `allow-empty` for
+protocols where an empty acknowledgement is meaningful. Pass a callback when
+the product has a narrower definition; it receives the candidate message,
+terminal reason and optional policy name, and runs before persistence. A false
+result fails the candidate instead of rewriting an already committed success.
+
+`loop.idleTimeoutMs` measures provider silence. It starts immediately before the
+provider call, resets on stream activity, and pauses while local tools execute.
+Resource preparation, child waits and approval waiting do not spend this budget.
+The host gives tools their own deadlines. A stalled provider still aborts with
+durable reason `timeout`; caller interruption and shutdown reach tools directly.
+
+Reconnect loads the durable snapshot. Missing transient deltas do not mean the
+canonical result was lost. Exactly-once external delivery requires the
+application's transactional outbox or stable-ID deduplication.
+
+## Managed tools
+
+Durable `step` bodies return lossless JSON: finite numbers (excluding negative zero),
+strings, booleans, null, dense arrays and plain data objects. Return `null` explicitly
+for effect-only bodies and convert Date values to strings. Unsupported values are
+refused after the body, so external effects still require idempotency. First results
+and replay are detached snapshots; mutating a returned object cannot rewrite a record.
+The optional [sandbox coding profile](sandbox.md#coding-tool-integration) reuses the
+same tool mounting, authorization and output handling for namespace-backed commands.
+
+Always compose `toolFenceLifecycle` into `mountAgent`. It checks ownership
+before a managed side effect and again before accepting its result. Fence loss
+uses an internal control signal: it stops the old loop and is not sent to the
+model as a tool error.
+
+`mountAgent` sends failed runner outcomes through the AI SDK's tool-error
+channel. AgentRuntime persists them with `outcome: 'error'`, publishes the same
+safe envelope, and replays them as an error result on later turns. Classification
+comes from the execution channel, never from inspecting output fields: a valid
+successful result such as `{ error: 'domain value' }` remains successful. Typed
+`AppError` codes and safe details may reach the model; arbitrary thrown causes
+are retained for local hooks and reduced to `INTERNAL_SERVER_ERROR` outside.
+
+The framework cannot undo an already-started non-cooperative external effect.
+Pass the stable call/run idempotency identity into business mutations when the
+effect must be replay-safe.
+
+## History, provider metadata and files
+
+`projectAgentHistory` converts canonical engine records into provider-valid AI
+SDK messages and pairs tool calls/results in persisted causal order. Adjacent
+parallel calls stay in one assistant round and their adjacent results stay in
+one tool round; a dependent call after those results starts a new assistant
+round, and trailing final text remains after the last tool result. Provider-required metadata is kept
+in a versioned opaque envelope and omitted from product delivery by default.
+`projectAgentHistoryDetailed` additionally returns one inspectable decision per canonical record;
+leading assistant records, crash drafts and unmatched tool chronology are never silently passed to
+the provider.
+
+`selectAgentHistory` is the non-destructive context-window selector. It removes only whole oldest
+complete turns, protects system/summary, incomplete and configured recent turns, and reports every
+keep/remove reason with measured/estimated/unavailable token provenance. An oversized protected turn
+returns `oversized`; unavailable accounting returns `unavailable` without invented arithmetic.
+
+`ComposedAgentPrompt.instructions` accepts the AI SDK `Instructions` contract.
+Use `adaptInstructions` when a provider needs metadata on the system message:
+
+```ts
+prompt({
+  context,
+  signal,
+  adaptInstructions: (content) => ({
+    role: 'system',
+    content,
+    providerOptions: { openrouter: { cacheControl: { type: 'ephemeral' } } },
   }),
-};
-// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
+})
+```
+
+Attachments and generated files remain application-owned. The runtime only
+stores a reference returned by `persistGeneratedFile`; it never silently puts
+base64 blobs into the neutral history store.
+
+To send a stored attachment back to a multimodal model, configure
+`history.resolveFile`. It maps the neutral file reference to AI SDK file data
+(URL, bytes, provider reference or text). Without a resolver the
+`unresolvedFile` policy applies, and it is **`omit`** by default: the file part
+simply does not reach the provider. Choose `text` for a describing placeholder —
+the filename or media type, never the storage reference, because that string is
+an address inside your infrastructure and this content travels upstream — or
+`error` to fail loudly. The `error` message does name the reference: it is
+thrown into your process, where you are owed the whole story.
+
+## Compaction
+
+`structuredCompaction` summarizes complete provider-valid turn groups outside
+the store lock, then calls `replaceCompactedRange` against the exact snapshot
+version. A concurrent input produces `conflict`; the stale summary is not
+applied. Summary records use the dedicated `summary` role and project to a
+provider system message. The consumer supplies the structured summary schema
+and prompt. Pass `previousSummary` for a direct call, or configure
+`readPreviousSummary` for runtime-managed compaction, to merge and atomically
+replace a leading summary on the next compaction.
+Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
+eligible range and recomputes the summary; the stale summary is never retried.
+
+### Recovering a prefix after a failed turn
+
+The default evidence policy omits failed assistants. A failed turn therefore stops the
+compactable prefix, including completed turns after it. A terminal failure is not an
+unanswered tool call, but opting its partial evidence into a summary is an explicit host
+decision. Use the existing `evidencePolicy: { failedAssistant: 'assistant-marked' }` on
+`structuredCompaction` (or `selectCompactableHistory`) when that evidence is wanted.
+The same policy belongs on the summarizer's history projection and on any corresponding
+token-budget selection. Stored statuses remain unchanged.
+
+The summarizer receives **raw** `eligibleMessages`, not provider messages and not an
+automatic failure marker. Project them with the same policy before sending them to a
+model, and preserve failed outcomes in the application's structured summary and prompt:
+
+```ts
+const evidencePolicy: AgentHistoryEvidencePolicy = {
+  failedAssistant: 'assistant-marked',
+}
+
+// Inside structuredCompaction({ evidencePolicy, ... }).summarize:
+const projected = await projectAgentHistoryDetailed(eligibleMessages, {
+  evidencePolicy,
+  incompleteToolTurn: 'error',
+})
+const failedMessageIds = eligibleMessages
+  .filter(message => message.role === 'assistant' && message.status === 'failed')
+  .map(message => message.id)
+// Pass projected.messages, projected.system and failedMessageIds to the host's
+// summarizer. Its schema/prompt must retain failures and uncertain effects as
+// such, merge previousSummary, and never describe partial output as success.
+```
 
-const page = await invocations.read({
-  conversationId: 'evaluation-42', limit: 100,
-}, authenticatedContext);
-// Continue with fromSeq: page.nextSeq while it is defined.
+An opted-in failed assistant projects an explicit non-success marker even when it has
+no text or only control parts. A dangling call, unresolved approval, invalid result
+chronology or a user input with no assistant remains a barrier under either policy.
+Raw whole-turn completeness does not guarantee that every record can be projected:
+for example, a call and its result split across records may be rejected by the projector.
+`incompleteToolTurn: 'error'` makes that rejection stop summarization; the original history
+stays canonical. A host with such records must use a status-aware summarizer that explicitly
+represents every relevant record, or retain the range. Do not silently summarize an omitted
+exchange, filter the failed record out of the replacement range, rewrite its status or skip
+over an incomplete turn. The replacement remains one contiguous prefix under snapshot CAS.
+
+Provider chronology and external effect authority answer different questions (ADR 0269).
+A matching `tool-result` with `outcome: 'error'` and an application code such as `UNKNOWN`
+closes the provider exchange; it does **not** prove the external effect failed or succeeded.
+Compaction changes the model-history projection, not the canonical event journal or the
+retained terminal admission receipt. The `durability/effect` intent, accepted proof and
+uncertain outcome remain available after compaction and archive restore. A reconstructed
+`createLocalStepDurability` using the original `(conversationId, runId, effectName)` returns
+the accepted proof, reconciles a bare intent, or returns `uncertain` without calling `run`
+again. It does not deduplicate a new run or a newly named effect. Standalone effect callers
+still own the exclusive execution lease; sharing a ledger is not an atomic claim.
+An application-owned receipt outside that journal retains its own recovery rules and must
+not be discarded because a history turn became compactable.
+
+### Compacting without the store
+
+The *selection* inside compaction needs no store, no version and no runtime, so
+it is published on its own as `selectCompactableHistory` — for an application
+that drives the model itself and keeps its own history (→ ADR 0142):
+
+```ts
+import { selectCompactableHistory } from 'stitchkit/agent-runtime'
+
+const { leadingSummary, compactable, retained } = selectCompactableHistory({
+  messages,
+  keepRecentTurns: 3,
+})
+if (compactable.length > 0) {
+  const summary = await summarize(compactable, leadingSummary)
+  messages = [summary, ...retained]     // replace the old summary, never stack one
+}
 ```
 
-`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.
-
-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.
+`compactable` is the oldest **whole complete** turns and `retained` is
+everything the model must still hear; together they are the input, in order. A
+turn holding a tool call whose result never arrived is never eligible, and
+neither is anything after it: half a turn hands the provider a call with no
+result, which most of them refuse outright.
 
-==============================================================================
-# API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
-==============================================================================
+`structuredCompaction` calls this same function, so the published selection and
+the runtime's cannot drift into two behaviours. What it adds is the part that
+does need the store — writing the result back under a version check.
 
-## `stitchkit/agent-runtime`
-
-Server-only optional application runtime. See the
-[agent runtime guide](../guide/agent-runtime.md).
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `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 |
-
-### Durable capability layer
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `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.
+Deciding *when* to compact is yours: `AgentRuntimeRunContext.contextUsage`
+carries the last step's prompt size beside the model's window, and dividing them
+is one line where the threshold is decided. The core does not own that ratio, on
+purpose — see ADR 0142 for what it publishes and what it declines to.