stitchkit 0.68.7 → 0.68.9

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` |
@@ -3530,6 +3533,36 @@ const exportOperation = defineAsyncOperation({
 const runtimeTools = exportOperation.runtimeTools
 ```
 
+#### Durable application-owned execution
+
+The executable reference
+[`durable-async-operation-harness.ts`](../../packages/core/examples/durable-async-operation-harness.ts)
+shows the complete boundary behind that surface. It composes
+`defineAsyncOperationContract`, `defineAsyncOperation`, `createApplication`,
+`createBoundedAdmission`, managed shutdown and `createAgentToolFenceLifecycle`
+around an injected store and provider.
+
+The store transactionally owns the idempotency key **and normalized request
+hash**. Reusing both returns the existing operation; reusing the key with a
+different hash conflicts. Every mutation is an expected-revision CAS. Before an
+external call, the application persists a unique attempt/effect key and marks
+the dispatch `possibly-dispatched`; a lost response is therefore reconciled by
+that key after restart and is never treated as permission to submit the effect
+again. Provider acknowledgement, progress, cancellation intent, result and
+artifact references remain durable application state.
+
+Agent tool fencing and operation idempotency are separate guarantees. The fence
+prevents a stale run owner from crossing an effect boundary; the transactional
+idempotency record makes a repeated current call converge on one operation.
+Neither replaces the other.
+
+Stitchkit deliberately does **not** own the durable queue, operation database,
+lease renewal, provider retry/reconciliation protocol, asset catalog or domain
+states. The process-local application resource stops admission and drains
+accepted work; unresolved durable records survive shutdown for the next
+recovery pass. The packed consumer lane executes this composition from the
+published package on Bun and Node.
+
 Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
 `wait` only stops waiting and never calls optional domain `cancel`.
 
@@ -3730,7 +3763,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 +3918,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 +4019,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
@@ -4263,6 +4378,43 @@ These are post-commit notifications, not a transactional outbox: a process can
 crash between the database commit and `publish`. Reconnect should load canonical
 state. Exactly-once external delivery remains an application-owned outbox.
 
+### External channel ingress and delivery
+
+The executable
+[`external-channel-harness.ts`](../../packages/core/examples/external-channel-harness.ts)
+is the reference composition for webhooks, polling transports and local-device
+adapters. Its generic boundary injects a runtime, durable store and delivery
+adapter; the optional
+[`external-channel-grammy.ts`](../../packages/core/examples/external-channel-grammy.ts)
+attaches the same ingress function to grammY polling or webhook lifecycle
+without putting provider types in the agent runtime.
+
+Inbound update identity, principal resolution, conversation mapping and reply
+target are application policy. Persist and deduplicate the update before
+`runtime.submit`, use the stored idempotency key on crash recovery, then persist
+the admitted `runId`. A duplicate arriving after restart resolves to that same
+mapping instead of creating another model turn.
+
+For output, choose `terminal-only` or `streaming` explicitly. Stable durable
+`eventId` values and transient `(runtimeEpoch, sequence)` identities become
+outbox keys; the application store assigns causal ordinals. A bounded channel
+is only a process-local wakeup and never the durable authority. Before sending,
+persist one of these states:
+
+| State | Recovery action |
+| --- | --- |
+| `not-dispatched` | may dispatch once |
+| `possibly-dispatched` | reconcile with the adapter or remain unresolved |
+| `acknowledged` | deduplicate; delivery is complete |
+
+The agent `terminal` event and the adapter's delivery receipt are intentionally
+different records. A successful run does not prove that a reply reached its
+channel, and a delivery failure never rewrites the canonical agent result.
+Shutdown stops ingress, drains accepted process-local work and leaves ambiguous
+outbox records visible for a later reconciliation pass. Stitchkit does not own
+a channel database, durable broker, provider payload schema or application
+identity policy.
+
 Durable event IDs are derived from run, event type and snapshot version. Use
 `advanceAgentRuntimeEventCursor` to classify delivery.
 
@@ -11561,7 +11713,7 @@ Server-only optional application runtime. See the
 | `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 |
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
-| `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
+| `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent`; compose beside application idempotency for [durable operations](../guide/mcp-and-agents.md#durable-application-owned-execution) |
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
@@ -11697,6 +11849,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,
@@ -11923,8 +12102,8 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
 | `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
 | `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
-| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions |
-| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities |
+| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions; see the [durable application-owned recipe](../guide/mcp-and-agents.md#durable-application-owned-execution) |
+| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities; execution and recovery remain application-owned |
 | `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
 | `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
 | `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.7",
+  "version": "0.68.9",
   "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",