stitchkit 0.92.0 → 0.94.0

package/llms/agent-runtime-coding-tools.txt

@@ -0,0 +1,58 @@
+# stitchkit/agent-runtime/coding-tools — 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/coding-tools`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/coding-tools`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/coding-tools`
+
+Server-only evolving, peer-free direct runtime tools. `createAgentCodingTools(config)` returns
+`read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, optional
+`run_command` and, when an
+artifact store is supplied, `read_output`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAgentCodingTools` | function | construct direct host-authorized bounded file, listing, glob, search, exact-snippet edit, shell and artifact runtime-tool definitions; every ordinary refusal is a typed code with an instructive `hint`, and filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
+| `AGENT_CODING_TOOL_NAMES` | const | the mounted tool names — `read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command`, `read_output` |
+| `AgentCodingToolDefinition` | _type_ | peer-free structural direct-tool shape accepted by the canonical runtime-tool surface |
+| `AgentCodingToolConfig` | _type_ | absolute root, required operation authorization, optional async/sync `authorizePath({ path })` shared by direct file effects and discovery, finite executable alias map, exact child environment and optional limits |
+| `AgentCodingToolAuthorizationSchema` / `AgentCodingToolAuthorization` | schema / _type_ | discriminated read/write/search/patch/shell/artifact decision presented to host policy before effect |
+| `AgentCodingToolPathAuthorizationSchema` / `AgentCodingToolPathAuthorization` | schema / _type_ | strict workspace-relative path presented to the shared path policy before disclosure, opening or mutation |
+| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout/termination-grace ceilings |
+| `AgentCodingArtifactStore` | _type_ | host-owned opaque artifact write and bounded read boundary |
+| `FileReadInputSchema` / `FileReadOutputSchema` | schema | bounded strict-UTF-8 byte slice; offsets must align with UTF-8 code-point boundaries |
+| `FileWriteInputSchema` / `FileWriteOutputSchema` | schema | create-only by default or explicit atomic replacement; symlink targets fail closed |
+| `createShellInputSchema` / `ShellOutputSchema` | schema | enumerated executable alias plus arguments and concrete relative cwd; explicit exited/timeout/output-limit/cancelled outcome |
+
+File/search operations pin directory descriptors across authorization and the actual effect;
+resource discovery uses the same ancestor-safe traversal. This closes parent rename/symlink races
+without claiming an executable sandbox. The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
+of aggregate argument text, 4 MiB per artifact and 30 seconds. The root is a path-resolution
+boundary, not an OS sandbox; executable behavior, process
+isolation, credentials and external-effect idempotency remain host responsibilities.
+
+When `authorizePath` denies a path, direct read/write/edit returns `FORBIDDEN`, while
+`list_directory`, `glob` and `search_files` omit it. Denial is recursive: direct access and
+discovery base paths are checked against `.` and every ancestor, outermost first and segment-wise,
+so denying `credentials` denies `credentials/token.txt` but not `credentials-backup`. Directory
+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.

package/llms/agent-runtime-harness.txt

@@ -0,0 +1,45 @@
+# stitchkit/agent-runtime/harness — 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/harness`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/harness`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/harness`
+
+Server-only evolving facade over the canonical Agent runtime. It requires the optional `ai` peer
+and introduces no store, queue or model-provider implementation of its own.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createHeadlessAgentHarness` | function | compose one `createAgentRuntime` with caller-supplied model resolution, bounded resources, tools and prompt policy; adds canonical `snapshot` |
+| `HeadlessAgentHarness` / `HeadlessAgentHarnessConfig` | _type_ | runtime facade and injected ownership boundary |
+| `HeadlessAgentModelResolver` | _type_ | per-run preflight/resolve port returning the actual `AgentResolvedModel` |
+| `AgentHarnessResourceSchema` / `AgentHarnessResource` | schema / _type_ | strict instruction, skill or resource with name, text and provenance |
+| `AgentHarnessResourceKindSchema` / `AgentHarnessResourceKind` | schema / _type_ | closed `instruction`, `skill` or `resource` vocabulary |
+| `AgentHarnessResourceResult` | _type_ | one loader result containing resources and diagnostics |
+| `AgentHarnessResourceDiagnosticSchema` / `AgentHarnessResourceDiagnostic` | schema / _type_ | bounded caller evidence; observer failure is isolated |
+| `AgentHarnessLimitsSchema` / `AgentHarnessLimits` | schema / _type_ | resource count, total UTF-8 bytes and diagnostic ceilings |
+| `AgentHarnessProfileEventSchema` / `AgentHarnessProfileEvent` | schema / _type_ | actual model descriptor, non-content resource provenance and sorted direct tool identities applied to one run |
+| `createAgentHarnessFileResources` | function | discover explicit instruction/skill/resource roots with symlink containment, bounded summaries and direct exact reads |
+| `AgentHarnessFileRootSchema` / `AgentHarnessFileRoot` | schema / _type_ | caller-owned absolute path, public root ID and resource kind |
+| `AgentHarnessFileLimitsSchema` / `AgentHarnessFileLimits` | schema / _type_ | file count, depth, per-file and aggregate byte ceilings |
+| `AgentHarnessFileResources` | _type_ | loader plus direct `read_resource` definition for lazy exact content |
+| `createAgentHarnessControlServer` | function | transport-neutral correlated requests, observer attachments and exclusive controller leases |
+| `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
+explicit policy; use the Bun or Node SQLite leaf for durable reopen.

package/llms/agent-runtime-openrouter.txt

@@ -0,0 +1,22 @@
+# stitchkit/agent-runtime/openrouter — 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/openrouter`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/openrouter`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/agent-runtime/openrouter`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `openRouterProvider` | function | isolated `@openrouter/ai-sdk-provider` language-model factory |
+| `openRouterModelCatalog` | function | complete tool-capable text catalog plus independent weekly popularity and available benchmark observations |
+| `OpenRouterProviderSettings` | _type_ | official provider settings accepted by the factory |
+| `OpenRouterModelCatalogOptions` / `OpenRouterCatalogFetch` | _type_ | credential, timeout, clock and injected fetch boundary for catalog loading |

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 |