stitchkit 0.93.0 → 0.94.1

package/llms/agent-runtime-sqlite-node.txt

@@ -0,0 +1,26 @@
+# stitchkit/agent-runtime/sqlite/node — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/sqlite/node`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/sqlite/node`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/sqlite/node`
+
+Node 22.5+ built-in SQLite persistence. It shares the schema and semantics of
+the Bun leaf but imports only `node:sqlite`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createNodeSqliteAgentRuntimeStore` | function | open an owned Node `DatabaseSync`, initialize/validate schema v2, migrate v1 transactionally and return `{ store, conversations, database, transaction, close }` |
+| `NodeSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional read-only and initialization policies; read-only requires an initialized schema |
+| `createSqliteAgentRuntimeStore` / `initializeAgentRuntimeSqlite` | function | shared normalized adapter and namespaced schema lifecycle |
+| `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` / `SqliteStoreTransaction` | _type_ | durable store handle — `store`, `conversations`, `database`, `transaction`, `close` — owned connection lifecycle, initialization policy, and the one write transaction the SQLite companions share |

package/llms/agent-runtime-testing.txt

@@ -0,0 +1,30 @@
+# stitchkit/agent-runtime/testing — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/testing`
+
+Credential-free provider and concurrency fixtures for Bun and Node tests.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createFaultProviderServer` | function | start an OpenAI-compatible local SSE endpoint with deterministic pass, connection-refused, timeout, stream-cut, HTTP, malformed JSON, slow-stream and missing-usage steps |
+| `AgentFaultStepSchema` / `AgentFaultStep` | schema / _type_ | strict fault-plan step vocabulary |
+| `defineAgentFaultPlan` | function | validate a non-empty deterministic fault sequence |
+| `createReplayAgentProvider` | function | serve a declared sequence of credential-free language-model fixtures per model ID |
+| `createAgentRaceBarrier` / `AgentRaceBarrier` | function / _type_ | named bounded deterministic concurrency barrier |
+| `createAgentRaceTrace` / `AgentRaceTrace` / `AgentRaceTraceEntry` | function / _type_ | record and assert exact event order without wall-clock guesses |
+| `createAgentRaceDriver` / `AgentRaceDriver` | function / _type_ | collect named barriers and release their teardown together |
+| `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
+| `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
+| `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |

package/llms/agent-runtime.2.txt

@@ -0,0 +1,550 @@
+# stitchkit/agent-runtime — stitchkit docs slice, part 2 of 3
+
+> 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.3.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`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
+==============================================================================
+
+## 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
+
+### 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
+
+```ts
+import { purgeAgentConversation } from 'stitchkit/agent-runtime';
+
+const result = await purgeAgentConversation(store, {
+  conversationId,
+  expectedVersion: snapshot.version, // optional stale-intent protection
+});
+```
+
+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;
+- `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:
+
+```ts
+prepareStep: (step) => {
+  if (wouldExceedSelectedModelWindow(step)) {
+    throw new AgentContextOverflowError('Prepared step exceeds the selected model window')
+  }
+  return chooseProductStepOptions(step)
+}
+```
+
+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.
+
+Completion validity belongs to the protocol and is checked before the terminal
+CAS. Protocols that require a visible answer opt in explicitly:
+
+```ts
+const protocol = defineAgentProtocol({
+  context: ContextSchema,
+  inputMetadata: InputMetadataSchema,
+  terminalAcceptance: 'require-output',
+})
+```
+
+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' } } },
+  }),
+})
+```
+
+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.
+
+### 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
+}
+```
+
+`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.
+
+`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.
+
+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.
+
+## Observability
+
+`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.
+
+### What a run says it spent
+
+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.
+
+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.