stitchkit 0.65.0 → 0.66.0

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

@@ -114,6 +114,7 @@ var AgentTerminalReasonSchema = z.enum([
   "shutdown",
   "provider_failure",
   "context_overflow",
+  "absorbed",
   "abandoned"
 ]);
 function runStateForTerminalReason(reason) {
@@ -122,7 +123,7 @@ function runStateForTerminalReason(reason) {
   }
   if (reason === "interrupted")
     return "interrupted";
-  if (reason === "superseded")
+  if (reason === "superseded" || reason === "absorbed")
     return "superseded";
   if (reason === "cancelled" || reason === "shutdown" || reason === "timeout") {
     return "cancelled";
@@ -131,14 +132,31 @@ function runStateForTerminalReason(reason) {
     return "abandoned";
   return "failed";
 }
+var AgentProvenanceSchema = z.enum([
+  "provider-reported",
+  "measured",
+  "computed",
+  "estimated",
+  "unavailable"
+]);
 var AgentUsageValueSchema = z.object({
-  value: z.number().nonnegative().optional(),
-  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
+  value: z.int().nonnegative().optional(),
+  provenance: AgentProvenanceSchema.extract([
+    "provider-reported",
+    "computed",
+    "estimated",
+    "unavailable"
+  ])
 });
 var AgentCostValueSchema = z.object({
   value: z.number().nonnegative().optional(),
   currency: z.string().length(3).optional(),
-  provenance: z.enum(["provider-reported", "computed", "estimated", "unavailable"])
+  provenance: AgentProvenanceSchema.extract([
+    "provider-reported",
+    "computed",
+    "estimated",
+    "unavailable"
+  ])
 });
 var AgentUsageSchema = z.object({
   inputTokens: AgentUsageValueSchema,
@@ -160,11 +178,19 @@ var AgentRunFieldsSchema = 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 !== "absorbed" && run.absorbedIntoRunId !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["absorbedIntoRunId"],
+      message: "Only an absorbed run names the run that answered it"
+    });
+  }
   if (run.terminalReason === undefined) {
     if (TERMINAL_RUN_STATES.has(run.state)) {
       ctx.addIssue({
@@ -190,6 +216,20 @@ var AgentRunSchema = AgentRunFieldsSchema.superRefine((run, ctx) => {
       message: "A policy stop names the policy that stopped the run"
     });
   }
+  if (run.terminalReason === "absorbed" && run.absorbedIntoRunId === undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["absorbedIntoRunId"],
+      message: "An absorbed run names the run that answered its input"
+    });
+  }
+  if (run.absorbedIntoRunId === run.id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["absorbedIntoRunId"],
+      message: "A run cannot absorb itself"
+    });
+  }
 });
 var TERMINAL_RUN_STATES = new Set([
   "completed",
@@ -213,4 +253,4 @@ var AgentRunMetricsSchema = z.object({
   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, runStateForTerminalReason, 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, AgentProvenanceSchema, 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,CAiXf"}
+{"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,CAobf"}

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-sbkyvacf.js";
+} from "./index-fhsmrzj7.js";
 import {
   createApplication
 } from "./index-eabpd4tb.js";
@@ -352,6 +352,50 @@ async function runAgentStoreConformance(config) {
   if (foreignOwner.outcome !== "conflict") {
     throw new Error("A checkpoint from another owner must conflict");
   }
+  const liveView = await store.loadRun({ conversationId, runId: running.id });
+  if (!liveView)
+    throw new Error("loadRun must find a run of this conversation");
+  if (liveView.run.id !== running.id || liveView.run.conversationId !== conversationId) {
+    throw new Error("loadRun returned a run it was not asked for");
+  }
+  if (liveView.run.revision !== checkpointedRun.revision) {
+    throw new Error("loadRun must return the run as the last mutation left it");
+  }
+  if (liveView.run.usage?.cost?.value !== 0.25) {
+    throw new Error("loadRun must carry the figure the run has spent so far");
+  }
+  if (liveView.snapshotVersion !== checkpoint.snapshot.version) {
+    throw new Error("loadRun must report the conversation version it read at");
+  }
+  if (liveView.assistant !== undefined) {
+    throw new Error("loadRun must not report a terminal answer for a live run");
+  }
+  if (await store.loadRun({ conversationId, runId: "no-such-run" })) {
+    throw new Error("loadRun must return undefined for an unknown run");
+  }
+  if (await store.loadRun({ conversationId: "no-such-conversation", runId: running.id })) {
+    throw new Error("loadRun must not cross conversation boundaries");
+  }
+  const activeRuns = await store.listActiveRuns(conversationId);
+  if (!activeRuns.some((run) => run.id === running.id)) {
+    throw new Error("listActiveRuns must report a run that is in flight");
+  }
+  if (activeRuns.some((run) => run.terminalReason !== undefined)) {
+    throw new Error("listActiveRuns must not report a run that has ended");
+  }
+  for (let index = 1;index < activeRuns.length; index += 1) {
+    const previous = activeRuns[index - 1];
+    const current = activeRuns[index];
+    if (!previous || !current)
+      continue;
+    const ordered = previous.createdAt === current.createdAt ? previous.id.localeCompare(current.id) < 0 : previous.createdAt < current.createdAt;
+    if (!ordered) {
+      throw new Error("listActiveRuns must order by createdAt and then by id");
+    }
+  }
+  if ((await store.listActiveRuns("no-such-conversation")).length !== 0) {
+    throw new Error("listActiveRuns must be empty for an unknown conversation");
+  }
   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");
@@ -409,6 +453,16 @@ async function runAgentStoreConformance(config) {
   if (settledRun?.usage?.cost?.value !== 1.5) {
     throw new Error("Terminal commit did not persist the run usage it was given");
   }
+  const terminalView = await store.loadRun({ conversationId, runId: running.id });
+  if (terminalView?.run.terminalReason !== "success") {
+    throw new Error("loadRun must report the terminal reason a settled run ended with");
+  }
+  if (JSON.stringify(terminalView.assistant) !== JSON.stringify(terminalAssistant)) {
+    throw new Error("loadRun must retain the answer a settled run produced");
+  }
+  if ((await store.listActiveRuns(conversationId)).some((run) => run.id === running.id)) {
+    throw new Error("listActiveRuns must drop a run once it has ended");
+  }
   const compactedTerminal = await store.replaceCompactedRange({
     conversationId,
     expectedVersion: terminalApplied.snapshot.version,
@@ -468,6 +522,100 @@ async function runAgentStoreConformance(config) {
   if (terminalRun?.state !== "abandoned" || terminalMessage?.status !== "failed") {
     throw new Error("Abandon recovery did not atomically terminalize its assistant record");
   }
+  await assertAbsorptionIsAtomic(store);
+}
+async function assertAbsorptionIsAtomic(store) {
+  const conversationId = `conformance-absorb-${crypto.randomUUID()}`;
+  const leadInput = userMessage(conversationId, "absorb-input-1");
+  const leadRun = queuedRun(conversationId, leadInput.id, "absorb-run-1");
+  const lead = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-1",
+    input: leadInput,
+    run: leadRun
+  });
+  requireOutcome(lead, "applied");
+  const successorInput = userMessage(conversationId, "absorb-input-2");
+  const successorRun = queuedRun(conversationId, successorInput.id, "absorb-run-2");
+  const successor = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-2",
+    input: successorInput,
+    run: successorRun
+  });
+  requireOutcome(successor, "applied");
+  const acquired = await store.acquireRun({
+    conversationId,
+    runId: leadRun.id,
+    expectedRevision: 0,
+    ownerId: "absorb-owner"
+  });
+  requireOutcome(acquired, "applied");
+  const running = acquired.snapshot.runs.find((run) => run.id === leadRun.id);
+  if (!running)
+    throw new Error("Absorbing run disappeared after acquisition");
+  const answer = AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id: running.assistantMessageId,
+    conversationId,
+    runId: running.id,
+    role: "assistant",
+    status: "completed",
+    parts: [{ type: "text", text: "answered both" }],
+    createdAt: "2026-08-26T00:00:00.000Z",
+    updatedAt: "2026-08-26T00:00:02.000Z"
+  });
+  await store.commitRunTerminal({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "absorb-owner",
+    assistant: AgentMessageSchema.parse({ ...answer, status: "interrupted" }),
+    reason: "interrupted",
+    absorb: [{ runId: successorRun.id, inputMessageIds: [successorInput.id] }]
+  }).then(() => {
+    throw new Error("A non-completing run absorbed a queued successor");
+  }, (error) => {
+    if (!(error instanceof TypeError))
+      throw error;
+  });
+  const committed = await store.commitRunTerminal({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "absorb-owner",
+    assistant: answer,
+    reason: "success",
+    absorb: [{ runId: successorRun.id, inputMessageIds: [successorInput.id] }]
+  });
+  requireOutcome(committed, "applied");
+  const absorbingView = await store.loadRun({ conversationId, runId: leadRun.id });
+  if (absorbingView?.run.inputMessageIds.join(",") !== "absorb-input-1,absorb-input-2") {
+    throw new Error("An absorbing run must record the inputs it answered");
+  }
+  const absorbedView = await store.loadRun({ conversationId, runId: successorRun.id });
+  if (absorbedView?.run.terminalReason !== "absorbed") {
+    throw new Error("An absorbed successor must be terminal in the same transaction");
+  }
+  if (absorbedView.run.absorbedIntoRunId !== leadRun.id) {
+    throw new Error("An absorbed run must name the run that answered its input");
+  }
+  if (absorbedView.assistant !== undefined) {
+    throw new Error("An absorbed run produced no answer and must retain none");
+  }
+  if ((await store.listActiveRuns(conversationId)).length !== 0) {
+    throw new Error("An absorbed successor must leave the active listing");
+  }
+  const retried = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-2",
+    input: userMessage(conversationId, "absorb-discarded"),
+    run: queuedRun(conversationId, "absorb-discarded", "absorb-discarded-run")
+  });
+  requireOutcome(retried, "duplicate");
+  if (retried.runId !== leadRun.id || retried.assistant?.id !== answer.id) {
+    throw new Error("A retried absorbed key must resolve to the run that answered it");
+  }
+  if (retried.inputMessageId !== successorInput.id) {
+    throw new Error("A retried absorbed key must still name its own input");
+  }
 }
 // src/testing/managed-resource-conformance-contract.ts
 import { z } from "zod";

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 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` | server | evolving<br>_redefined in 9 of the 11 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/application` | server | evolving | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
@@ -3683,15 +3683,14 @@ 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 is a behaviour that shipped and was withdrawn:
+`runs.inputPolicy` decides. It takes four values, or a function returning one:
 
 | policy | the run in flight | what it already produced |
 |--------|-------------------|--------------------------|
 | `queue` (default) | finishes first | kept |
