stitchkit 0.88.0 → 0.90.0

package/llms-full.txt

@@ -48,13 +48,14 @@ own, recorded as an ADR.
 |--------|--------|----------|-------|
 | `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
-| `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract, projected onto the realtime contract |
+| `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
+| `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
@@ -63,11 +64,12 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 33 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 35 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 19 of the 33 minors since 0.56.2, most recently 0.88.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 35 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults and deterministic race controls |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
@@ -76,7 +78,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 33 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 35 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -5583,9 +5585,11 @@ the product has a narrower definition; it receives the candidate message,
 terminal reason and optional policy name, and runs before persistence. A false
 result fails the candidate instead of rewriting an already committed success.
 
-`loop.idleTimeoutMs` is inactivity, not total duration: the deadline resets on
-every model stream event. A stalled call aborts with durable reason `timeout`;
-user interruption and shutdown remain distinct.
+`loop.idleTimeoutMs` measures provider silence. It starts immediately before the
+provider call, resets on stream activity, and pauses while local tools execute.
+Resource preparation, child waits and approval waiting do not spend this budget.
+The host gives tools their own deadlines. A stalled provider still aborts with
+durable reason `timeout`; caller interruption and shutdown reach tools directly.
 
 Reconnect loads the durable snapshot. Missing transient deltas do not mean the
 canonical result was lost. Exactly-once external delivery requires the
@@ -5593,6 +5597,14 @@ application's transactional outbox or stable-ID deduplication.
 
 ## Managed tools
 
