stitchkit 0.122.1 → 0.122.2

package/llms/agent-runtime.txt

@@ -1,4 +1,4 @@
-# stitchkit/agent-runtime — stitchkit docs slice, part 1 of 4
+# stitchkit/agent-runtime — stitchkit docs slice, part 1 of 5
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
@@ -7,8 +7,9 @@
 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)
@@ -168,655 +169,3 @@ A stop policy's `when` receives the steps so far together with the same run cont
 typed by the runtime's `CONTEXT`. A rule that depends on its own run (a receipt bound to the
 run's request, a per-tenant limit) reads it there; it needs no map of its own keyed by `runId`.
 The first policy to return `true` ends the run as `policy_stop` with its `name` as `policyName`.
-
-## 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 asks about each named ancestor and the file,
-outermost first, stopping at the first refusal; discovery rooted at `.` also asks about `.`.
-Thus 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 questions for direct access. Directory decisions happen before descent; file decisions and
-`search_files.include` happen before opening content. Incompatible glob directory prefixes are
-pruned before policy or directory opens. 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. Reads and edits
-stay pinned through authorization; `write_file` plans before it and opens the parent after, because
-the parent it creates does not exist yet. Reads revalidate the pinned file identity;
-writes and patches revalidate the pinned parent identity; search and resource discovery descend
-only through opened directories. Every filesystem tool selects its root capability before operation or path authorization and retains
-that identity if a callback replaces the root path or configured alias. On Linux the ordinary
-command launcher spawns the command with the pinned directory's `/proc` descriptor link as its cwd;
-on macOS it inherits the pinned cwd through an isolated guard — one short-lived guard process per
-command, tens of milliseconds, outside `shellTimeoutMs`, which counts from the command's start. The
-application process never changes cwd. Where
-contained descriptors are unavailable (Windows), `run_command` accepts a cwd whose realpath is
-that same name under the root — a symlink segment refuses there too — and checks the directory's
-identity again immediately before launch, after every host decision.
-A custom sandbox launcher owns atomic cwd capture at its pathname handoff; the SDK refuses a
-changed identity after policy/prepare and immediately before that handoff. A path that changed
-during direct-access authorization refuses with `CONFLICT`.
-A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
-case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
-NUL bytes are refused before either host policy sees a path.
-Reads and edits open file candidates without blocking on special files, then require a regular
-file. A writerless FIFO therefore refuses instead of occupying a filesystem worker. `write_file`
-supplies the exact missing-directory plan as `createsDirectories` to host authorization; the
-descriptor walk may create only those entries. An ancestor that disappears after approval refuses
-with `CONFLICT`, without expanding that plan. 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. It inserts `newText` literally in both single and
-`replaceAll` modes, including JavaScript replacement tokens such as `$$`, `$&`, `` $` `` and `$'`.
-`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 that reached
-comparison. One finite glob automaton matches files and prunes incompatible directory prefixes;
-`glob` also confines its walk to the requested path. A `hint` can explain include filtering or
-pruning, without counting files below unopened directories.
-
-Search processes one file at a time. List, glob and search share directory, entry, serialized-output,
-timeout and cancellation budgets, including canonical spelling checks before path authorization.
-`list_directory` caps raw enumeration at the smaller of `maxListEntries` and `maxSearchEntries`;
-its coverage scope lists symlinks while glob/search skip them. Glob patterns are limited to 4,096
-UTF-16 units. A scoped glob measures depth from its requested base directory. In addition to `maxSearchFiles` (10,000), `maxSearchDepth`
-(32), `maxSearchResults` (100) and `maxReadBytes` (262,144), hosts can configure
-`maxSearchDirectories` (1,000 directory-open attempts, root included), `maxSearchEntries`
-(20,000 entries observed by bounded readers), `maxSearchBytes` (16,777,216 aggregate content
-bytes, including rejected UTF-8), `maxSearchOutputBytes` (65,536 bytes for the entire serialized
-UTF-8 JSON, minimum 1,024) and `searchTimeoutMs` (5,000). An input whose minimum coverage
-envelope cannot fit the output ceiling refuses before filesystem access. Directory readers cap
-enumeration before materialization and sorting; reaching an entry or result ceiling is
-conservatively partial, without reading a lookahead entry or match.
-
-`list_directory`, `glob` and `search_files` return `coverage.complete` and `coverage.reasons`
-to distinguish full empty results from partial work. Glob `resultTruncated` conservatively marks
-the result ceiling even when no extra match was read.
-Coverage names the include/exclusion/symlink scope, directory and entry counters, actual content
-bytes and elapsed milliseconds. Limits, cancellation, denial, unreadable files and oversized
-lines are explicit reasons. `errors` names only a workspace-relative path, operation and safe code;
-`errorsTruncated` and `deniedTruncated` report shortened diagnostics. Excluded directories and
-symlinks are outside the declared search scope. The caller's signal and deadline reach host
-authorization, file reads and traversal; CPU checkpoints and asynchronous races stop further work.
-Late opened handles are closed, while already-running kernel calls may finish later. Directory
-enumeration and glob matching have internal checkpoints; cancellation stops their producer loops.
-Host policy and visitor exceptions propagate to error hooks with their original cause, rather
-than becoming filesystem diagnostics. Diagnostic byte admission is linear and checks the deadline
-even for an empty result.
-
-Regex searches use JavaScript `RegExp` syntax without flags — groups, alternation, classes,
-anchors, `\b`, quantifiers and `(?ims-ims:…)` modifiers — with bounded cost per line. A line
-whose backtracking work (paths × longest path × line length × (number of groups + 1), every
-repetition capped at the line length beyond the iterations it requires) stays within 2^24 steps runs on the native engine, so ordinary `.*` searches over code
-lines keep native speed and the deadline is observed between lines; any other line runs on a
-cached linear automaton, so `(a+)+$` on a long line costs the same as `a+` and the deadline is
-observed inside the line. Backreferences and
-lookaround refuse before I/O; lines over 8,192 UTF-8 bytes are skipped with incomplete coverage.
-Literal queries allow up to 8,192 UTF-16 units and include patterns up to 4,096.
-
-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.
-
-Coding commands compose the shared native execution owner. Artifact retention and UTF-8
-previews remain coding-tool policy; normal leader exit still forcibly stops remaining POSIX
-group members before draining. A structural sandbox launcher uses the same settlement owner
-with a finite output queue. Sandbox shutdown waits for actual owned completion and surfaces
-cleanup refusal rather than treating it as successful teardown.
-
-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. Its `transaction` owns the retry of a
-serialization conflict, wherever the database reports it: on a statement or on
-`COMMIT`, which some clients surface in a different shape. Pass
-`armCommitConflict` to `runAgentStoreConformance` to prove it:
-
-```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.
-
-### Branch or restore with a new identity
-
-Use `store.branchConversation()` to create an independent conversation. `importConversation()`
-restores the original identity and is not a fork. The built-in memory and SQLite stores and
-`createAgentRuntimeStore()` expose branching; a hand-written `AgentRuntimeStore` can advertise this
-optional capability. The host authorizes the caller's source/archive access and destination
-creation before calling this trusted store boundary.
-
-```ts
-const copy = await sqlite.store.branchConversation({
-  requestKey: 'branch-request-1',
-  destinationConversationId: 'new-conversation',
-  source: { kind: 'conversation', conversationId: 'original', throughRunId: 'finished-run' },
-  // Required when selected history has spills: an explicit policy for this destination.
-  artifactAuthorization: { operation: 'read', path: 'approved-destination-workspace' },
-})
-
-const restored = await sqlite.store.branchConversation({
-  requestKey: 'restore-request-1',
-  destinationConversationId: 'restored-as-new',
-  source: { kind: 'archive', bytes: archiveBytes },
-})
-```
-
-`throughRunId` selects its exact terminal/abandon event. Omit it to include the settled tip and
-compaction recorded after the last run. The selected prefix must contain no queued or acquired
-runs. A later active source run does not prevent branching an earlier settled prefix. A migrated
-baseline has no earlier per-run event boundary; it can be copied at its settled tip.
-
-The result is `{ outcome: 'created' | 'duplicate', receipt }`. Keep the receipt: it binds source
-and destination identity, source kind, exact `sourceSeq`/`sourceVersion`, `sourceDigest`, request
-fingerprint and creation time. A retry with the same destination/key and selector returns the
-original receipt even after the source advances or the destination continues. Changing the
-request conflicts; no existing destination is overwritten. Archive fingerprints bind the supplied
-bytes. The source digest binds the selected canonical events, artifacts and reconstructed snapshot.
-Run update timestamps reconstructed from events use their recorded `occurredAt`. Abandon transitions
-retain the full failed assistant in the same event; a legacy archive must retain that exact assistant
-in its runtime snapshot, otherwise copying refuses instead of inventing historical content or time.
-
-No provider or tool runs during copying. The next ordinary runtime `submit` continues the copied
-history. All engine identities and typed references are new, including repeated references to one
-spill. Compacted content stays in the event history and SQLite inactive rows; the model reads the
-same active summaries. A hash-only checkpoint is historical digest evidence, marked
-`sourceSha256`; a later full terminal record must settle its content.
-
-Recorded provider options and canonical reasoning/tool-call provider metadata are retained.
-Provider message hashes and request references remain consistent after rekey. Metadata is
-data, subject to the opaque JSON reference guard: an undocumented runtime reference key
-refuses instead of carrying a source identity into the destination. Unknown message fields
-and malformed request/message digests also refuse before any destination writes.
-
-A branch grants no source authority. Terminal run owners/fences and approval signatures are
-removed. State, schedules, children, retries, sandbox, approval rejection and durability facts are
-retained as inert `runtime/branch-observation` records; they cannot repopulate operational state
-or pending effects. Spills discard source authorization and require the explicit fresh
-`artifactAuthorization`; normal destination read authorization still applies. No cached projection,
-schedule row or child relation is cloned. Ordinary companion projections in the export have
-`{ name, version, uptoSeq, value, updatedAt }` envelopes. Branch validates their envelopes,
-unique names and checkpoints within the supplied journal, then discards their values. They are
-derived application caches, including ones containing source references; their values are never
-replayed as state or copied as authority. Rebuild destination projections with
-`createSqliteAgentProjectionStore().advance(...)` over the destination ledger. An exact earlier
-boundary never inherits a later cache value.
-
-The store validates the complete archive before writing: contiguous events, a matching runtime
-snapshot, known typed forms, reference closure, and spill bytes/digests. Unsupported provider
-envelopes, encrypted invocation payloads, unknown event versions, malformed projection envelopes,
-missing artifacts and undocumented reference fields in opaque JSON refuse atomically. They need
-an owner-defined transfer codec; never recursively rewrite internal JSON in the application.
-Third-party drivers must provide atomic write transactions and archive support for spills;
-`history.restore` is required for migrated baselines with inactive rows.
-
-### 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.
-
-For `runtime/transition` payload inspection, use `AgentStoreTransitionRecordSchema` and its
-inferred `AgentStoreTransitionRecord` type. A checkpoint record may hold either the full assistant
-message or `{ id, status: 'streaming', sha256?, sourceSha256?, parts: number, bytes: number }`;
-exactly one digest is present. Numeric `parts` counts parts; it is not an array of message parts.
-`sourceSha256` preserves a branch's historical source digest. These hash-only records are
-observations, not executable checkpoint inputs. `AgentStoreTransitionSchema` describes full
-store mutations. Shape inspection does not replace branch's complete replay/reference validation.
-Schema v4 archives written by 0.109.4 use the same journal representation.
-
-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.
-Resolve after durable admission; return `{ status: 'retry', reason }` for a
-transient refusal or `{ status: 'terminal', reason }` to stop the entire schedule in
-`failed` state. Only those two shapes are failures: any other returned value — a
-queue length, a receipt — means the callback returned, so it delivered. Throws retry
-too. `maxAttempts` (default 1000, about sixteen hours at the retry ceiling) bounds
-one occurrence: a one-off schedule then becomes `failed`, a recurring one gives up
-that occurrence (`schedule/failed` with `skipped: true` and the `nextAt` it moves
-to) and keeps its cadence. A failure reason is kept to 1000 characters. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
-capped at 60 seconds and persisted across restart. `retryAt`, `attempts` and `lastError`
-show retry diagnostics; success resets them. `nextAt` and `lateByMs` retain the original
-occurrence time. Recurring schedules fire once after an idle stretch and advance to the
-next future slot on their original cadence.
-
-Dispatch receives an `AbortSignal`, has a 30-second deadline and holds a unique
-60-second lease. A late or cancelled attempt cannot settle or emit firing events.
-Honor the signal and durably deduplicate the key: a crash after admission but before
-settlement can replay delivery. This is at-least-once, not exactly-once.
-Due selection is indexed, limited to 32 parallel deliveries per tick; one hung batch
-can delay newly due work by at most its deadline. The service keeps one nearest-due
-timer plus per-attempt deadline timers. Storage failures use a bounded recovery timer;
-idle ticks do not write. SQLite v4 migration preserves due times and claims; stop older
-scheduler processes before migration. See [ADR 0202](../decisions/0202-schedule-retries-preserve-occurrence-identity.md).
-`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.