stitchkit 0.93.0 → 0.94.0

package/llms/agent-runtime-sandbox.txt

@@ -0,0 +1,159 @@
+# stitchkit/agent-runtime/sandbox — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Optional process sandbox  (docs/guide/sandbox.md) · API reference: `stitchkit/agent-runtime/sandbox`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# 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.
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/sandbox`  (docs/api/reference.md)
+==============================================================================
+
+## `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/agent-runtime-sqlite-bun.txt

@@ -0,0 +1,29 @@
+# stitchkit/agent-runtime/sqlite/bun — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/sqlite/bun`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/sqlite/bun`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/sqlite/bun`
+
+Bun built-in SQLite persistence. The entrypoint imports `bun:sqlite` and is not
+loaded by the neutral, browser or Node runtime surfaces.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createBunSqliteAgentRuntimeStore` | function | open an owned Bun SQLite connection, initialize/validate schema v2, migrate v1 transactionally and return `{ store, conversations, database, transaction, close }` |
+| `BunSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional create and initialization policies |
+| `createSqliteAgentRuntimeStore` | function | build the normalized store over an injected synchronous SQLite boundary |
+| `initializeAgentRuntimeSqlite` | function | initialize or validate only Stitchkit's namespaced SQLite schema |
+| `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` / `SqliteStoreTransaction` | _type_ | durable store handle — `store`, `conversations`, `database`, `transaction`, `close` — owned connection lifecycle, initialization policy, and the one write transaction the SQLite companions share |
+
+---

package/llms/agent-runtime-sqlite-node.txt

@@ -0,0 +1,26 @@
+# stitchkit/agent-runtime/sqlite/node — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/sqlite/node`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/sqlite/node`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/sqlite/node`
+
+Node 22.5+ built-in SQLite persistence. It shares the schema and semantics of
+the Bun leaf but imports only `node:sqlite`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createNodeSqliteAgentRuntimeStore` | function | open an owned Node `DatabaseSync`, initialize/validate schema v2, migrate v1 transactionally and return `{ store, conversations, database, transaction, close }` |
+| `NodeSqliteAgentRuntimeStoreConfig` | _type_ | database filename plus optional read-only and initialization policies; read-only requires an initialized schema |
+| `createSqliteAgentRuntimeStore` / `initializeAgentRuntimeSqlite` | function | shared normalized adapter and namespaced schema lifecycle |
+| `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` / `SqliteStoreTransaction` | _type_ | durable store handle — `store`, `conversations`, `database`, `transaction`, `close` — owned connection lifecycle, initialization policy, and the one write transaction the SQLite companions share |

package/llms/agent-runtime-testing.txt

@@ -0,0 +1,30 @@
+# stitchkit/agent-runtime/testing — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/testing`
+
+Credential-free provider and concurrency fixtures for Bun and Node tests.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createFaultProviderServer` | function | start an OpenAI-compatible local SSE endpoint with deterministic pass, connection-refused, timeout, stream-cut, HTTP, malformed JSON, slow-stream and missing-usage steps |
+| `AgentFaultStepSchema` / `AgentFaultStep` | schema / _type_ | strict fault-plan step vocabulary |
+| `defineAgentFaultPlan` | function | validate a non-empty deterministic fault sequence |
+| `createReplayAgentProvider` | function | serve a declared sequence of credential-free language-model fixtures per model ID |
+| `createAgentRaceBarrier` / `AgentRaceBarrier` | function / _type_ | named bounded deterministic concurrency barrier |
+| `createAgentRaceTrace` / `AgentRaceTrace` / `AgentRaceTraceEntry` | function / _type_ | record and assert exact event order without wall-clock guesses |
+| `createAgentRaceDriver` / `AgentRaceDriver` | function / _type_ | collect named barriers and release their teardown together |
+| `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
+| `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
+| `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |