stitchkit 0.64.0 → 0.65.1

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-b1k33127.js";
+} from "./index-sbkyvacf.js";
 import {
   createApplication
 } from "./index-eabpd4tb.js";
@@ -308,11 +308,72 @@ async function runAgentStoreConformance(config) {
     createdAt: "2026-08-22T00:00:00.000Z",
     updatedAt: "2026-08-22T00:00:02.000Z"
   });
+  if (checkpointedRun.fencingToken === undefined) {
+    throw new Error("Acquisition must persist a fencing token the store can read back");
+  }
+  const staleFence = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "conformance-owner",
+    fencingToken: checkpointedRun.fencingToken + 1,
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [{ type: "text", text: "stale fence" }],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.500Z"
+    })
+  });
+  if (staleFence.outcome !== "conflict") {
+    throw new Error("A checkpoint with a stale fencing token must conflict");
+  }
+  const foreignOwner = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "a-different-runtime",
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [{ type: "text", text: "foreign owner" }],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.700Z"
+    })
+  });
+  if (foreignOwner.outcome !== "conflict") {
+    throw new Error("A checkpoint from another owner must conflict");
+  }
+  const recoverable = await store.scanRecoverable({ limit: 10 });
+  if (!recoverable.items.some((item) => item.run.id === running.id)) {
+    throw new Error("A running run must appear in a recoverable scan");
+  }
+  const interrupted = await store.requestRunInterrupt({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision
+  });
+  requireOutcome(interrupted, "applied");
+  const interruptedRun = interrupted.snapshot.runs.find((run) => run.id === running.id);
+  if (interruptedRun?.state !== "interrupt_requested") {
+    throw new Error("A durable interrupt must move the run to interrupt_requested");
+  }
+  if (interruptedRun.usage?.cost?.value !== 0.25) {
+    throw new Error("An interrupt must not discard the figure the run had already spent");
+  }
   const terminalResults = await Promise.all([
     store.commitRunTerminal({
       conversationId,
       runId: running.id,
-      expectedRevision: checkpointedRun.revision,
+      expectedRevision: interruptedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
       reason: "success",
@@ -325,7 +386,7 @@ async function runAgentStoreConformance(config) {
     store.commitRunTerminal({
       conversationId,
       runId: running.id,
-      expectedRevision: checkpointedRun.revision,
+      expectedRevision: interruptedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
       reason: "success",

package/llms-full.txt

@@ -58,7 +58,7 @@ own, recorded as an ADR.
 | `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` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 7 of the 9 minors since 0.56.2, most recently 0.64.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 8 of the 10 minors since 0.56.2, most recently 0.65.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/application` | server | evolving | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
@@ -3496,7 +3496,9 @@ mechanics: durable acceptance, history projection, the AI SDK stream loop,
 checkpoints, keyed interruption, terminal commit and stable application events.
 
 If the application already owns that loop, continue importing `mountAgent` from
-`stitchkit/tools`. Neither path depends on the other at runtime.
+`stitchkit/tools`. `stitchkit/tools` does not depend on this entrypoint at all;
+this entrypoint uses the tool executor from it, but pulls no MCP peer, so
+choosing `mountAgent` alone costs you nothing from here.
 
 ## Install
 
@@ -3504,6 +3506,13 @@ If the application already owns that loop, continue importing `mountAgent` from
 bun add stitchkit ai zod
 ```
 
+`mountAgent` from `stitchkit/tools` — used in the composition below — additionally
+needs the MCP peer, which that entrypoint imports statically:
+
+```sh
+bun add @modelcontextprotocol/server
+```
+
 OpenRouter is isolated so other runtime users do not resolve its package:
 
 ```sh
@@ -3543,7 +3552,7 @@ const models = defineModelRegistry({
   },
 })
 
-const prompt = composeAgentPrompt([
+const prompt = composeAgentPrompt<{ userId: string }>([
   {
     name: 'product',
     stability: 'stable',
@@ -3674,15 +3683,15 @@ input + queued run → running → execution settled → terminal CAS → succes
 
 ## What happens to a run when new input arrives
 
-`runs.inputPolicy` decides. It takes three values (or a function returning one);
-the fourth row below is a behaviour it deliberately does not offer yet:
+`runs.inputPolicy` decides. It takes three values, or a function returning one;
+the fourth row is a behaviour that shipped and was withdrawn:
 
 | policy | the run in flight | what it already produced |
 |--------|-------------------|--------------------------|
 | `queue` (default) | finishes first | kept |
 | `interrupt` | ends | kept, and marked as cut off |
 | `supersede` | ends | discarded from the prompt, kept in the record |
-| `inject` | continues | kept — it takes the new input at a step boundary |
+| _inject_ | continues | withdrawn in 0.65.0 — see below |
 
 `interrupt` and `supersede` differ in exactly one thing, and the question that
 picks between them is **not** "was the run interrupted" but **"did anyone see
@@ -3766,37 +3775,19 @@ const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
 process-local escape hatch chooses the reason, so a caller that knows the answer
 was never delivered can discard it without a newer input arriving.
 
-### The one that ends nothing
-
-**`inject`** hands the input to the loop between tool calls and lets the run keep
-going. It is right when the input *refines* rather than redirects — a correction
-arriving while a multi-step task is halfway through, where discarding the
-finished steps would be pure loss.
-
-It queues like `queue`, and a run already in flight takes it on at its next step
-boundary. That ordering is the whole design: the tempting shape, attaching a new
-input straight to a running run, has a loss case with no honest answer, because
-the run may terminate before the loop reaches a boundary and the input would then
-be recorded as answered by a turn that never saw it. Queue first and absorb
-opportunistically, and the fallback is simply that the successor runs — the
-behaviour every other policy already has.
-
-When a run does absorb one:
-
-- both inputs land in the answering run's `inputMessageIds`, so the durable
-  record matches what the model was actually asked;
-- both submissions' tickets resolve to the same terminal result;
-- the absorbed run is marked `absorbed` with `absorbedIntoRunId` pointing at the
-  run that answered. It is kept, not deleted — its admission receipt still points
-  at it, so a duplicate submission has to resolve to something. It leaves the
-  conversation snapshot, because a snapshot carries active runs plus those a
-  message references and an absorbed run never wrote an assistant message;
-- the next provider call carries the re-projected history. An application's own
-  `prepareStep` wins if it sets `messages` itself — it is the one that knows why.
-
-A step boundary is the only place this can happen: the provider is between calls,
-so the next request can carry the new message. A single-step run never reaches
-one, and its successor simply runs next.
+### The one that is not offered
+
+**inject** — hand the input to the loop between tool calls and let the run
+continue — shipped in 0.63.0 and was **withdrawn in 0.65.0**. It committed the
+absorption durably at a step boundary, before the answer existed, and everything
+downstream of that ordering was wrong: an accepted input could end up in a state
+that was neither active, recoverable nor terminal, so `close()` could report
+`settled: true` while leaving it permanently unanswerable, and a duplicate
+submission of the same idempotency key was refused forever.
+
+The redesign is tracked in the backlog and is not a patch to what shipped: the
+absorption has to commit atomically **with** the terminal record, so that a run
+which ends first simply leaves an ordinary queued successor behind.
 
 With `runs.coalescePending: true`, an active lane has at most one queued
 successor. Every later accepted input is atomically appended to that successor;
@@ -3918,8 +3909,16 @@ crash between the database commit and `publish`. Reconnect should load canonical
 state. Exactly-once external delivery remains an application-owned outbox.
 
 Durable event IDs are derived from run, event type and snapshot version. Use
-`advanceAgentRuntimeEventCursor` to classify accepted, duplicate and gap delivery; a gap triggers a
-snapshot reload. `createAgentRuntimeEventSink` adds a bounded failure-isolated lifecycle and typed
+`advanceAgentRuntimeEventCursor` to classify delivery.
+
+**`gap` is reported for transient events only**, where `sequence` is a per-run
+counter the runtime really does increment once per event. Durable events carry
+the *conversation's* version, which advances on every mutation including the many
+that publish nothing — checkpoints, compaction, an acceptance that has not
+started — so two consecutive durable events are routinely several versions apart
+and adjacency says nothing. A durable loss is not detectable from the cursor;
+reload on reconnect, which is what a bounded fire-and-forget sink asks of you
+anyway. `createAgentRuntimeEventSink` adds a bounded failure-isolated lifecycle and typed
 projection/redaction hook. `onPublishError` records direct publisher failures without changing the
 already committed run.
 
@@ -4046,9 +4045,33 @@ spent nothing, and an omitted object could not tell you which one you had.
 Two costs in different currencies do not add: the sum reports `unavailable`
 rather than picking a label. The core records a currency and never converts one.
 
-Usage is **not durable**. It reaches you on the operator and delivery event
-streams and in `AgentRuntimeResult.metrics`, and stitchkit writes no spend to the
-store — where a figure lives afterwards is the application's (→ ADR 0002).
+**A run's figure is durable, and that is where to read it when a channel loses
+it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
+record, so a crashed process leaves behind what it had already spent and a
+dropped event is not a lost number:
+
+```ts
+const snapshot = await store.loadSnapshot(conversationId)
+const spent = snapshot.runs.find((run) => run.id === runId)?.usage
+```
+
+Two gaps are open and are stated rather than left to be discovered:
+
+- **Both event sinks are bounded and drop under load**, by arrival order — the
+  event carrying the money is exactly as droppable as the one carrying nothing.
+  The run record is the recovery, and this paragraph is the only place that says
+  so.
+- **`AgentRuntimeResult.metrics` is `undefined` when this executor did not win
+  the terminal race.** Read `result.run.usage` — the durable figure — rather than
+  `result.metrics`, which is the channel that can go missing.
+- **Compaction spend is invisible unless you report it.** `config.history.compact`
+  calls a model inside the turn and produces no step and no event of its own.
+  Return `usage` from `AgentCompactionResult` and it joins the run's figure;
+  omit it and the run under-reports by whatever summarising cost.
+
+What stitchkit does **not** keep is a ledger: one figure, on the run that
+produced it, never aggregated and never reconciled against a provider invoice
+(→ ADR 0110).
 
 ### Reconciling with the provider's own accounting
 
@@ -4066,8 +4089,10 @@ The join is yours, and `runId` is the key:
 await ledger.record({
   runId: terminal.run.id,
   conversationId: terminal.run.conversationId,
-  costUsd: terminal.metrics?.usage?.cost?.value ?? null,   // null when `unavailable`
-  provenance: terminal.metrics?.usage?.cost?.provenance ?? 'unavailable',
+  // The durable figure, not `terminal.metrics` — that one is absent whenever
+  // this executor did not win the terminal race.
+  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
+  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
 })
 
 // later — the provider's accounting names the same generation
@@ -7819,6 +7844,81 @@ implement `AgentRuntimeStoreDriver` and compose the aggregate with
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.65.0
+
+The largest migration of the pre-1.0 line, and most of it is the compiler
+pointing at things. One item is a feature withdrawal and two change behaviour
+with no compile error at all.
+
+### A projection a provider accepts, and a policy withdrawn
+
+### If you compact, or use `system-note`, you were broken and now are not
+
+No code change to adopt the fix — but **check your own code if you call
+`projectAgentHistory` yourself.** System and summary records no longer appear in
+`messages`; they come back in `system` and belong in the provider's instructions
+channel, which is the only place `ai` accepts them:
+
+```ts
+// before — the provider refuses this outright
+const messages = await projectAgentHistory(snapshot.messages)
+streamText({ model, messages })
+
+// after
+const { messages, system } = await projectAgentHistoryDetailed(snapshot.messages)
+streamText({
+  model,
+  instructions: system.map((content) => ({ role: 'system', content })),
+  messages,
+})
+```
+
+If you use `createAgentRuntime`, this is handled for you.
+
+### `inputPolicy: 'inject'` is withdrawn
+
+```ts
+// before
+runs: { inputPolicy: 'inject' }
+// after
+runs: { inputPolicy: 'queue' }
+```
+
+`'absorbed'`, `AgentRun.absorbedIntoRunId` and `AgentRuntimeStore.absorbQueuedRun`
+go with it. A driver built on `AgentRuntimeStoreDriver` needs no change.
+
+### Records must agree with themselves
+
+If you construct `AgentRun` values — a store double, a fixture, a migration —
+derive the state instead of setting it:
+
+```ts
+// after
+import { runStateForTerminalReason } from 'stitchkit/agent-runtime'
+AgentRunSchema.parse({ …run, terminalReason: reason, state: runStateForTerminalReason(reason) })
+```
+
+A terminal state with no reason, a queued run carrying one, and `policy_stop`
+without a `terminalPolicyName` are now all refused at parse time.
+
+### Enum and field changes the compiler will point at
+
+- `AgentTerminalReason`: `'tool_failure'` removed (never produced),
+  `'context_overflow'` added — this runtime's own refusal when the prompt does
+  not fit, which used to report `provider_failure`.
+- `AgentRunState`: `'absorbed'` removed.
+- `AgentRunMetrics.usage` is required.
+- `AgentHistoryBudgetDecision['reason']`: `'superseded'` → `'unspeakable'`.
+
+### Two behaviour changes with no compile error
+
+- **`loop.idleTimeoutMs` now defaults to 60 000.** A run whose provider stream
+  goes quiet for a minute ends as `timeout` instead of holding the lane forever.
+  Pass `null` for the old behaviour, and think about why you want it.
+- **`advanceAgentRuntimeEventCursor` stops returning `gap` for durable events.**
+  If you reload a conversation on `gap`, you were reloading after essentially
+  every run. Transient events still report it, and there it is real.
+
 ## Released migration: 0.64.0
 
 Two changes, and only one of them can break a build. Nothing was removed.
@@ -10379,7 +10479,7 @@ Server-only optional application runtime. See the
 | `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
 | `AgentRuntimeAdmission` | _type_ | canonical committed input, assigned run, pending assistant projection, compatibility IDs and snapshot version |
 | `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
-| `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` distinguishes checkpoint from terminal totals |
+| `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` says the provider never reported the run finished, so the figure beside it is not a confirmed total |
 | `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with context resolver and explicit evidence policy |
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
@@ -10414,8 +10514,8 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRec
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
-`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AbsorbQueuedRun`, `AbsorbQueuedRunSchema`,
-`RecoverAgentRun`, `ReplaceCompactedRange`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `runStateForTerminalReason`,
+`ACTIVE_AGENT_RUN_STATES`, `RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
 `AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,

package/package.json

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