+| `inject` | continues, and answers the new input too | kept, and built on |
 | `interrupt` | ends | kept, and marked as cut off |
 | `supersede` | ends | discarded from the prompt, kept in the record |
-| _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
@@ -3775,19 +3774,53 @@ 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 is not offered
+### An input that joins a run in flight
+
+`inject` is right when the new input **refines** rather than redirects, and the
+steps already taken are still worth something: *"summarise this thread… actually,
+in bullet points"* should not throw away the reading the first message paid for.
+
+What happens:
+
+1. The input is admitted exactly like any other — a committed user message and a
+   **queued run**, durable before anything else happens.
+2. At the running loop's next step boundary, that input joins its prompt. Only
+   that input: an unrelated queued submission is never carried in.
+3. When the run finishes, its terminal commit — **one transaction** — records
+   the input as one the run answered and settles the queued successor with
+   `terminalReason: 'absorbed'` and `absorbedIntoRunId` naming the run that
+   answered it. Every ticket for that successor resolves to the same answer.
+
+Nothing durable happens between 1 and 3, and that is the design (→ ADR 0113).
+A run that crashes, is closed, or is interrupted after taking an input on
+commits no absorption at all, so what is left behind is an ordinary queued
+successor — the state every other policy already produces and recovery already
+handles. **There is no ordering in which an accepted input becomes
+unanswerable.** Only a run that *completes* may absorb; an interrupted one took
+the input into its prompt and then stopped, and does not get to say it answered
+it.
+
+An absorbed run has **no assistant message of its own** — it produced none, and
+writing an empty one would be a record claiming otherwise. Its answer is
+reachable through `absorbedIntoRunId`, and the store follows that pointer itself
+when a submission arrives on the absorbed run's idempotency key, so a retry
+after a restart returns the answer rather than an empty terminal record.
 