+Durable `step` bodies return lossless JSON: finite numbers (excluding negative zero),
+strings, booleans, null, dense arrays and plain data objects. Return `null` explicitly
+for effect-only bodies and convert Date values to strings. Unsupported values are
+refused after the body, so external effects still require idempotency. First results
+and replay are detached snapshots; mutating a returned object cannot rewrite a record.
+The optional [sandbox coding profile](sandbox.md#coding-tool-integration) reuses the
+same tool mounting, authorization and output handling for namespace-backed commands.
+
 Always compose `toolFenceLifecycle` into `mountAgent`. It checks ownership
 before a managed side effect and again before accepting its result. Fence loss
 uses an internal control signal: it stops the old loop and is not sent to the
@@ -6690,6 +6702,140 @@ the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
 
 
+==============================================================================
+# Guide: Optional process sandbox  (docs/guide/sandbox.md)
+==============================================================================
+
+---
+title: Optional process sandbox
+description: Linux namespace isolation, durable workspaces and a host credential gateway.
+---
+
+# Optional process sandbox
+
+`stitchkit/agent-runtime/sandbox` is a server-only, evolving API. Existing coding
+tools and agent configuration retain their current behavior. A host explicitly
+creates a session and opts into `createSandboxCodingTools`; importing this
+entrypoint does not redirect existing coding tools.
+
+```ts
+import { createBubblewrapSandboxBackend } from 'stitchkit/agent-runtime/sandbox';
+
+const backend = await createBubblewrapSandboxBackend({
+  stateDirectory: '/var/lib/my-app/sandboxes',
+  maxConcurrentCommands: 8,
+  onBrokerError: (cause) => console.error('Internal sandbox gateway error', cause),
+});
+const template = await backend.prewarm({
+  template: 'agent-workspace',
+  files: { 'hello.txt': new TextEncoder().encode('hello') },
+});
+const handle = await backend.create({ template: template.templateKey, network: 'deny-all' });
+try {
+  const result = await handle.session.run({ executable: '/usr/bin/cat', args: ['hello.txt'] });
+  console.log(result.stdout);
+  const state = handle.captureState(); // Persist this descriptor in the host's store.
+  await handle.stop();
+  const resumed = await backend.create({ template: template.templateKey, state, network: 'deny-all' });
+  try { console.log(await resumed.session.readTextFile('hello.txt')); }
+  finally { await resumed.delete(); }
+} finally { await handle.shutdown(); }
+```
+
+`prewarm` snapshots the supplied byte files. Its content-addressed key includes
+the backend name, template name and file contents. It is not a VM image or a
+package installer. `stop` and `shutdown` kill live commands and retain workspace
+files; `delete` removes session state and workspace, preserving reusable templates.
+Reconnect requires the same backend name and template. A live owner holds an
+exclusive lease: concurrent attach and deletion by an older handle fail with
+`SANDBOX_BUSY`. After a host crash, an operator must verify that its processes are
+gone before removing a stale lease; automatic crash recovery is not provided.
+Storage is process-durable, without a power-loss/fsync guarantee.
+
+## Coding tool integration
+
+```ts
+import { createSandboxCodingTools } from 'stitchkit/agent-runtime/sandbox';
+import { mountAgent } from 'stitchkit/tools';
+
+const tools = mountAgent([], {
+  runtimeTools: createSandboxCodingTools(handle, {
+    authorize: (operation) => applicationPolicy(operation),
+    executables: { shell: '/usr/bin/sh' },
+    requiredRestrictions: ['network-denied', 'write-contained', 'process-contained', 'secrets-hidden'],
+    limits: { shellTimeoutMs: 10_000, maxShellOutputBytes: 65_536 },
+  }),
+});
+```
+
+The factory uses the existing coding profile, including its authorization,
+path containment, UTF-8 handling, output artifacts and command limits. File tools
+access the same workspace through the host's contained-file implementation;
+commands run inside the namespace with `/workspace` as their root. The host-only
+`handle.coding` binding never belongs in model input or persisted state.
+Unsupported backends omit the binding and the factory refuses explicitly.
+
+Stop also kills coding commands. Both launch paths share the configured
+`maxConcurrentCommands` admission limit (default 8); an occupied slot gives
+`SANDBOX_BUSY` before another process starts. This counts direct commands, not
+guest descendants. Required restrictions are checked again during preparation;
+a network-policy change invalidates an outstanding prepared launch. After
+reconnect, create the coding profile from the new handle; old tools remain stopped.
+
+## Network gateway
+
+`deny-all` isolates the network namespace, including DNS and loopback access to
+host services. `{ allow: [{ origin, headers }] }` retains that isolation and
+allows HTTP through a Unix-socket gateway only. Origins are exact HTTP(S) origins,
+including scheme and port; no wildcard, redirect, arbitrary TCP or CONNECT tunnel
+is allowed. For HTTPS upstreams the **host** establishes TLS. Guests speak HTTP
+over the socket with the upstream host in `Host`, for example:
+
+```ts
+await handle.session.setNetworkPolicy({
+  allow: [{ origin: 'https://api.example.com', headers: { authorization: hostCredential } }],
+});
+await handle.session.run({
+  executable: '/usr/bin/curl',
+  args: ['--unix-socket', '/run/stitchkit-network.sock', 'http://api.example.com/resource'],
+});
+```
+
+The host obtains `hostCredential` from its credential store. Headers never enter
+guest environment, process arguments or persisted reconnect state. Authorized
+upstreams are trusted: an upstream that reflects its request headers can disclose
+them in its response. This gateway cannot prevent that. Header values are fixed
+for the policy; replace the policy to rotate credentials. Policy changes require
+all commands to finish or stop (`SANDBOX_BUSY` otherwise). `allow-all` explicitly
+shares host networking and adds no injected headers; use it only when unrestricted
+egress is intended. Policies are resupplied on every reconnect and are not stored.
+
+## Runtime boundary
+
+The reference backend requires Linux, `/usr/bin/bwrap`, usable namespaces and a
+conventional `/usr`, `/lib`, `/lib64` layout. Failure to establish isolation gives
+`SANDBOX_UNAVAILABLE`; there is no host-execution fallback. Runtime directories
+are read-only, the workspace is writable, environment is cleared, and host home,
+state storage and other host sockets are not mounted. Each command gets ephemeral
+`/tmp`; only `/workspace` persists. Runtime binaries and the configured state
+directory belong to the trusted host. See the
+[Bubblewrap security model](https://github.com/containers/bubblewrap#system-security).
+
+This is namespace isolation over the host kernel, not a VM. It does not impose
+memory, CPU, disk or process-count quotas. A host running mutually untrusted workloads
+must supply those bounds outside the namespace (for example, a delegated cgroup and
+quota-controlled storage); command admission is not a substitute. Commands default to a 30-second deadline
+and 1 MiB combined output; callers can configure both. File I/O is bounded to
+1 MiB. The gateway allows 16 concurrent requests, 1 MiB request/response bodies
+and a 30-second deadline. Do not treat these bounds as resource containment for
+arbitrary hostile workloads.
+
+Custom backends implement `SandboxDriver` byte I/O, `spawn` and policy enforcement;
+`createSandboxSession` supplies text conversion, paths and `run` once. Paths are
+workspace-relative or canonical `/workspace/...` paths. Unsupported policies must
+be refused explicitly by the backend.
+
+
 ==============================================================================
 # Guide: Generic application primitives  (docs/guide/primitives.md)
 ==============================================================================
@@ -8664,13 +8810,49 @@ Nothing an open can fail with escapes as a rejected promise: a disconnected
 socket, a timeout, a refusal all arrive as `unavailable` carrying the error's own
 code and message, and the next connection retries.
 
+The re-open carries what the client still holds, so a reconnection is usually
+cheap: the hub answers with a difference, or with nothing at all when the answer
+has not moved. That needs the key to still exist on the server — set `holdMs`
+past your reconnect delay, or the last detach releases the source and the page
+pays the whole value once.
+
+### Large answers cross as differences
+
+A frame carries the value, a **difference** to a revision this subscriber already
+holds, or `unchanged`. The hub chooses per subscriber and sends a difference only
+when it is genuinely smaller; your `value` listener sees the rebuilt value either
+way and needs no code for this.
+
+It matters when an answer is large and moves a little: a ~75 KB list in which two
+timestamps change, republished every fifteen seconds, was a megabyte per
+subscriber per minute before and is a frame under a kilobyte now.
+
+```ts
+createWatchHub({
+  // Superseded values kept per key, so a difference has something to be taken
+  // against. Default 262144. Set 0 to send whole values only.
+  deltaMemoryBytes: 256 * 1024,
+  holdMs: 30_000,
+  // …
+});
+```
+
+Reassembly is checked against the server's fingerprint on every frame. If a
+difference will not apply — a client that missed a revision, a hub that restarted
+— that **one key** resynchronises: your `state` listener sees `resync-required`
+and the whole value follows. Other keys on the same socket are untouched.
+
+Both ends must come from the same major release: a client older than 0.90 reads a
+difference frame as a value of `undefined`.
+
 ### `watch` or `createLiveStateController`?
 
 > **If you would have written `applyEvent` as `(_, next) => next`, you want
-> `watch`: the server sends the value whole.** `createLiveStateController` is for
-> a server that sends *deltas* you have to fold. `watch` is that controller with
-> the fold fixed to replacement, plus the key sharing and the retention — so
-> applying both to one value is always a mistake.
+> `watch`: whatever crosses the wire, what your `value` listener receives is the
+> whole answer.** `createLiveStateController` is for a server whose *protocol* is
+> deltas that your code folds. `watch` may send a difference too, but it folds it
+> for you and hands you the value — so applying both to one value is always a
+> mistake.
 
 ### What it cannot promise
 
@@ -9600,9 +9782,10 @@ stitchkit answers this at two levels.
   sanitisation and `createObservability` with independent request/tool sinks.
   [Start here ↓](#the-observability-module)
 
-stitchkit still ships no logger and no audit store — those are the app's choice.
-What it ships is the machinery that turns a completed call into a clean,
-normalised record.
+stitchkit still ships no logger and no audit store, and auditing stays opt-in —
+those are the app's choice (→ ADR 0012, reaffirmed in ADR 0184). What it ships is
+the machinery that turns a completed call into a clean, normalised record, keeps
+the ones worth keeping, and does not lose them when the store is down.
 
 ## The observability module
 
@@ -9839,6 +10022,69 @@ queryable across all three:
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
 
+### Write the calls that changed something
+
+`auditChanges` is the filter most projects end up writing, shipped so they do not
+have to write it six ways:
+
+```ts
+import { auditChanges, createObservability } from 'stitchkit/observability';
+
+createObservability({
+  request: { write: saveAuditRow, filter: auditChanges },
+  tools: { write: saveAuditRow, filter: auditChanges },
+});
+```
+
+It drops `GET`, `HEAD` and `OPTIONS`, keeps everything else, and keeps `401` and
+`403` **whatever the verb was** — a refused read is the row an audit exists to
+hold, and a filter that drops every `GET` drops exactly that. An unrecognised
+verb is kept: an extra row costs bytes, a missing one costs the answer to "who
+changed this", silently and only later.
+
+One filter across HTTP, MCP and agent calls, because a tool call carries its
+contract verb in `httpMethod` while its `method` is the literal `TOOL`.
+
+Narrower policy stays yours — compose it:
+
+```ts
+filter: (event) => auditChanges(event) && event.serviceName !== 'health',
+```
+
+### Keeping the row when the store is down
+
+A sink is fire-and-forget, so an unreachable store means the event is simply
+gone — and a store is most likely to be unreachable during an incident, which is
+the window whose rows someone will later want most.
+
+`createSpooledSink` writes the row to a local append-only file first, offers it
+to the store second, and marks it delivered third. What a previous process left
+unmarked is replayed:
+
+```ts
+import { createSpooledSink } from 'stitchkit/observability';
+
+const audit = createSpooledSink({
+  path: '/var/lib/app/audit.ndjson',
+  write: saveAuditRow,
+});
+
+// Once, at startup, before the sink is wired — and await it.
+const { replayed, failed } = await audit.recover();
+
+createObservability({ request: { write: audit.write, filter: auditChanges } });
+```
+
+The guarantee is **at least once**. A crash between the store accepting a row and
+the file recording that it did replays the row, so **the store must be idempotent
+on the record key** — `event.spanId` by default, unique per call. A unique index
+on it turns the duplicate into a no-op; without one, replay writes the row twice.
+Exactly-once would need the file and the database to share a transaction. They do
+not.
+
+One process, one path. Two processes pointed at the same file replay each other's
+records: harmless against an idempotent store, wasteful always.
+
 ### Request context
 
 When request observability is configured, `createHandler` establishes the
@@ -11236,6 +11482,65 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.90.0
+
+1. `stitchkit.watch.value` is a discriminated union on `kind` — `full`, `delta`,
+   `unchanged` — and every frame carries `fingerprint`. **Both ends must come from
+   the same major.** A client older than this release reads a `delta` frame as a
+   value of `undefined`, silently; upgrade the hub and the pages that talk to it
+   together, or set `deltaMemoryBytes: 0` on the hub until they are.
+
+   Applications using `createWatchClient` need no code change: it rebuilds the
+   value and hands the listener the whole answer as before. Code that reads
+   `WatchValueFrame.value` directly — a hand-written subscriber, a test double —
+   narrows on `kind` first.
+
+   ```ts
+   // before: frame.value
+   // after:
+   if (frame.kind === 'full') hold(frame.value);
+   else if (frame.kind === 'delta') hold(applyWatchDelta(held, frame.delta));
+   // 'unchanged' leaves what you hold standing
+   ```
+
+2. `AttachedWatcher.open` takes an optional third argument, `have`. A custom
+   server binding that forwards `stitchkit.watch.open` should pass the payload's
+   `have` through; omitting it costs a whole value on every reconnection and is
+   otherwise harmless.
+
+## Released migration: 0.89.0
+
+1. Custom `AgentRuntimeStore` adapters implement `seedConversationInput`; custom
+   `AgentRuntimeStoreDriver` adapters implement `seeds.load` and `seeds.create` together
+   with atomic, ordered history insertion. Use the maintained Prisma example and run
+   `runAgentStoreConformance` against the adapter. Built-in memory and SQLite
+   stores already implement the contract; SQLite migrates to schema version 3.
+2. OpenRouter usage normalization consumes each completed SDK step's `usage`, including
+   `raw`, rather than aggregate usage. Missing counters stay `unavailable`.
+
+   ```ts
+   // before: normalizeOpenRouterUsage(await result.usage, metadata)
+   // after:
+   for (const step of await result.steps) {
+     const usage = normalizeOpenRouterUsage(step.usage, step.providerMetadata);
+     // Persist the step's measured usage with its provenance.
+   }
+   ```
+
+3. Durable step bodies return lossless JSON. Convert dates explicitly, reject invalid
+   numbers upstream, and return `null` after an effect-only operation.
+
+   ```ts
+   await context.step('send', async () => {
+     await sendIdempotently();
+     return null;
+   });
+   ```
+
+   First execution, replay and concurrent callers receive detached values. Persistence
+   does not make external effects transactional; the host retains idempotency and recovery.
+
+
 How to move a consuming project from one stitchkit version to another — including
 across many versions at once (a project frozen on an old version, then jumped
 forward). The process is mechanical: stitchkit marks every breaking change in one
@@ -14942,7 +15247,10 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 | `watchContract` | const | the four-event realtime contract a watched read travels on |
 | `WATCH_OPEN` / `WATCH_CLOSE` / `WATCH_VALUE` / `WATCH_STATE` | const | the event names of that contract |
 | `WatchKey` / `WatchKeySchema` / `watchKeyString` | type / schema / function | `(service, action, arguments digest)` — the identity both ends compute the same way |
-| `WatchValueFrame` / `WatchValueSchema` / `WatchStateFrame` / `WatchStateSchema` | _types_ | a value with its monotonic revision, and a phase from `LiveStatePhase` with the read's own code and message |
+| `WatchValueFrame` / `WatchValueSchema` / `WatchStateFrame` / `WatchStateSchema` | _types_ | one answer — `full`, `delta` or `unchanged`, with its monotonic revision and fingerprint — and a phase from `LiveStatePhase` with the read's own code and message |
+| `WatchHave` / `WatchHaveSchema` | type / schema | what a reconnecting subscriber already holds, offered on `open`: a revision and the fingerprint that proves it |
+| `WatchDelta` / `WatchDeltaSchema` / `WatchArrayOp` / `WatchArrayOpSchema` | _types_ / schemas | a structural difference over parsed JSON — objects by changed and dropped key, arrays by runs copied from the previous value |
+| `watchDiff` / `applyWatchDelta` / `watchDeltaWins` | functions | build a difference (`undefined` when equal), rebuild the value from one (throws rather than inventing), and whether it is actually smaller than the value |
 
 ---
 
@@ -15559,6 +15867,12 @@ Server-only optional application runtime. See the
 | `AgentConversationPageSchema` / `AgentConversationPage` | schema / _type_ | cursor-paged conversation summaries |
 | `AgentConversationMessagePageSchema` / `AgentConversationMessagePage` | schema / _type_ | cursor-paged durable message history |
 | `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
+| `SeedConversationInputSchema` / `SeedConversationInput` | schema / _type_ | atomic once-seeding input; partial imported identity sets are refused |
+| `AgentSeedReceiptSchema` / `AgentSeedReceipt` | schema / _type_ | durable seed receipt retained beyond compaction and implemented by custom store drivers |
+| `createLocalStepDurability` | function | record JSON step results and park on time/events; a replay returns recorded results, while unrecorded effects require host idempotency |
+| `StepDurabilityLedger` / `LocalStepDurability` / `LocalStepDurabilityOptions` / `StepRunOptions` | _type_ | the narrow ledger the port needs, the step/read surface, and its construction and per-step options |
+| `DURABILITY_STEP_EVENT_KIND` | const | the ledger event kind a recorded step is written under |
+| `StepResultDecodeError` / `StepResultNotSerializableError` / `StepAbortedError` / `ParkRecordDecodeError` / `ParkAbortedError` | class | fail-closed decode of a recorded step or park, a body whose result cannot be serialized, an aborted step, and a park collapsed around an aborted waiter |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
 | `selectCompactableHistory` | function | which oldest whole complete turns may be summarised away — the half of compaction that needs no store (→ ADR 0142) |
 | `SelectCompactableHistoryOptions` / `CompactableHistory` | _type_ | message list, retained-turn count and evidence policy in; `leadingSummary`, `compactable` and `retained` out |
@@ -15599,10 +15913,12 @@ Server-only optional application runtime. See the
 | `agentGoalStateSlot` / `agentTodoStateSlot` / `createAgentStateTools` | constants / function | built-in goal/todo state and bound `goal_*` / `todo_write` Agent tools |
 | `AgentSandboxGradeSchema` / `AgentSandboxGrade` / `AgentSandboxRestrictionSchema` / `AgentSandboxRestriction` / `AgentProcessSandbox` | schema / _type_ | host-provided process sandbox capability and explicit restriction vocabulary |
 | `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | process-cached probe, fail-closed required-gap calculation and durable probe record |
+| `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
 | `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `createAgentScheduleService` / `createAgentScheduleTools` | schema / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, stable dispatch identity and Agent tools |
 | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
+| `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
 | `AgentChildHandle` / `AgentChildManager` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
 | `AgentToolDefinition` | _type_ | peer-neutral shape returned by the bound agent-only state, search, schedule and child tool factories |
 | `AgentProviderStreamCutError` | class | explicit retryable provider stream truncation evidence |
@@ -15630,7 +15946,11 @@ recognises a failure carried inside a *successful* tool result, in both the bare
 
 `normalizeOpenRouterUsage` is the same normalisation `openRouterProvider`
 applies, exported so an application calling the SDK directly gets provenance-correct numbers
-without adopting the runtime.
+without adopting the runtime. Pass each completed SDK step's usage, including `raw`.
+Token provenance comes from the original OpenRouter fields: missing fields remain
+`unavailable`, even when the SDK substitutes zero. Aggregate usage without `raw` cannot
+establish reported token counts. Explicit zero remains `provider-reported`; cost is never
+estimated from token prices.
 
 `AgentContextUsage` reaches every step through `AgentRuntimeRunContext.contextUsage`: how full the
 model's context is, as `usedTokens` (an `AgentUsageValue`, so it carries the provenance that says
@@ -15789,6 +16109,9 @@ and introduces no store, queue or model-provider implementation of its own.
 | `AgentHarnessControlServer` / `AgentHarnessControlConnection` | _type_ | host server and detachable connection lifecycle; `deliver` is serialized, while required out-of-band `onOverflow` closes/aborts a slow transport before reconnect |
 | `AgentHarnessControlServerConfig` | _type_ | explicit per-connection pending-event and server-wide concurrent attachment-snapshot bounds for failure-isolated control delivery |
 | `AgentHarnessPendingApproval` / `AgentHarnessApprovalDecision` | _type_ | exact durable pending request and allow/deny successor input |
+| `AgentHarnessApprovalRequest` | _type_ | the pending request as a response-time policy sees it: approval id, call id, tool name and input |
+| `AgentHarnessApprovalAuthorization` / `AgentHarnessApprovalAuthorizationResult` | _type_ | response-time policy input (responder, conversation, request, proposed decision) and its `allowed` / `rejected` result |
+| `AgentHarnessApprovalRejectedError` | class | thrown when the response policy refuses a responder; the pending request is left answerable |
 
 Resources default to at most 64 entries, 1 MiB of total UTF-8 text and 128 diagnostics. Duplicate
 names and exceeded bounds fail before the provider step. Recovery remains the underlying runtime's
@@ -15948,6 +16271,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
+| `auditChanges` | function | the sink `filter` most projects write themselves — drops `GET`/`HEAD`/`OPTIONS`, keeps `401`/`403` whatever the verb, keeps an unrecognised verb |
+| `createSpooledSink` / `SpooledSink` / `SpooledSinkConfig` / `SpoolRecovery` | function / _types_ | spool the row to an append-only file before the store and replay what a previous process left undelivered — at least once, keyed on `spanId` |
 | `createDimensionsProjector` / `DimensionsProjector` / `DimensionsProjectorConfig` / `ProjectedDimensions` | function / _type_ | typed request/result/error attribution projected into the existing request context |
 | `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
@@ -16105,6 +16430,8 @@ payload.
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
 | `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT' \| 'CLI'`; omission still means MCP+Agent only |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
+| `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
+| `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection and command-scoped `optionAliases` / `positionals` policy |
 | `CliPresentationPolicyConfig` | _type_ | reusable default-command, short-alias and explicit-positional policy inherited by `CliConfig` |
@@ -16267,6 +16594,36 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 ---
 
+## `stitchkit/tools/connections`
+
+Server-only subexport that consumes external MCP servers and OpenAPI specifications
+as typed tools, without adding a peer dependency to `stitchkit/tools`. Foreign
+operations mount as the same `RuntimeToolDefinition`s our own produce, so
+`mountAgent({ runtimeTools })` runs them through the canonical lifecycle, hooks
+and approval path.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineMcpClientConnection` | function | declare one external MCP server connection over Streamable HTTP with an optional SSE fallback |
+| `defineOpenApiConnection` | function | declare one OpenAPI document (object, JSON text or JSON URL) as a tool surface |
+| `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent` |
+| `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |
+| `ConnectionBudgetExceededError` | class | the mount would expose more foreign tools than its declared budget |
+| `ConnectionRequestError` | class | any non-`2xx` connection response other than the reauthorization signal |
+| `ConnectionUrlError` | class | a non-http(s) URL or a request host the SSRF fence refused |
+| `ConnectionTokenProvider` | _type_ | `() => string \| undefined \| Promise<string \| undefined>` — the lazily resolved credential |
+| `ConnectionBudget` | _type_ | `{ maxTools? }` ceiling on one `mountConnections` call |
+| `ConnectionDefinition` | _type_ | either a defined MCP client or OpenAPI connection |
+| `ConnectionMountOptions` | _type_ | shared `{ lifecycle?, budget? }` mount policy |
+| `McpClientConnection` | _type_ | a defined MCP client connection |
+| `McpClientConnectionConfig` | _type_ | name, transport, tool filter, token provider, instance key and allowed hosts |
+| `McpConnectionTransport` | _type_ | `{ url, headers? }` for one MCP endpoint |
+| `McpToolFilter` | _type_ | `{ allow?, block? }` discovered-tool filter |
+| `OpenApiConnection` | _type_ | a defined OpenAPI connection |
+| `OpenApiConnectionConfig` | _type_ | name, spec, base URL, token provider, instance key and allowed hosts |
+
+---
+
 ## `stitchkit/testing`
 
 Fetch-only integration helpers that preserve the real generated-client and
@@ -16639,3 +16996,16 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 For the rationale behind these APIs — why `Bun.serve` and not a framework, why
 two context types, why thin wrappers — see the
 [Architecture Decisions](../decisions/).
+
+## `stitchkit/agent-runtime/sandbox`
+
+Optional server-only namespace sandbox. Exports:
+`createSandboxCodingTools` composes the existing coding profile over a handle's
+host-only `SandboxCodingBinding`, with shared authorization, command collection and lifecycle.
+`createBubblewrapSandboxBackend`, `createSandboxSession`, `SandboxError`,
+`SandboxCommandSchema`, `SandboxNetworkPolicySchema`, `SandboxStateSchema`.
+Its types are `BubblewrapSandboxConfig`, `SandboxBackend`, `SandboxCommand`,
+`SandboxCreateInput`, `SandboxDriver`, `SandboxHandle`, `SandboxNetworkPolicy`,
+`SandboxPrewarmInput`, `SandboxProcess`, `SandboxRunOptions`, `SandboxSession`,
+and `SandboxState`. The [sandbox guide](../guide/sandbox.md) specifies lifecycle,
+network enforcement, gateway credentials and platform/resource boundaries.

package/llms.txt

@@ -14,6 +14,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
 - [Agent application runtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-runtime.md): optional durable history, prompt/model composition, stream loop, coordination, fencing and events
 - [Managed application kernel](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-kernel.md): process-local resources, readiness, admission, schedules, projections and optional provider adapters
+- [Optional process sandbox](https://github.com/max-listov/stitchkit/blob/master/docs/guide/sandbox.md): Linux Bubblewrap sessions, durable workspace reconnect, network policy and host credential brokering
 - [Generic application primitives](https://github.com/max-listov/stitchkit/blob/master/docs/guide/primitives.md): lifecycle transitions, owner scope, permissions, exact money and quantities, deadlines, audit, delivery and exports — declared, not persisted
 - [Application migration recipes](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-migration-recipes.md): executable database, poller, queue-consumer and operational publishing cutovers
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.88.0",
+  "version": "0.90.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -73,6 +73,10 @@
       "types": "./dist/tool-invoker.d.ts",
       "import": "./dist/tool-invoker.js"
     },
+    "./tools/connections": {
+      "types": "./dist/tools/connections/index.d.ts",
+      "import": "./dist/tools/connections/index.js"
+    },
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
@@ -153,6 +157,10 @@
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
     },
+    "./agent-runtime/sandbox": {
+      "types": "./dist/agent-runtime-sandbox.d.ts",
+      "import": "./dist/agent-runtime-sandbox.js"
+    },
     "./files": {
       "types": "./dist/files.d.ts",
       "import": "./dist/files.js"

package/dist/index-dre2ywck.js

@@ -1,48 +0,0 @@
-import {
-  LiveStatePhaseSchema,
-  LiveStateStopReasonSchema
-} from "./index-ywd0y6m1.js";
-
-// src/live/watch-contract.ts
-import { z } from "zod";
-var WatchKeySchema = z.object({
-  service: z.string().min(1),
-  action: z.string().min(1),
-  digest: z.string().min(1)
-}).strict().readonly();
-var WatchOpenSchema = z.object({ key: WatchKeySchema, args: z.unknown() }).readonly();
-var WatchAcceptedSchema = z.object({
-  accepted: z.boolean(),
-  reason: z.string().optional()
-}).strict().readonly();
-var WatchValueSchema = z.object({
-  key: WatchKeySchema,
-  revision: z.number().int().nonnegative(),
-  value: z.unknown()
-}).readonly();
-var WatchStateSchema = z.object({
-  key: WatchKeySchema,
-  phase: LiveStatePhaseSchema,
-  reason: LiveStateStopReasonSchema.optional(),
-  code: z.string().optional(),
-  message: z.string().optional()
-}).readonly();
-var WATCH_OPEN = "stitchkit.watch.open";
-var WATCH_CLOSE = "stitchkit.watch.close";
-var WATCH_VALUE = "stitchkit.watch.value";
-var WATCH_STATE = "stitchkit.watch.state";
-var watchContract = {
-  serverToClient: {
-    [WATCH_VALUE]: { args: z.tuple([WatchValueSchema]) },
-    [WATCH_STATE]: { args: z.tuple([WatchStateSchema]) }
-  },
-  clientToServer: {
-    [WATCH_OPEN]: { args: z.tuple([WatchOpenSchema]), ack: WatchAcceptedSchema },
-    [WATCH_CLOSE]: { args: z.tuple([z.object({ key: WatchKeySchema }).readonly()]) }
-  }
-};
-function watchKeyString(key) {
-  return `${key.service}/${key.action}/${key.digest}`;
-}
-
-export { WatchKeySchema, WatchValueSchema, WatchStateSchema, WATCH_OPEN, WATCH_CLOSE, WATCH_VALUE, WATCH_STATE, watchContract, watchKeyString };