stitchkit 0.87.1 → 0.89.0

package/llms-full.txt

@@ -55,6 +55,7 @@ own, recorded as an ADR.
 | `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 32 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 34 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 18 of the 32 minors since 0.56.2, most recently 0.87.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 34 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 32 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 34 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 |
@@ -4742,6 +4744,11 @@ root and cwd are path boundaries, not a security sandbox: isolate the process wh
 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
@@ -4765,7 +4772,11 @@ Host-level causes stay scrubbed to `INTERNAL_SERVER_ERROR` and name nothing outs
 `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 `include` pattern; regex is bounded by
+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
@@ -4975,10 +4986,14 @@ 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 and exact provider requests enter the same append-only ledger; the
-normalized head/run/message tables remain the fast operational projection.
+`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
@@ -5270,6 +5285,24 @@ own usage. The two channels answer to different readers — delivering a turn tw
 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.
+
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
@@ -5552,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
@@ -5562,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
@@ -5714,6 +5757,10 @@ spent nothing, and an omitted object could not tell you which one you had.
 Two costs in different currencies do not add: the sum reports `unavailable`
 rather than picking a label. The core records a currency and never converts one.
 
+`step-finished.response` identifies the provider response for that one step. The terminal event
+does not copy the last response: response identity remains per-step, while every terminal usage
+figure remains a `computed` aggregate.
+
 **A run's figure is durable, and that is where to read it when a channel loses
 it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
 record, so a crashed process leaves behind what it had already spent and a
@@ -6655,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)
 ==============================================================================
@@ -11201,6 +11382,39 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## 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
@@ -11229,6 +11443,37 @@ of the range if you want a different one.
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.88.0
+
+Two mechanical edits, and only if your project builds these values rather than only reading them.
+
+A completed step event now carries the provider's response identity, and the field is required:
+
+```ts
+// before
+{ type: 'step-finished', step: 0, usage }
+
+// after
+{ type: 'step-finished', step: 0, usage, response: { id: generationId } }
+```
+
+Every event the runtime emits already has it, so a sink that only reads them needs no change. A
+fixture, a test double or a pipeline that re-validates events persisted by an earlier version does:
+give the older records a response identity, or keep parsing them with the schema they were written
+under.
+
+If you implement the whole `AgentRuntime` interface — usually a mock — add the new method:
+
+```ts
+// before
+const fake: AgentRuntime = { submit, interrupt, recover, close }
+
+// after
+const fake: AgentRuntime = { submit, interrupt, abandon, recover, close }
+```
+
+No data migration is involved, and nothing in the store changes shape.
+
 ## Released migration: 0.87.0
 
 Only if your project implements `AgentConversationReader` itself. A message page
@@ -15493,6 +15738,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 |
@@ -15505,6 +15756,7 @@ Server-only optional application runtime. See the
 | `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
 | `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` says the provider never reported the run finished, so the figure beside it is not a confirmed total |
 | `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with causal per-conversation scheduling, context resolver and explicit evidence policy |
+| `AgentRuntimeAbandonInput` | _type_ | one known orphan identity, expected revision and mandatory stale-owner evidence for `runtime.abandon()` |
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
@@ -15514,13 +15766,15 @@ Server-only optional application runtime. See the
 | `AgentRunOperationKindSchema` / `AgentRunOperationPhaseSchema` / `AgentRunOperationSchema` / `AgentRunOperation` | schemas / _type_ | latest durable model-request or compaction phase with operation/step identity and original timestamps; request admission is awaited before provider invocation |
 | `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
+| `AgentProviderResponseSchema` / `AgentProviderResponse` | schema / _type_ | provider-assigned response ID and the optional upstream provider the model's own adapter resolves, shared by `step-finished.response` and durable `provider/response` facts |
+| `AgentStepFinishedEventSchema` / `AgentStepFinishedEvent` | schema / _type_ | one completed provider step with required usage and provider response identity |
 
 ### Durable capability layer
 
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive with exact ledger events, recovery projection and durable spill payloads |
-| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary and bounded page |
+| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary (including `provider/request` and `provider/response`) and bounded page |
 | `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
 | `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
 | `defineAgentProjection` / `AgentProjectionDefinition` / `AgentProjectionValue` / `createAgentProjectionRegistry` / `createSqliteAgentProjectionStore` | functions / _type_ | deterministic folds with persisted version and honest `uptoSeq` checkpoints |
@@ -15530,10 +15784,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 |
@@ -15543,7 +15799,7 @@ Server-only optional application runtime. See the
 The entrypoint deliberately exports the schemas beside their inferred types so persistence and
 transport adapters validate the same records. Runtime composition types are `AgentRuntime`,
 `AgentRuntimeConfig`, `AgentRuntimeInput`, `AgentRuntimeProtocolInput`, `AgentRuntimeRunContext`,
-`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeRecoveryInput`,
+`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeAbandonInput`, `AgentRuntimeRecoveryInput`,
 `AgentRuntimeRecoveryDecision`, `AgentRuntimeRecoveryOutcome`, `AgentRuntimePublisher`,
 `AgentInputPolicy`, `AgentStopReason`, `AgentCoordinatedRun`, `AgentRunTicket`,
 `AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
@@ -15561,7 +15817,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
@@ -15720,6 +15980,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
@@ -15760,6 +16023,13 @@ so denying `credentials` denies `credentials/token.txt` but not `credentials-bac
 admission happens before descent and file admission before opening; `search_files.include` is also
 applied before content is read. Requested paths must use `/` — a backslash is refused, because the
 containment walk reads it as a separator while a callback would read it as one name.
+Absolute paths remain refused; an absolute path inside the canonical root carries an exact
+workspace-relative `recoveryPath`, while one outside the root carries no replacement. The
+`search_files.include` schema states that its pattern is anchored to the whole workspace-relative
+path, `*` does not cross `/`, and `**/` is required for nested matches. `scannedFiles` is the
+post-include/post-authorization comparison count. A `hint` is added only when the filter itself
+produced the zero — it rejected every file the scan reached — never when there was nothing to
+reject or the host refused it.
 `run_command` is intentionally outside this guarantee because an executable needs process isolation,
 not path filtering, to constrain its filesystem access. → ADR 0172.
 
@@ -16029,6 +16299,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` |
@@ -16191,6 +16463,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
@@ -16563,3 +16865,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.87.1",
+  "version": "0.89.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-evcnmsc3.js → index-t7fkyxcr.js}

@@ -1,11 +1,11 @@
-import {
-  managedResourceDependencyId
-} from "./index-2k4yrqkc.js";
 import {
   ApplicationIdSchema,
   ApplicationShutdownResultSchema,
   ApplicationSnapshotSchema
 } from "./index-3gye9wzb.js";
+import {
+  managedResourceDependencyId
+} from "./index-2k4yrqkc.js";
 import {
   ShutdownOptionsSchema
 } from "./index-3z73fh2c.js";