-**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.
+It does publish one more `run-state` event, carrying `'superseded'`. It never
+enters the run executor, so that event is the only thing that tells a delivery
+surface following its `runId` that it is no longer queued.
 
-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 `coalescePending`, one successor can carry several inputs, and an
+absorption covers a successor **whole or not at all** — a partial one would
+leave a terminal run with inputs nobody answered. Inputs that coalesce before
+the absorbing run's last step boundary join the same absorption. One that
+arrives after it cancels the absorption: the successor then answers all of its
+inputs itself, and the absorbing run has answered one of them too. A duplicate
+answer, never a missing one.
+
+(0.63.0 shipped a version of this that committed the absorption at the step
+boundary, before the answer existed, and it was withdrawn in 0.65.0. ADR 0113
+records what that ordering broke.)
 
 With `runs.coalescePending: true`, an active lane has at most one queued
 successor. Every later accepted input is atomically appended to that successor;
@@ -3850,7 +3883,7 @@ problem, and omitting a run's cost is an operator's.
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
-implement the smaller `AgentRuntimeStoreDriver` rather than these nine members:
+implement the smaller `AgentRuntimeStoreDriver` rather than these eleven members:
 
 - `acceptInputAndAssignRun`
 - `acquireRun`
@@ -3859,11 +3892,37 @@ implement the smaller `AgentRuntimeStoreDriver` rather than these nine members:
 - `recoverRun`
 - `commitRunTerminal`
 - `replaceCompactedRange`
