stitchkit 0.88.0 → 0.89.0

package/dist/tools.js

@@ -21,8 +21,8 @@ import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "./index-1szetq6f.js";
-import"./index-3xnq72rz.js";
+} from "./index-q3ve2d1k.js";
+import"./index-7rkhw9ec.js";
 import {
   argumentsDigest
 } from "./index-a916km3r.js";
@@ -37,7 +37,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-0ydchz76.js";
+} from "./index-mnm4qp0p.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -46,47 +46,28 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-9hw9eq48.js";
+} from "./index-7601qfg1.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-rcgsnrr6.js";
-import {
-  createRuntimeToolFactory,
-  defineRuntimeTool
-} from "./index-kc6h6hg0.js";
+} from "./index-31jw8fjq.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-0vfdh685.js";
+} from "./index-8c3a7m4g.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-wn9cb82y.js";
+} from "./index-zyvby92n.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
 } from "./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import {
-  PORTABLE_JSON_SCHEMA_FORMATS,
-  assertToolName,
-  assertUniqueToolName,
-  findNonPortableFormats,
-  findUntypedProperties,
-  flattenToolJsonSchema,
-  prepareProjectedMcpTools,
-  presentationMetadata,
-  validateMcpRoundPolicy
-} from "./index-r159gjwy.js";
-import"./index-cby4ar3v.js";
-import {
-  coerceJsonArgs
-} from "./index-7zbps32p.js";
 import {
   normalizeError
 } from "./index-7evdsyez.js";
@@ -104,7 +85,26 @@ import {
 import {
   resolvePropagationContext
 } from "./index-zcgf3gqf.js";
+import {
+  coerceJsonArgs
+} from "./index-7zbps32p.js";
 import"./index-kzfs85xp.js";
+import {
+  createRuntimeToolFactory,
+  defineRuntimeTool
+} from "./index-kc6h6hg0.js";
+import {
+  PORTABLE_JSON_SCHEMA_FORMATS,
+  assertToolName,
+  assertUniqueToolName,
+  findNonPortableFormats,
+  findUntypedProperties,
+  flattenToolJsonSchema,
+  prepareProjectedMcpTools,
+  presentationMetadata,
+  validateMcpRoundPolicy
+} from "./index-r159gjwy.js";
+import"./index-cby4ar3v.js";
 import {
   isRecord
 } from "./index-77fekveh.js";
@@ -2521,6 +2521,62 @@ function mountOAuthProvider(config) {
   };
   return dcrEnabled ? [metadataRoute, registerRoute, authorizeRoute, tokenRoute] : [metadataRoute, authorizeRoute, tokenRoute];
 }
+// src/tools/registry.ts
+function defineToolRegistry(input) {
+  const defaults = [...input.defaults];
+  const slots = new Set;
+  for (const tool of defaults) {
+    if (!tool.name)
+      throw new Error("A default tool must carry a non-empty name");
+    if (slots.has(tool.name))
+      throw new Error(`Duplicate default tool name: ${tool.name}`);
+    slots.add(tool.name);
+  }
+  const disabled = new Set;
+  const replacements = new Map;
+  const assertKnown = (name, verb) => {
+    if (!slots.has(name)) {
+      throw new Error(`Tool registry ${verb}("${name}") names no default; declared: ${[...slots].sort().join(", ") || "(none)"}`);
+    }
+  };
+  const builder = {
+    replace(name, tool) {
+      assertKnown(name, "replace");
+      if (disabled.has(name)) {
+        throw new Error(`Tool registry cannot replace "${name}": it is disabled`);
+      }
+      if (replacements.has(name)) {
+        throw new Error(`Tool registry already replaced "${name}"`);
+      }
+      if (tool.name !== name) {
+        throw new Error(`A replacement for "${name}" must carry that name, not "${tool.name}"`);
+      }
+      replacements.set(name, tool);
+      return builder;
+    },
+    disable(name) {
+      assertKnown(name, "disable");
+      disabled.add(name);
+      return builder;
+    },
+    build() {
+      const tools = [];
+      const seen = new Set;
+      for (const tool of defaults) {
+        if (disabled.has(tool.name))
+          continue;
+        const effective = replacements.get(tool.name) ?? tool;
+        if (seen.has(effective.name)) {
+          throw new Error(`Duplicate composed tool name: ${effective.name}`);
+        }
+        seen.add(effective.name);
+        tools.push(effective);
+      }
+      return { tools, names: tools.map((tool) => tool.name) };
+    }
+  };
+  return builder;
+}
 // src/tools/tool-logger.ts
 function createToolLogger(config = {}) {
   const log = config.log ?? ((line) => console.error(line));
@@ -2646,6 +2702,7 @@ export {
   defineWaitTool,
   defineViewFileTool,
   defineUploadTool,
+  defineToolRegistry,
   defineRuntimeTool,
   defineDownloadTool,
   defineCliCommand,

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 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 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 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 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 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 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 |
@@ -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)
 ==============================================================================
@@ -11236,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
@@ -15559,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 |
@@ -15599,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 |
@@ -15630,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
@@ -15789,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
@@ -16105,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` |
@@ -16267,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
@@ -16639,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.88.0",
+  "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";