stitchkit 0.93.0 → 0.94.1

package/llms/agent-runtime.txt

@@ -0,0 +1,893 @@
+# stitchkit/agent-runtime — stitchkit docs slice, part 1 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.2.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)
+==============================================================================
+
+---
+title: "Agent application runtime"
+description: Configure Stitchkit's optional durable history, stream loop, run coordination and managed-tool fencing.
+type: architecture
+status: active
+created: 2026-08-22
+updated: 2026-08-29
+---
+
+# Agent application runtime
+
+> **Maturity: evolving.** This surface is still finding its shape and may be
+> redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
+> and a migration section, never silently. If your application already owns the
+> conversation loop, `mountAgent` from `stitchkit/tools` is the stable path.
+
+`stitchkit/agent-runtime` is the server-only, opinionated layer above
+`mountAgent`. Use it when the application wants Stitchkit to own conversation
+mechanics: durable acceptance, history projection, the AI SDK stream loop,
+checkpoints, keyed interruption, terminal commit and stable application events.
+
+If the application already owns that loop, continue importing `mountAgent` from
+`stitchkit/tools`. `stitchkit/tools` does not depend on this entrypoint at all;
+this entrypoint uses the tool executor from it, but pulls no MCP peer, so
+choosing `mountAgent` alone costs you nothing from here.
+
+UI and shared DTO code must import canonical records and delivery validation from
+`stitchkit/agent-runtime/browser`, not from the server runtime barrel:
+
+```ts
+import {
+  AgentRunSchema,
+  AgentRuntimeEventSchema,
+  advanceAgentRuntimeEventCursor,
+} from 'stitchkit/agent-runtime/browser'
+```
+
+This browser-safe entrypoint re-exports the same schemas and inferred types used
+by the runtime. It intentionally excludes model construction, execution,
+persistence, event sinks and every Node context dependency.
+
+## Install
+
+```sh
+bun add stitchkit ai zod
+```
+
+`mountAgent` from `stitchkit/tools` — used in the composition below — additionally
+needs the MCP peer, which that entrypoint imports statically:
+
+```sh
+bun add @modelcontextprotocol/server
+```
+
+OpenRouter is isolated so other runtime users do not resolve its package:
+
+```sh
+bun add @openrouter/ai-sdk-provider
+```
+
+## Minimal composition
+
+```ts
+import { z } from 'zod'
+import {
+  AgentContextOverflowError,
+  composeAgentPrompt,
+  createAgentRuntime,
+  createMemoryAgentRuntimeStore,
+  defineAgentProtocol,
+  defineModelRegistry,
+} from 'stitchkit/agent-runtime'
+import { openRouterProvider } from 'stitchkit/agent-runtime/openrouter'
+import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'
+
+const protocol = defineAgentProtocol({
+  context: z.object({ userId: z.string() }),
+  inputMetadata: z.object({}),
+})
+
+const models = defineModelRegistry({
+  providers: {
+    openrouter: openRouterProvider({ apiKey: env.OPENROUTER_API_KEY }),
+  },
+  models: {
+    fast: {
+      provider: 'openrouter',
+      modelId: 'provider/model',
+      contextWindow: 128_000,
+      capabilities: ['tools'],
+    },
+  },
+})
+
+const prompt = composeAgentPrompt<{ userId: string }>([
+  {
+    name: 'product',
+    stability: 'stable',
+    render: ({ context }) => `Help user ${context.userId}.`,
+  },
+])
+
+const runtime = createAgentRuntime({
+  protocol,
+  store: createMemoryAgentRuntimeStore(),
+  models: {
+    preflight: () => models.preflight('fast', ['tools']),
+    resolve: () => models.resolve('fast', ['tools']),
+  },
+  prompt: ({ context, signal, model }) =>
+    prompt({
+      context,
+      signal,
+      budget: {
+        contextWindow: model.descriptor.contextWindow,
+        reservedOutput: 8_000,
+        toolSchemas: { provenance: 'unavailable' },
+        attachments: { value: 0, provenance: 'measured' },
+        providerOverhead: { provenance: 'unavailable' },
+      },
+    }),
+  tools: ({ context, toolFenceLifecycle }) =>
+    mountAgent(service, {
+      context,
+      lifecycle: composeToolLifecycle(authLifecycle, toolFenceLifecycle),
+    }),
+  runs: { inputPolicy: 'interrupt', coalescePending: true },
+  loop: {
+    idleTimeoutMs: 60_000,
+    prepareStep: ({ context, steps }) => ({
+      activeTools: steps.some((step) => step.toolCalls.length > 0)
+        ? ['lookup']
+        : ['lookup', 'discover'],
+      instructions: `Current account: ${context.userId}`,
+    }),
+    stopPolicies: [
+      {
+        name: 'repeated-tool-error',
+        when: ({ steps }) => hasRepeatedToolError(steps),
+      },
+    ],
+  },
+})
+
+const ticket = runtime.submit({
+  conversationId: 'conversation-id',
+  idempotencyKey: 'request-id',
+  context: { userId: 'user-id' },
+  parts: [{ type: 'text', text: 'Hello' }],
+  recordIds: {
+    inputMessageId: 'user-message-id',
+    runId: 'run-id',
+    assistantMessageId: 'assistant-message-id',
+  },
+})
+
+const admission = await ticket.admission
+await ticket.accepted
+const terminal = await ticket.result
+```
+
+## Bounded deferred tool catalogs
+
+Use `createDeferredAgentToolSurface` when a measured large catalog makes
+sending every schema on every provider step expensive. The controller mounts
+the complete executable surface in process, but initially advertises only its
+search tool, explicit `alwaysOn` tools and bounded policy pins:
+
+```ts
+import { createDeferredAgentToolSurface } from 'stitchkit/agent-runtime'
+import { composeToolLifecycle } from 'stitchkit/tools'
+
+const deferred = createDeferredAgentToolSurface({
+  surfaces: {
+    member: { services: memberServices, runtimeTools, alwaysOn: ['ask_user'] },
+    broadcast: { services: broadcastServices, runtimeTools },
+  },
+  selectSurface: ({ context }) => context.mode,
+  pins: ({ context }) => context.skillTools,
+  search: {
+    name: 'tool_search',
+    maxQueryBytes: 1_024,
+    maxResults: 8,
+    maxResultBytes: 8_192,
+    select: ({ query, manifest }) => rankCatalog(query, manifest),
+  },
+  activation: {
+    maxSelectedTools: 8,
+    maxActiveTools: 16,
+    maxSchemaBytes: 32_768,
+  },
+  observe: event => recordDeferredToolEvidence(event),
+})
+
+const runtime = createAgentRuntime({
+  // protocol, store, models and prompt...
+  tools: runContext => deferred.mount(runContext, {
+    context: runContext.context,
+    lifecycle: composeToolLifecycle(authLifecycle, runContext.toolFenceLifecycle),
+  }),
+  loop: { prepareStep: deferred.prepareStep(applicationPrepareStep) },
+})
+```
+
+The built-in selector deterministically ranks exact name, prefix/token and
+description matches. A custom async selector returns names only; unknown and
+duplicate output is removed against the local canonical manifest. Search never
+executes the selected operation and never returns its schema. A later provider
+step receives the real selected tools by name, so their direct lifecycle,
+fencing, hooks, errors and `present.agent` output remain unchanged.
+
+Selection is a versioned receipt in the ordinary durable tool-result history.
+The latest valid same-run search replaces the earlier selection; parallel
+searches in one step merge in call order. Recovery reconstructs it, while a
+different run or finite surface cannot inherit it. Known inactive calls take a
+recoverable `SEARCH_REQUIRED` search round; unknown names still fail.
+
+Every ceiling is required. `maxSchemaBytes` measures UTF-8 bytes over canonical
+name, description and presentation schema. It is useful for before/after
+comparison, but provider serialization and tokenization differ: use existing
+provider-reported input usage and cost to decide whether the extra search round
+is beneficial. Controller evidence intentionally omits query text, prompts,
+arguments and application context. → ADR 0129.
+
+### Published headless harness and structured runner
+
+`stitchkit/agent-runtime/harness` publishes the resource-aware composition over
+`createAgentRuntime`. `createHeadlessAgentHarness` accepts the existing protocol and store,
+caller-provided model resolution, bounded instruction/skill/resource loading, direct tools and a
+prompt-budget callback. Resource names are unique; count, UTF-8 bytes and diagnostics are bounded.
+Invalid resources fail before a provider request. Diagnostics are evidence for the caller: their
+observer is isolated, and the loader decides whether a reported condition is fatal.
+
+`createAgentHarnessFileResources` is the optional filesystem implementation. It reads only
+caller-declared absolute roots, refuses symlinks and reports provenance as
+`rootId:relative/path`. Instructions enter the prompt immediately. Skills and ordinary resources
+enter as bounded name/description summaries; `read_resource` loads one exact body later as
+a normal direct typed tool. Custom loaders remain supported unchanged.
+
+Each run may resolve a different provider adapter without changing the harness. The
+`profile-applied` observation records the actual `AgentModelDescriptor`, resource kind/name/
+provenance and sorted direct tool names; it intentionally contains no resource text, prompts,
+arguments or credentials. Observer failure never changes the canonical run outcome.
+
+[`packages/core/examples/agent-runtime/headless-agent-runner.ts`](../../packages/core/examples/agent-runtime/headless-agent-runner.ts)
+is a reference structured control loop for `submit`, `interrupt`, `snapshot` and bounded `close`.
+It starts no process and chooses no framing, authentication or transport. Importing either example
+has no side effect; an external supervisor owns process placement and restart.
+
+| Concern | Public Stitchkit composition | Boundary |
+| --- | --- | --- |
+| execution loop | `createAgentRuntime` | already available; do not copy a second loop |
+| model choice | `defineModelRegistry` and `models.resolve` | provider credentials/discovery stay application-owned |
+| resources | `createHeadlessAgentHarness` → `composeAgentPrompt` | paths, trust, precedence and watching stay application-owned |
+| tools | `mountAgent` + `createAgentToolFenceLifecycle` | auth and domain effects stay application-owned |
+| follow-up | `runs.inputPolicy: 'queue'` | durable FIFO after the current run |
+| interrupt | `interrupt` or `interrupt-next` | `interrupt-next` terminates the active run and gives the new durable admission next priority |
+| recovery | `runtime.recover` + `scanRecoverable` | replay safety and context reconstruction are explicit callbacks |
+| reconnect | canonical snapshot + `advanceAgentMultiSessionCursor` | conversation/run-scoped gaps require resync |
+| persistence | memory reference, public driver, or SQLite leaf | product rows/outbox remain outside the runtime store |
+| executable lifecycle | structured runner example | framing, auth, process placement, restart and OS isolation stay host-owned |
+
+`createAgentHarnessControlServer` adds transport-neutral correlated requests, shared observers and
+one exclusive controller lease per conversation. `close()` on a connection detaches only that
+client; it never closes the harness. Normal `event` delivery stays serialized. A bounded slow
+consumer is detached and receives `resync-required` through the required synchronous
+`onOverflow` callback; that callback closes/aborts the underlying transport, which then reconnects
+and requests a fresh snapshot. It never writes a second frame concurrently with a blocked
+`deliver`. Browser code uses `createAgentControlView`,
+`reduceAgentControlSnapshot` and `reduceAgentControlEvent`; the reducer owns no renderer and marks a
+conversation `resyncRequired` after a transient sequence gap.
+
+Configure `loop.toolApproval` to use the installed AI SDK approval policy and
+`loop.toolApprovalSecret` to sign exact requests. A request is stored on the terminal assistant
+before any effect. `pendingApprovals()` derives unresolved requests from canonical messages;
+`respondToApproval()` writes one tool-role approval response and queues a successor. The SDK
+revalidates the signature/tool call/input before the original direct tool reaches its existing
+fence. Reconnect and SQLite reopen require no promise registry. Remembered policy and a stronger
+cross-crash exactly-once guarantee remain application concerns.
+
+Approval requests suspend a call; they do not settle its result. History carries exact call and
+approval identity across assistant/tool records, so an approved result can precede the next signed
+request in a successor run. Automatic decisions follow the same chronology. Unknown/duplicate
+responses and results with a different call or tool name are invalid; dropping an invalid active
+approval input fails the run with a private diagnostic rather than starting a fresh model turn.
+
+`stitchkit/agent-runtime/coding-tools` returns ordinary direct runtime tools named `read_file`,
+`write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command` and optional
+`read_output`. Every call passes a required host authorization callback. An optional async/sync
+`authorizePath({ path })` is the one operation-independent policy for direct file access and
+discovery: direct read/write/edit refuses a denied path, while listing, glob and search omit it.
+Denial is recursive on every surface — direct access and discovery base paths ask about `.` and each
+ancestor, outermost first, stopping at the first refusal, so denying `credentials` denies everything
+under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
+depth N costs N+1 questions. Directory decisions happen before descent; file decisions and
+`search_files.include` happen before opening content. Requested paths use `/`: a backslash is
+refused rather than normalised, because the workspace walk reads it as a separator and every
+authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
+descriptor-relative resolution: each ancestor is opened without following symlinks and remains
+pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
+writes and patches revalidate the pinned parent identity; search and resource discovery descend
+only through opened directories. Linux traverses `/proc/self/fd`; macOS uses the package's
+architecture-specific Node-API `openat` backend. Unsupported platforms, including FreeBSD until a
+real backend is qualified, fail closed. The package needs no install-time compiler or script.
+Other platforms fail these filesystem operations closed because Node exposes no equivalent
+portable directory-handle-relative API. Writes/edits reject symlink targets, content is strict
+UTF-8 and retained bytes are finite. Shell accepts a finite alias mapped by the host to an absolute executable plus an
+argument array — never a shell command string — and uses only the explicitly supplied environment.
+Arguments, output and time are bounded, while cancellation terminates the child. The configured
+root and cwd are path boundaries, not a security sandbox: isolate the process when an executable
+must not access the rest of the machine. Path admission does not constrain `run_command`; an
+executable requires process isolation for that guarantee. → ADR 0172
+
+An absolute path is still refused. When it is inside the canonical workspace root, the refusal
+includes the exact workspace-relative `recoveryPath`; an absolute path outside the root has no
+suggested replacement. Applying the suggestion still passes the same descriptor-relative
+containment and symlink checks.
+
+`edit_file` replaces one exact snippet. `oldText` is itself the freshness guard for the region it
+changes, so the digest is the optional `expectedSha256` and an edit is one call; pass the digest
+`read_file` returned when you want the whole-file guarantee, and read the `sha256` it returns to
+chain the next edit without re-reading. The read, the occurrence count and the construction of the
+new content all happen inside one per-target lock, so two concurrent edits of different snippets in
+one file cannot each build a file from the same base and have the second erase the first — the lock
+is process-local, which covers many agents in one process and not two processes over one workspace.
+It authorizes the exact replacement count, result digest and byte size, and deliberately does not
+claim multi-file atomicity.
+
+`write_file` creates missing parent directories inside the root and names them in
+`createdDirectories`; the walk that finds them runs before authorization and reports them in the
+authorization payload, so no directory is created before a host approves it.
+
+**Every ordinary outcome is a refusal a model can act on** — a missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is `CONFLICT` carrying its
+occurrence count, a path outside the root is `FORBIDDEN`, an unknown spilled-output reference is
+`SPILL_REFERENCE_UNKNOWN` — each with a `hint` naming the next move.
+Host-level causes stay scrubbed to `INTERNAL_SERVER_ERROR` and name nothing outside the workspace.
+Every refusal code is a member of `STITCH_ERROR_STATUS`, so its status survives an envelope that
+crosses a process boundary and is rebuilt from the wire.
+→ ADR 0139
+
+`list_directory` marks excluded directories rather than hiding them, and `glob` reports
+`skippedDirectories` beside its matches: an empty result from a tree whose files all live under an
+excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
+thing. `search_files` takes `regex`, `context` lines and an anchored `include` pattern matched
+against the whole workspace-relative path. `*` does not cross `/`, so files in subdirectories need
+`**/`; `scannedFiles` counts files admitted by both that filter and host authorization. A `hint`
+explains the zero only when the filter produced it, rejecting every file the scan reached; an empty
+tree and a host refusal return the same empty result without blaming the pattern. Regex is bounded by
+refusing backreferences and lookaround and capping line length rather than by a timeout, because a
+JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
+preview continues into an opaque bounded artifact and `read_output` reads slices without
+exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
+
+`run_command` treats every invocation as finite. `shellTimeoutMs` bounds normal execution and
+`shellTerminationGraceMs` bounds settlement after timeout, caller cancellation, output overflow or
+parent exit. POSIX hosts launch a dedicated process group and kill every descendant remaining in
+that group; a process that deliberately escapes the group is outside the guarantee. Node's
+portable Windows child-process API cannot kill a complete descendant tree without invoking a
+second host executable, so Windows kills the direct child, destroys retained pipes at the grace
+deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
+`cancelled` without spawning.
+
+One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
+concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
+new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;
+construct a new loader to refresh after filesystem changes.
+
+Runtime events preserve reasoning/text/tool lifecycle order. Durable admission,
+checkpoint, run-state and terminal events carry stable identities; transient
+deltas carry one runtime epoch and monotonic sequence. On a transient gap,
+reload the canonical snapshot and resume from the durable record instead of
+persisting deltas as a second history.
+
+Prompt `contextWindow` budgeting is a pre-request decision over the assembled
+context. `AgentRun.usage` is cumulative measured/provider-reported execution
+evidence across attempts and compaction. They answer different questions and
+must not be substituted for each other. TTFT and throughput require timestamps
+from the actual provider stream plus a provider-reported or tokenizer-measured
+token count; character counts cannot produce exact token or throughput figures.
+
+`recordIds` is optional. Supply stable application record IDs when an accepted-response transport must
+return durable placeholders before the run finishes. `ticket.admission` resolves after the store
+acceptance CAS and reports the canonical committed `input`, assigned `run`, a typed `pending`
+assistant projection, compatibility IDs and snapshot version.
+Those assigned IDs can differ from the proposal when an input coalesces into an existing queued
+successor. Reuse the same `inputMessageId` for retries carrying the same idempotency key; input
+identity is caller-stable, while the receipt reports the run/assistant identities that assignment
+may change. Await `admission` first on the immediate accepted-response path. `ticket.accepted`
+remains the signal-only compatibility surface and additionally waits for admission publication.
+
+The in-memory store is a reference adapter and has process-local durability
+only. Production applications normally call `createAgentRuntimeStore()` and
+provide one database transaction driver:
+
+```ts
+const store = createAgentRuntimeStore({
+  transaction: (work, options) =>
+    options?.access === 'read'
+      ? db.readTransaction(tx => work(tx))
+      : db.writeTransaction(tx => work(tx)),
+  head: {
+    load: (tx, conversationId) => loadRuntimeHead(tx, conversationId),
+    compareAndSwap: (tx, operation) => casRuntimeHead(tx, operation),
+  },
+  runs: {
+    load: (tx, identity) => loadRun(tx, identity),
+    loadByAssistantMessageId: (tx, identity) => loadRunByAssistant(tx, identity),
+    loadMany: (tx, identities) => loadRuns(tx, identities),
+    listActive: (tx, conversationId) => listActiveRuns(tx, conversationId),
+    save: (tx, record) => saveRun(tx, record),
+  },
+  admissions: {
+    load: (tx, identity) => loadAdmission(tx, identity),
+    loadByInputMessageId: (tx, identity) => loadAdmissionByInput(tx, identity),
+    create: (tx, receipt) => createAdmission(tx, receipt),
+  },
+  history: {
+    load: (tx, conversationId) => loadCanonicalMessages(tx, conversationId),
+    apply: (tx, mutation) => applyCanonicalHistoryMutation(tx, mutation),
+  },
+  scanRecoverable: page => scanRecoverableRuns(page),
+})
+```
+
+Prompt budgeting keeps reservation deficits signed. If instructions,
+`reservedOutput`, tool schemas, attachments and provider overhead already exceed
+`contextWindow`, `composeAgentPrompt` returns `contextDecision: 'oversized'`
+and a negative `availableHistoryTokens` even when history is empty. A `compact`
+policy is returned only when removing history could actually make the prompt
+fit. Exact equality (including a zero window with zero reservations/history)
+fits; any unavailable component keeps the decision `unavailable`.
+
+The same opaque `tx` reaches head, run, admission and history callbacks. The adapter maps rows
+and supplies atomicity; Stitchkit owns transition validation and revision
+arithmetic. The executable reference is
+[`examples/agent-store-prisma/adapter.ts`](../../examples/agent-store-prisma/adapter.ts).
+`compareAndSwap` returns either `{ outcome: 'applied' }` or
+`{ outcome: 'conflict', actualVersion }`. Decide that outcome by reading the
+version, comparing it and then writing unconditionally — inside the transaction
+the adapter supplies, that is atomic. A conditional upsert is the shorter thing
+to write and it is wrong twice: `ON CONFLICT ... WHERE` guards the update branch
+only, so the first write to a conversation applies whatever `expectedVersion` it
+was given, and the affected-row count that would report the outcome is the
+driver's, which need not be the rows the statement moved. The head contains only
+schema version, conversation identity and monotonic version. Runs and admission receipts are normalized records;
+recovery queries active run states directly instead of maintaining a second projection.
+An admission receipt retains its canonical input, and a terminal run retains its canonical
+assistant, so physical product-history compaction cannot break idempotent retries.
+
+### Built-in SQLite persistence
+
+Use the runtime-specific leaf; the neutral agent runtime never imports either
+SQLite built-in:
+
+```ts
+// Bun
+import { createBunSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/bun'
+
+const sqlite = createBunSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })
+const runtime = createAgentRuntime({ ...config, store: sqlite.store })
+
+await runtime.close()
+await sqlite.close()
+```
+
+```ts
+// Node 22.5+
+import { createNodeSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/node'
+
+const sqlite = createNodeSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })
+```
+
+Initialization creates only `stitchkit_agent_runtime_*` tables and records
+schema version 2 in `stitchkit_agent_runtime_meta`; it does not use
+`PRAGMA user_version` or mutate application tables. An unknown schema version or
+unversioned partial Stitchkit schema is refused. The connection is owned by the
+returned handle and closes only after accepted operations drain.
+
+Each handle serializes its transactions. Separate connections use
+`busy_timeout = 0`: a competing synchronous writer fails promptly with
+SQLite's lock error, so an awaited transaction can resume and commit or roll
+back. Retry that explicit error with an application-owned bounded policy; do
+not configure a blocking busy timeout on the same JavaScript thread.
+
+Aggregate reads and catalog pages use `BEGIN`, so a WAL writer may remain active
+while the reader sees one committed snapshot. Mutations and purge use
+`BEGIN IMMEDIATE`: they reserve the writer slot before reading state for CAS and
+never attempt a deferred read-to-write upgrade. A custom driver may inspect the
+additive `transaction` option `{ access: 'read' }`; ignoring it preserves the
+previous write-safe behavior.
+
+The adapter proves canonical durability across reopen and process restart. It
+does not make external tool effects exactly once, join application projections
+atomically or replace an application outbox. If a product row must commit with
+an agent transition, implement `AgentRuntimeStoreDriver` over the application's
+own transaction boundary instead.
+
+Opening a version 1 store migrates it in one transaction, forward only — back
+the file up first, a 0.85.x package refuses a migrated file. Existing
+normalized state becomes one `runtime/baseline` event per conversation, dated
+when the migration ran and carrying `asOf` for the last message it describes;
+search and projections address that pre-migration history as one snapshot at
+`seq 1`. New transitions continue the monotonic conversation sequence. Version
+2 requires SQLite FTS5 because event search is an advertised capability, so a
+build without FTS5 is a startup error (`requires FTS5 support`) rather than an
+empty search result; check with
+`SELECT sqlite_compileoption_used('ENABLE_FTS5')`.
+
+The handle returned by `createBunSqliteAgentRuntimeStore` /
+`createNodeSqliteAgentRuntimeStore` is `{ store, conversations, database,
+transaction, close }`. `database` is the shared connection and `transaction`
+is one write transaction in the store's own serialization: the SQLite
+companions — `createSqliteAgentProjectionStore`, `createSqliteAgentSpillStore`,
+`createSqliteAgentChildManager`, `createAgentScheduleService` — take `{ sqlite }`
+and write their rows and events through it, so a row and its event land
+together or not at all.
+
+`conversations.messages` pages the model's history: what compaction removed is
+not in it, which is the point of compaction. A person reading back their own
+conversation needs the other view, and asks for it explicitly:
+
+```ts
+const page = await conversations.messages({
+  conversationId,
+  limit: 50,
+  direction: 'after',
+  includeCompacted: true,
+})
+const removed = new Set(page.compacted)
+```
+
+`items` stays one sequence in the order it happened, and `compacted` names the
+ids inside it that the model no longer sees — the boundary is a mark on the
+conversation, not a second list. A compaction summary sits at the position of
+the last message it replaced, so the block reads through and the summary
+arrives after it, where it was written; in the model's history, where every
+replaced message is gone, it occupies the block's place either way. Without
+the flag the page is exactly what it was, `compacted`
+empty. The v1 → v2 migration baseline records the same thing: the whole
+sequence, with `compacted` naming what had been folded away. A file migrated
+by 0.86.0 has a baseline built from the active history only — the messages
+themselves are still in the store and this read reaches them, but that one
+event cannot be rewritten after the fact.
+
+### Retried provider streams
+
+With `loop.retry` set, a provider stream that fails before any tool call in the
+attempt is retried at the step boundary. Subscribers see `attempt-reset` for the
+run before the next attempt's first delta and drop what the failed attempt
+streamed; the durable draft is checkpointed after that output is discarded; an
+input injected into the failed attempt is taken again by the retry; and the
+failed attempt's reported usage stays in the run's spend. Transient events —
+deltas, reasoning, `attempt-reset` — are numbered from 1 per run, counting only
+what was published, so a cursor sees no gap on an ordinary stream.
+
+### Event ledger, projections and durable capabilities
+
+`AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`, canonical
+`exportConversation` and empty-target `importConversation`. Runtime transitions, exact provider
+requests and completed provider response identities enter the same append-only ledger. A
+`provider/response` payload binds `response: { id, provider? }` to its `runId`, retry `attempt` and
+`stepNumber`; `step-finished.response` projects the same object to the operator sink. The optional
+upstream name comes from the model provider's own `resolveResponseProvider` — `openRouterProvider`
+supplies it — so the runtime carries the fact without learning any gateway's metadata key. The normalized
+head/run/message tables remain the fast operational projection.
+
+Use `defineAgentProjection` with `createSqliteAgentProjectionStore` for a
+deterministic versioned fold. Every value reports `uptoSeq`, so a caller can
+distinguish current data from a projection that still has events to consume.
+Changing the projection version folds from sequence one.
+
+The built-ins are `agentSummaryProjection`, `agentUsageProjection` and
+`agentOutlineProjection`; focused card, state-slot and schedule projections are
+also available. `list(projection)` reads all materialized conversation rows in
+one SQLite query instead of reopening their event logs.
+
+Durable state is declared once and injected on every provider request:
+
+```ts
+const goal = defineStateSlot({
+  name: 'goal',
+  schema: z.object({ objective: z.string(), status: z.string() }),
+})
+
+const slots = createAgentStateSlotStore({ store: sqlite.store, definitions: [goal] })
+await slots.set({
+  conversationId,
+  name: 'goal',
+  value: { objective: 'finish migration', status: 'active' },
+  actor: 'human',
+})
+
+const runtime = createAgentRuntime({ ...config, store: sqlite.store, stateSlots: [goal] })
+```
+
+`createAgentStateTools` binds `create_goal`, `update_goal`, `get_goal` and
+`todo_write` to one conversation. Human changes call the same slot store with
+`actor: 'human'`; they remain structured `state/set` facts rather than forged
+chat messages.
+
+`createSqliteAgentSpillStore` persists oversized output separately and records
+its locator, hash and lifecycle in the ledger. `read_output` and
+`search_output` re-run both locator authorization and the originating tool
+authorization before reading bytes. A reference the store does not hold is a
+refusal like any other — `SPILL_REFERENCE_UNKNOWN` / 404, naming the reference
+and pointing at the one the spilling command returned. The lookup is scoped by
+conversation, so a reference belonging to another conversation is absent rather
+than forbidden, and the refusal cannot tell a model that it exists elsewhere. `createSqliteAgentEventSearch` returns the
+exact conversation and event sequence; cross-conversation results are denied
+unless `authorizeConversation` approves each target.
+`createAgentEventSearchTools` supplies `session_search`, `session_trace` and
+`session_event` over the same bounded APIs.
+
+For credential-free failure tests, import `createFaultProviderServer` and
+`createReplayAgentProvider` from `stitchkit/agent-runtime/testing`. Runtime
+`loop.retry` applies an explicit `AgentRetryPolicy`: each decision is recorded
+as `retry/scheduled`, each new attempt as `retry/started`, and an attempt that
+has invoked a tool is never automatically replayed.
+
+`createAgentScheduleService` persists `at`, `after` and `every` input. Repeating
+schedules require an explicit IANA time zone. Dispatch uses a stable
+`schedule:<id>:<occurrence>` idempotency key, and restart lateness is recorded.
+`createAgentScheduleTools` exposes the exact `schedule_after`, `schedule_at`,
+`schedule_every`, `schedule_list` and `schedule_cancel` surface.
+
+`createSqliteAgentChildManager` seeds a child from the parent's ledger through
+an exact sequence, stores the graph, clamps requested limits to a durable parent
+remainder and stops budget overruns at the next step boundary as
+`policy_stop`. That enforcement runs inside the child's own runtime: the host that spawns it gives the child
+`loop.stopPolicies: [agentChildBudgetStopPolicy({ manager, childConversationId })]`, which
+calls `recordStepUsage` at every step boundary; `recordStepUsage` alone measures and decides,
+and reports `enforced: false` when the deciding process holds no handle to stop. Given to `createAgentRuntime` as `children`, the manager stops the parent's children after the parent's terminal is durable — interrupted, cancelled, timed out or shut down; a successful, policy-stopped, superseded or failed parent leaves them to the conversation (ADR 0175 carries the table); without `children` nothing cascades; an unreachable child is recorded
+as `lost`, not misreported as a provider failure.
+`createAgentChildTools` adds `subagent`, `subagent_fork`, `list_agents`,
+`send_message` and `interrupt_agent`; final output stays behind its bounded
+result locator.
+
+## Durable order
+
+`acceptInputAndAssignRun` is one atomic operation. It is followed by ownership
+acquisition, revision-checked assistant checkpoints and one terminal CAS. The
+process-local coordinator releases its lane only after terminal commit.
+
+A queued admission is durable immediately, even if its predecessor is still awaiting ownership
+or its first checkpoint. Snapshots expose causal turn order rather than physical append order:
+the predecessor's assigned input(s) and assistant come before the successor input(s). Execution
+uses the same run boundary, so neither `prompt({ snapshot })` nor default/custom history
+projection can see inputs assigned to a later run. `inject` remains the explicit path that moves
+a successor input into the run already in flight.
+
+```text
+input + queued run → running → execution settled → terminal CAS → successor
+```
+
+## 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:
+
+```ts
+runs: {
+  inputPolicy: (input) =>
+    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
+}
+```
+
+`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.
+
+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`.
+
+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.
+
+### How an interrupted turn reaches the model
+
+An interrupted turn is projected, and says so:
+
+```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]' },
+]}
+```
+
+`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.
+
+| 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 |
+
+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.
+
+`projectAgentHistoryDetailed` reports what reached the provider, including part
+types that no projected content stands for:
+
+```ts
+const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
+// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
+//      omittedParts: ['source', 'provider'] }
+// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
+```
+
+`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:
+
+```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`)
+}
+```
+
+`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:
+
+```ts
+await runtime.abandon({
+  conversationId,
+  runId,
+  expectedRevision: run.revision,
+  staleOwner: true,
+})
+```
+
+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.