-- `loadSnapshot`
+- `loadSnapshot` — the whole conversation; see **Reading a conversation** below
+- `loadRun` — one run by id, with the answer it produced if it has ended
+- `listActiveRuns` — the runs of one conversation that have not ended
 - `scanRecoverable` — one **bounded page** of recoverable runs; `recover()`
   calls this and nothing else, so an adapter that implements the interface has
   everything recovery needs
 
+### Reading a conversation
+
+Two shapes of read, and the difference matters as a conversation grows.
+
+**Bounded.** `loadRun` and `listActiveRuns` read run records and the
+conversation head. Neither touches history, so neither grows with the length of
+the conversation. `loadRun` is how you resolve the `runId` that
+`submit().admission` hands back — it returns the run, the version it was read
+at, and, once the run is terminal, the answer it produced.
+
+**Unbounded.** `loadSnapshot` returns every message and every run, and so does
+every mutation result: the store's reducer validates its invariants against the
+whole conversation, and the runtime builds the next prompt from the snapshot the
+mutation returns. Ask for it when you need the conversation — composing a
+prompt, or compacting — and not to look one run up.
+
+So the cost of a run scales with the length of its conversation, not with the
+length of the turn. **Configure compaction** (see below) for anything
+long-running: it is the only thing in the framework that makes a conversation
+smaller, and without it a year-old assistant thread is read in full on every
+turn. This is a known limit, held deliberately rather than by omission — paged
+history would have to change what a snapshot *is*, and the store's invariants
+with it, and that is a decision on its own (→ ADR 0112).
+
 Every mutation carries an expected run revision or snapshot version. Input
 assignment additionally carries an idempotency identity. A conflict is a
 control outcome; stale data is never silently overwritten.
