stitchkit 0.68.7 → 0.68.8

package/llms-full.txt

@@ -62,6 +62,8 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime` | server | evolving<br>_redefined in 9 of the 13 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events and reconnect cursor without execution or sinks |
+| `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/application` | server | evolving<br>_redefined in 3 of the 13 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules 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` |
@@ -165,6 +167,7 @@ map — feature → packages:
 | MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
+| SQLite agent store (`stitchkit/agent-runtime/sqlite/bun` or `/node`) | — (runtime built-in) |
 | MCP host/client tests | `@modelcontextprotocol/client` |
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
@@ -3730,7 +3733,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-08-22
+updated: 2026-08-28
 ---
 
 # Agent application runtime
@@ -3885,6 +3888,47 @@ await ticket.accepted
 const terminal = await ticket.result
 ```
 
+### Executable headless harness and capability map
+
+[`packages/core/examples/headless-agent-harness.ts`](../../packages/core/examples/headless-agent-harness.ts)
+is the complete resource-aware recipe. It accepts injected protocol, model,
+tool and store ports, validates resources plus diagnostics, carries provenance
+into the prompt and delegates execution to `createAgentRuntime`. Importing the
+example starts no process, opens no database and discovers no filesystem path.
+
+| Concern | Public Stitchkit composition | Boundary |
+| --- | --- | --- |
+| execution loop | `createAgentRuntime` | already available; do not copy a second loop |
+| model choice | `defineModelRegistry` and `models.resolve` | provider credentials/discovery stay application-owned |
+| resources | injected loader → `composeAgentPrompt` sections | paths, trust, precedence and watching stay application-owned |
+| tools | `mountAgent` + `createAgentToolFenceLifecycle` | auth and domain effects stay application-owned |
+| follow-up | `runs.inputPolicy: 'queue'` | durable FIFO after the current run |
+| interrupt | `interrupt` or `interrupt-next` | `interrupt-next` terminates the active run and gives the new durable admission next priority |
+| recovery | `runtime.recover` + `scanRecoverable` | replay safety and context reconstruction are explicit callbacks |
+| reconnect | canonical snapshot + `advanceAgentRuntimeEventCursor` | transient deltas are replaceable; durable event IDs deduplicate |
+| persistence | memory reference, public driver, or SQLite leaf | product rows/outbox remain outside the runtime store |
+
+Pi's steering queue waits for the current tool calls and injects the steering
+message at its next loop boundary. It is therefore not an alias for
+`interrupt-next`: Stitchkit requests termination of the active durable run,
+waits for its terminal settlement, and executes the prioritized successor.
+Pi follow-up is closest to Stitchkit `queue`, while JSONL trees, branching,
+workspace discovery, permissions and terminal UI remain embedding-application
+features rather than runtime requirements.
+
+Runtime events preserve reasoning/text/tool lifecycle order. Durable admission,
+checkpoint, run-state and terminal events carry stable identities; transient
+deltas carry one runtime epoch and monotonic sequence. On a transient gap,
+reload the canonical snapshot and resume from the durable record instead of
+persisting deltas as a second history.
+
+Prompt `contextWindow` budgeting is a pre-request decision over the assembled
+context. `AgentRun.usage` is cumulative measured/provider-reported execution
+evidence across attempts and compaction. They answer different questions and
+must not be substituted for each other. TTFT and throughput require timestamps
+from the actual provider stream plus a provider-reported or tokenizer-measured
+token count; character counts cannot produce exact token or throughput figures.
+
 `recordIds` is optional. Supply stable application record IDs when an accepted-response transport must
 return durable placeholders before the run finishes. `ticket.admission` resolves after the store
 acceptance CAS and reports the canonical committed `input`, assigned `run`, a typed `pending`
@@ -3945,6 +3989,47 @@ recovery queries active run states directly instead of maintaining a second proj
 An admission receipt retains its canonical input, and a terminal run retains its canonical
 assistant, so physical product-history compaction cannot break idempotent retries.
 
+### Built-in SQLite persistence
+
+Use the runtime-specific leaf; the neutral agent runtime never imports either
+SQLite built-in:
+
+```ts
+// Bun
+import { createBunSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/bun'
+
+const sqlite = createBunSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })
+const runtime = createAgentRuntime({ ...config, store: sqlite.store })
+
+await runtime.close()
+await sqlite.close()
+```
+
+```ts
+// Node 22.5+
+import { createNodeSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/node'
+
+const sqlite = createNodeSqliteAgentRuntimeStore({ filename: './agent-runtime.sqlite' })
+```
+
+Initialization creates only `stitchkit_agent_runtime_*` tables and records
+schema version 1 in `stitchkit_agent_runtime_meta`; it does not use
+`PRAGMA user_version` or mutate application tables. An unknown schema version or
+unversioned partial Stitchkit schema is refused. The connection is owned by the
+returned handle and closes only after accepted operations drain.
+
+Each handle serializes its transactions. Separate connections use
+`busy_timeout = 0`: a competing synchronous writer fails promptly with
+SQLite's lock error, so an awaited transaction can resume and commit or roll
+back. Retry that explicit error with an application-owned bounded policy; do
+not configure a blocking busy timeout on the same JavaScript thread.
+
+The adapter proves canonical durability across reopen and process restart. It
+does not make external tool effects exactly once, join application projections
+atomically or replace an application outbox. If a product row must commit with
+an agent transition, implement `AgentRuntimeStoreDriver` over the application's
+own transaction boundary instead.
+
 ## Durable order
 
 `acceptInputAndAssignRun` is one atomic operation. It is followed by ownership
@@ -11697,6 +11782,33 @@ Use this entrypoint from client components and shared DTO packages. The full
 | `openRouterProvider` | function | isolated `@openrouter/ai-sdk-provider` language-model factory |
 | `OpenRouterProviderSettings` | _type_ | official provider settings accepted by the factory |
 
+## `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 v1 and return `{ store, 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 |
+| `AgentRuntimeSqliteDatabase` / `AgentRuntimeSqliteStatement` / `AgentRuntimeSqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` | _type_ | durable store handle, owned connection lifecycle and initialization policy |
+
+## `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 v1 and return `{ store, 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 |
+| `AgentRuntimeSqliteDatabase` / `AgentRuntimeSqliteStatement` / `AgentRuntimeSqliteValue` | _type_ | minimal runtime-neutral synchronous SQLite boundary |
+| `SqliteAgentRuntimeStore` / `SqliteAgentRuntimeStoreConfig` | _type_ | durable store handle, owned connection lifecycle and initialization policy |
+
 ## `stitchkit/observability`
 
 Server-only. The audit layer one level above the raw hooks — W3C trace context,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.7",
+  "version": "0.68.8",
   "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",
@@ -92,6 +92,14 @@
       "types": "./dist/agent-runtime-openrouter.d.ts",
       "import": "./dist/agent-runtime-openrouter.js"
     },
+    "./agent-runtime/sqlite/bun": {
+      "types": "./dist/agent-runtime-sqlite-bun.d.ts",
+      "import": "./dist/agent-runtime-sqlite-bun.js"
+    },
+    "./agent-runtime/sqlite/node": {
+      "types": "./dist/agent-runtime-sqlite-node.d.ts",
+      "import": "./dist/agent-runtime-sqlite-node.js"
+    },
     "./application": {
       "types": "./dist/application.d.ts",
       "import": "./dist/application.js"
@@ -127,7 +135,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",