stitchkit 0.63.0 → 0.65.0

package/dist/{index-b1k33127.js → index-sbkyvacf.js}

@@ -99,7 +99,6 @@ var AgentRunStateSchema = z.enum([
   "completed",
   "interrupted",
   "superseded",
-  "absorbed",
   "failed",
   "cancelled",
   "abandoned"
@@ -114,9 +113,24 @@ var AgentTerminalReasonSchema = z.enum([
   "timeout",
   "shutdown",
   "provider_failure",
-  "tool_failure",
+  "context_overflow",
   "abandoned"
 ]);
+function runStateForTerminalReason(reason) {
+  if (reason === "success" || reason === "policy_stop" || reason === "provider_stop") {
+    return "completed";
+  }
+  if (reason === "interrupted")
+    return "interrupted";
+  if (reason === "superseded")
+    return "superseded";
+  if (reason === "cancelled" || reason === "shutdown" || reason === "timeout") {
+    return "cancelled";
+  }
+  if (reason === "abandoned")
+    return "abandoned";
+  return "failed";
+}
 var AgentUsageValueSchema = z.object({
   value: z.number().nonnegative().optional(),
   provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
@@ -134,7 +148,7 @@ var AgentUsageSchema = z.object({
   cacheWriteTokens: AgentUsageValueSchema.optional(),
   cost: AgentCostValueSchema.optional()
 });
-var AgentRunSchema = z.object({
+var AgentRunFieldsSchema = z.object({
   schemaVersion: z.literal(1),
   id: AgentRecordIdSchema,
   conversationId: AgentRecordIdSchema,
@@ -146,11 +160,45 @@ var AgentRunSchema = z.object({
   fencingToken: AgentRecordVersionSchema.optional(),
   terminalReason: AgentTerminalReasonSchema.optional(),
   terminalPolicyName: z.string().min(1).optional(),
-  absorbedIntoRunId: AgentRecordIdSchema.optional(),
   usage: AgentUsageSchema.optional(),
   createdAt: AgentTimestampSchema,
   updatedAt: AgentTimestampSchema
 });
+var AgentRunSchema = AgentRunFieldsSchema.superRefine((run, ctx) => {
+  if (run.terminalReason === undefined) {
+    if (TERMINAL_RUN_STATES.has(run.state)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["terminalReason"],
+        message: `A run in terminal state "${run.state}" must say why it ended`
+      });
+    }
+    return;
+  }
+  const expected = runStateForTerminalReason(run.terminalReason);
+  if (run.state !== expected) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["state"],
+      message: `Terminal reason "${run.terminalReason}" ends a run in state "${expected}", not "${run.state}"`
+    });
+  }
+  if (run.terminalReason === "policy_stop" && run.terminalPolicyName === undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["terminalPolicyName"],
+      message: "A policy stop names the policy that stopped the run"
+    });
+  }
+});
+var TERMINAL_RUN_STATES = new Set([
+  "completed",
+  "interrupted",
+  "superseded",
+  "cancelled",
+  "abandoned",
+  "failed"
+]);
 var AgentSnapshotSchema = z.object({
   schemaVersion: z.literal(1),
   conversationId: AgentRecordIdSchema,
@@ -160,9 +208,9 @@ var AgentSnapshotSchema = z.object({
 });
 var AgentRunMetricsSchema = z.object({
   partial: z.boolean(),
-  usage: AgentUsageSchema.optional(),
+  usage: AgentUsageSchema,
   durationMs: z.number().nonnegative().optional(),
   ttftMs: z.number().nonnegative().optional()
 });
 
-export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentTerminalReasonSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunSchema, AgentSnapshotSchema, AgentRunMetricsSchema };
+export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentTerminalReasonSchema, runStateForTerminalReason, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunSchema, AgentSnapshotSchema, AgentRunMetricsSchema };

package/dist/testing/agent-store-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CA4Sf"}
+{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CAiXf"}

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 | 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
@@ -7763,6 +7788,24 @@ additive** — adopting it changes nothing in your code. (See
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Before you bump, if you implement an agent store
+
+One step, and it is mechanical. If your project has an `AgentRuntimeStore` — a
+Prisma adapter, an in-memory one, anything — run the conformance kit against it
+**on the version you are leaving**, then again after the bump:
+
+```ts
+import { runAgentStoreConformance } from 'stitchkit/testing'
+
+await runAgentStoreConformance({ store: yourStore, conversationId: 'conformance' })
+```
+
+Green before and red after tells you the contract grew and where, in one run,
+instead of one failure at a time in production. Green both times means the
+upgrade owes you nothing on that surface — which is the usual answer if you
+implement `AgentRuntimeStoreDriver` and compose the aggregate with
+`createAgentRuntimeStore(driver)`, the supported shape (→ ADR 0111).
+
 ## Flow (agent or human)
 
 1. **Find the current version.** In the consumer: the resolved `stitchkit` in
@@ -7801,6 +7844,122 @@ current one *up to* your target, and apply each snippet.
    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.
+
+### An event that says which kind it is
+
+### Narrow `AgentRunEvent` on `type`
+
+```ts
+// before
+for (const event of events) record(event.usage?.cost?.value ?? 0)
+
+// after — and the compiler will point at every site
+for (const event of events) {
+  if (event.type !== 'run-terminal') continue
+  record(event.usage.cost.value ?? null)   // `usage` is present; unknown says so
+}
+```
+
+`step` is now required on `step-finished`, `terminalReason` on `run-terminal`,
+and `usage` on both. `queueWaitMs` exists only on `run-started`. Nothing was
+removed — the fields that were optional because a *different* kind of event
+lacked them are now simply on the kinds that have them.
+
+Import `AgentRunTerminalEventSchema` (or the sibling schemas) if you construct
+events in tests.
+
+### If you implement `AgentRuntimeStore` directly, move to the driver
+
+Not urgent and nothing breaks today — but the aggregate is no longer the
+supported target, so its future growth will not be announced as breaking
+(→ ADR 0111). The supported shape is one line:
+
+```ts
+const driver: AgentRuntimeStoreDriver<TransactionClient> = { /* six primitives */ }
+export const store = createAgentRuntimeStore(driver)
+```
+
+Run `runAgentStoreConformance` against your adapter before and after any bump —
+see *Before you bump, if you implement an agent store* above.
+
 ## Released migration: 0.63.0
 
 Four changes to what a running system reports and how an input reaches a run
@@ -10320,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 |
@@ -10355,8 +10514,7 @@ 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`, `RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
 `AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
@@ -10391,6 +10549,8 @@ snapshot reload; the bounded sink isolates transport failure and supports a type
 
 Managed effects and operator telemetry additionally export `AgentToolFenceConfig`,
 `AgentToolFenceContext`, `AgentObservability`, `AgentRunEvent`, `AgentRunEventSchema`,
+`AgentRunStartedEvent`, `AgentRunStartedEventSchema`, `AgentStepFinishedEvent`,
+`AgentStepFinishedEventSchema`, `AgentRunTerminalEvent`, `AgentRunTerminalEventSchema`,
 `AgentRunSinkConfig`, `AgentRunSinkDrop` and `AgentRunSinkError`. A monotonic run `fencingToken`
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.

package/package.json

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