@@ -7844,6 +7903,149 @@ 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.66.0
+
+Three changes, and only one of them is a feature. The other two are shapes that
+would have had to break later: a vocabulary that described one fact with two
+words, and a store whose only read was the whole conversation.
+
+The compiler points at most of it. Two things change with no compile error —
+what a **total** says about its own provenance, and the fact that token counts
+are now validated where they were not.
+
+### An input that joins a run in flight
+
+#### If you matched exhaustively on `AgentTerminalReason`
+
+`'absorbed'` is new. A run ends this way when a run already in flight took its
+input on and answered it; its state is `'superseded'`, and `absorbedIntoRunId`
+names the run that has the answer.
+
+```ts
+// after
+switch (run.terminalReason) {
+  // …
+  case 'absorbed':
+    // no assistant message of its own — follow run.absorbedIntoRunId
+    break
+}
+```
+
+A run record with `terminalReason: 'absorbed'` and no `absorbedIntoRunId` is
+refused at parse time, and so is `absorbedIntoRunId` on any other reason.
+
+#### If you render or export runs
+
+An absorbed run has **no assistant message**. Anything that assumes "every
+terminal run has one" needs the `absorbed` case — the answer is on the run
+`absorbedIntoRunId` names, and `store.loadRun` resolves it.
+
+#### If you want the policy
+
+```ts
+// after
+runs: { inputPolicy: 'inject' }
+```
+
+It was withdrawn in 0.65.0 and is back with the ordering corrected: the
+absorption commits with the terminal record, not at the step boundary. Read
+*An input that joins a run in flight* in the agent-runtime guide before turning
+it on — in particular what happens when the absorbing run does not complete, and
+how it composes with `coalescePending`.
+
+#### If you implement a store driver
+
+Nothing to do, but know what changed underneath: one terminal commit can now
+save **two** run records, and they must land in the same transaction. A driver
+that persists one of the pair fails `runAgentStoreConformance`.
+
+### A run read without its conversation
+
+#### If you implement `AgentRuntimeStore` by hand
+
+Two members to add. **If your adapter is an `AgentRuntimeStoreDriver` passed to
+`createAgentRuntimeStore`, there is nothing to do** — the driver already had
+everything both need.
+
+```ts
+// after
+loadRun(input: { conversationId: string; runId: string }): Promise<AgentRunView | undefined>
+listActiveRuns(conversationId: string): Promise<readonly AgentRun[]>
+```
+
+`AgentRunView` is `{ snapshotVersion, run, assistant? }`. `assistant` is the
+retained terminal answer, so it is present exactly when the run has ended and
+absent while it is live — a store that returns a live run's draft here lets the
+terminal path resolve a run that has not finished. `listActiveRuns` orders by
+`createdAt` then `id`, and must not report a run that has ended.
+`runAgentStoreConformance` covers both, including the boundary cases.
+
+#### If you have a store **double** in your tests
+
+The runtime now reads `loadRun` where it used to read `loadSnapshot`. A double
+that simulates a condition — a run drifting to another owner, a stale fencing
+token — must apply it to both reads, or the code under test will not see it.
+This is not hypothetical: it turned one of this repository's own fixtures into
+an infinite retry loop, which is how the bounded retry below was found.
+
+#### Nothing else changes
+
+`loadSnapshot` behaves exactly as before, and still returns the whole
+conversation — as does every mutation result. What it costs, and what bounds it,
+is now written down in *Reading a conversation* in the agent-runtime guide.
+
+### One provenance vocabulary, and integral tokens
+
+#### If you match on `'measured'`
+
+A **total** now says `computed`, because it is a sum this code performed rather
+than a count it took — the same rule `AgentUsage` has always applied to a run's
+spend. Two values change with no compile error:
+
+```ts
+// before
+if (result.totalTokens.provenance === 'measured') { /* exact */ }
+// after
+if (result.totalTokens.provenance === 'computed') { /* exact, and derived */ }
+```
+
+It affects `AgentHistoryBudgetResult.totalTokens` and
+`ComposedAgentPrompt.instructionTokens`. A per-message or per-section count is
+still `measured` — only the totals moved. When any part was estimated the total
+is still `estimated`: an estimate survives arithmetic, and that is the weaker
+claim, so it wins.
+
+#### If you produce token counts
+
+They are validated now, in the places they were not. A fractional count throws
+where it used to flow into the context-window arithmetic:
+
+```ts
+// refused from this release on
+estimateTokens: (text) => ({ value: text.length / 4, provenance: 'estimated' })
+// after
+estimateTokens: (text) => ({ value: Math.ceil(text.length / 4), provenance: 'estimated' })
+```
+
+The same applies to `ComposeAgentPromptOptions.estimateFallback` and
+`.historyTokens`, to `AgentPromptBudget.toolSchemas` / `.attachments` /
+`.providerOverhead`, and to `AgentPromptBudget.contextWindow` /
+`.reservedOutput`, which must now be non-negative safe integers.
+
+`AgentUsageValue.value` is `z.int()` too, which matters if you build usage
+records by hand or in a store double. A figure arriving from a **provider** is
+not thrown — `normalizeSdkUsage` and the OpenRouter adapter turn a non-integer
+into `{ provenance: 'unavailable' }`, so a run that already answered is not
+failed over its own bookkeeping.
+
+#### The new export
+
+`AgentProvenanceSchema` / `AgentProvenance` is the whole vocabulary:
+`provider-reported`, `measured`, `computed`, `estimated`, `unavailable`. Each
+surface declares its subset, so nothing widened — `AgentUsageValue` still refuses
+`measured` and `AgentTokenCount` still refuses `provider-reported`. Use it when
+you want one switch over the question instead of two.
+
 ## Released migration: 0.65.0
 
 The largest migration of the pre-1.0 line, and most of it is the compiler
@@ -10511,10 +10713,42 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRec
 `AgentUsageValueSchema`, `AgentCostValueSchema`, `AgentUsageSchema`, `AgentUsage` and
 `AgentRunMetrics`.
 
+`AgentProvenanceSchema` / `AgentProvenance` is the entrypoint's single vocabulary for **how a
+number came to be known**: `provider-reported` (the provider stated it about a request it served),
+`measured` (this process counted it exactly, before any request was made), `computed` (arithmetic
+over other values — a sum of exact numbers is still `computed`), `estimated` (a heuristic) and
+`unavailable` (not known, so `value` is absent, which is a different fact from a reported zero).
+Each surface declares the subset it can produce: `AgentUsageValueSchema` and `AgentCostValueSchema`
+describe a request that has already happened and never say `measured`; `AgentTokenCountSchema`
+describes a prompt being composed and never says `provider-reported`. Every token count is an
+integer — `AgentUsageValueSchema` and `AgentTokenCountSchema` refuse a fractional `value`, and a
+provider figure that is not a whole number is normalised to `unavailable` rather than thrown.
+`AgentCostValueSchema.value` stays fractional, because money is.
+
+`runs.inputPolicy` takes `queue` (default), `inject`, `interrupt` or `supersede`, or a function of
+the raw input returning one. `inject` lets a run in flight take a newly arrived input into its prompt
+at a step boundary and answer it too; the absorption is committed in the **same transaction** as that
+run's terminal record, via `CommitRunTerminal.absorb`, so a run that ends any other way leaves an
+ordinary queued successor. The absorbed run ends with `terminalReason: 'absorbed'`, run state
+`'superseded'`, `absorbedIntoRunId` naming the run that answered it, and **no assistant message of
+its own**; a submission on its idempotency key resolves through that pointer to the answer
+(→ ADR 0113).
+
+`AgentRuntimeStore` has two **bounded** reads beside `loadSnapshot`:
+`loadRun({ conversationId, runId })` returns an `AgentRunView` — the run, the conversation version it
+was read at, and the retained answer once the run is terminal — or `undefined`; `listActiveRuns(conversationId)`
+returns the runs that have not ended, ordered by `createdAt` then `id`. Neither reads history, so
+neither grows with the length of the conversation, and neither needs anything new from
+`AgentRuntimeStoreDriver`. `loadSnapshot` and every mutation result still carry the whole
+conversation — that is what the store's reducer validates against, and what the runtime builds a
+prompt from (→ ADR 0112).
+
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
-`RequestRunInterrupt`, `RequestRunInterruptSchema`, `runStateForTerminalReason`, `RecoverAgentRun`, `ReplaceCompactedRange`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AgentRunView`, `AgentRunViewSchema`,
+`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.65.0",
+  "version": "0.66.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",