stitchkit 0.62.0 → 0.64.0

package/dist/{index-58vkx74h.js → index-b1k33127.js}

@@ -99,6 +99,7 @@ var AgentRunStateSchema = z.enum([
   "completed",
   "interrupted",
   "superseded",
+  "absorbed",
   "failed",
   "cancelled",
   "abandoned"
@@ -106,6 +107,7 @@ var AgentRunStateSchema = z.enum([
 var AgentTerminalReasonSchema = z.enum([
   "success",
   "policy_stop",
+  "provider_stop",
   "interrupted",
   "superseded",
   "cancelled",
@@ -115,6 +117,23 @@ var AgentTerminalReasonSchema = z.enum([
   "tool_failure",
   "abandoned"
 ]);
+var AgentUsageValueSchema = z.object({
+  value: z.number().nonnegative().optional(),
+  provenance: z.enum(["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"])
+});
+var AgentUsageSchema = z.object({
+  inputTokens: AgentUsageValueSchema,
+  outputTokens: AgentUsageValueSchema,
+  reasoningTokens: AgentUsageValueSchema.optional(),
+  cacheReadTokens: AgentUsageValueSchema.optional(),
+  cacheWriteTokens: AgentUsageValueSchema.optional(),
+  cost: AgentCostValueSchema.optional()
+});
 var AgentRunSchema = z.object({
   schemaVersion: z.literal(1),
   id: AgentRecordIdSchema,
@@ -127,6 +146,8 @@ 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
 });
@@ -137,23 +158,6 @@ var AgentSnapshotSchema = z.object({
   messages: z.array(AgentMessageSchema),
   runs: z.array(AgentRunSchema)
 });
-var AgentUsageValueSchema = z.object({
-  value: z.number().nonnegative().optional(),
-  provenance: z.enum(["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"])
-});
-var AgentUsageSchema = z.object({
-  inputTokens: AgentUsageValueSchema,
-  outputTokens: AgentUsageValueSchema,
-  reasoningTokens: AgentUsageValueSchema.optional(),
-  cacheReadTokens: AgentUsageValueSchema.optional(),
-  cacheWriteTokens: AgentUsageValueSchema.optional(),
-  cost: AgentCostValueSchema.optional()
-});
 var AgentRunMetricsSchema = z.object({
   partial: z.boolean(),
   usage: AgentUsageSchema.optional(),
@@ -161,4 +165,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, AgentRunSchema, AgentSnapshotSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunMetricsSchema };
+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 };

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,CAmRf"}
+{"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"}

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-58vkx74h.js";
+} from "./index-b1k33127.js";
 import {
   createApplication
 } from "./index-eabpd4tb.js";
@@ -283,12 +283,20 @@ async function runAgentStoreConformance(config) {
       parts: [{ type: "text", text: "checkpoint" }],
       createdAt: "2026-08-22T00:00:00.000Z",
       updatedAt: "2026-08-22T00:00:01.000Z"
-    })
+    }),
+    usage: {
+      inputTokens: { value: 1000, provenance: "provider-reported" },
+      outputTokens: { value: 100, provenance: "provider-reported" },
+      cost: { value: 0.25, currency: "USD", provenance: "provider-reported" }
+    }
   });
   requireOutcome(checkpoint, "applied");
   const checkpointedRun = checkpoint.snapshot.runs.find((run) => run.id === running.id);
   if (!checkpointedRun)
     throw new Error("Checkpointed run disappeared");
+  if (checkpointedRun.usage?.cost?.value !== 0.25) {
+    throw new Error("Checkpoint did not persist the run usage it was given");
+  }
   const terminalAssistant = AgentMessageSchema.parse({
     schemaVersion: 1,
     id: running.assistantMessageId,
@@ -307,7 +315,12 @@ async function runAgentStoreConformance(config) {
       expectedRevision: checkpointedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
-      reason: "success"
+      reason: "success",
+      usage: {
+        inputTokens: { value: 3000, provenance: "computed" },
+        outputTokens: { value: 300, provenance: "computed" },
+        cost: { value: 1.5, currency: "USD", provenance: "computed" }
+      }
     }),
     store.commitRunTerminal({
       conversationId,
@@ -315,7 +328,12 @@ async function runAgentStoreConformance(config) {
       expectedRevision: checkpointedRun.revision,
       ownerId: "conformance-owner",
       assistant: terminalAssistant,
-      reason: "success"
+      reason: "success",
+      usage: {
+        inputTokens: { value: 3000, provenance: "computed" },
+        outputTokens: { value: 300, provenance: "computed" },
+        cost: { value: 1.5, currency: "USD", provenance: "computed" }
+      }
     })
   ]);
   const terminalOutcomes = terminalResults.map((result) => result.outcome).sort();
@@ -326,6 +344,10 @@ async function runAgentStoreConformance(config) {
   if (terminalApplied?.outcome !== "applied") {
     throw new Error("Terminal race produced no applied result");
   }
+  const settledRun = terminalApplied.snapshot.runs.find((run) => run.id === running.id);
+  if (settledRun?.usage?.cost?.value !== 1.5) {
+    throw new Error("Terminal commit did not persist the run usage it was given");
+  }
   const compactedTerminal = await store.replaceCompactedRange({
     conversationId,
     expectedVersion: terminalApplied.snapshot.version,

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 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/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 |
@@ -3682,7 +3682,7 @@ the fourth row below is a behaviour it deliberately does not offer yet:
 | `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 | — not supported; see below |
+| `inject` | continues | kept — it takes the new input at a step boundary |
 
 `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,15 +3766,37 @@ 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 supported
-
-**inject** — hand the input to the loop between tool calls and let the run
-continue — has no primitive. `loop.prepareStep` passes the AI SDK return type
-through, so an application *can* append messages between steps, but nothing
-hands `prepareStep` the pending inputs and nothing attaches an absorbed input to
-the running run's `inputMessageIds`. A run that answered two messages would
-carry a durable record claiming it answered one. It is reachable by hand, not
-supported.
+### 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.
 
 With `runs.coalescePending: true`, an active lane has at most one queued
 successor. Every later accepted input is atomically appended to that successor;
@@ -4028,6 +4050,35 @@ 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).
 
+### Reconciling with the provider's own accounting
+
+Whether a provider bills for a call that was aborted mid-flight cannot be known
+inside the process: the authoritative number arrives later, from the provider's
+accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
+is an absorbing state, and a write that reached it through the conversation
+aggregate could conflict a concurrent compaction into discarding a summary it had
+just paid a model to produce.
+
+The join is yours, and `runId` is the key:
+
+```ts
+// when the run terminates — write what the runtime observed
+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',
+})
+
+// later — the provider's accounting names the same generation
+await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```
+
+Record the row even when the figure is `unavailable`: that row is the evidence
+that a run happened and cost something nobody has counted yet, and it is what the
+provider's later figure attaches to. A run with no row is a run you cannot
+reconcile.
+
 The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
 outbox.
 
@@ -7712,6 +7763,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
@@ -7750,6 +7819,114 @@ 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.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
+in flight. Nothing moves an export except one added store member, and only an
+application implementing `AgentRuntimeStore` directly has to touch code.
+
+### A spend figure that survives, and an input that joins
+
+### `AgentRuntimeStore` has a ninth member
+
+Only if you implement the aggregate interface directly — an adapter built on
+`AgentRuntimeStoreDriver` needs no change, and the public conformance kit covers
+the new operation.
+
+```ts
+// after
+absorbQueuedRun(input: AbsorbQueuedRun): Promise<AgentStoreMutationResult>
+```
+
+It moves a queued successor's inputs into the run already answering, in one
+mutation, and marks the successor `absorbed`. Two run records change in one
+transaction — if your driver persists them one at a time, persist both.
+
+### A provider failure says so
+
+```ts
+// before — an upstream error arrived as a policy stop with no policy
+if (terminal.reason === 'policy_stop') retryLater()
+
+// after
+if (terminal.reason === 'provider_failure') retryLater()
+if (terminal.reason === 'provider_stop') { /* a length cap or content filter */ }
+```
+
+`policy_stop` now always carries the `policyName` that caused it. If you switch
+exhaustively on `AgentTerminalReason` or `AgentRunState`, add `'provider_stop'`
+and `'absorbed'`.
+
+### `partial` changed meaning
+
+It used to tell you which event kind you were holding. It now tells you whether
+the figure beside it is a confirmed total:
+
+```ts
+// after — true when the provider never reported the run finished
+if (metrics.partial) treatAsFloor(metrics.usage)
+```
+
+Terminal events for runs that were superseded, interrupted, timed out or failed
+before the provider finished now report `partial: true` where they reported
+`false`.
+
+### Checkpoint metrics are a running total
+
+```ts
+// wrong, and now wrong by more than it used to be
+const spent = checkpoints.reduce((total, c) => total + (c.metrics.usage?.cost?.value ?? 0), 0)
+// right
+const spent = checkpoints.at(-1)?.metrics.usage?.cost?.value
+```
+
+### You can read a run's spend back from the store
+
+`AgentRun.usage` is written at every checkpoint and with the terminal record, so
+a dropped observability event no longer loses the number, and a process that dies
+mid-stream leaves behind what it had already spent.
+
 ## Released migration: 0.62.0
 
 Two groups of behaviour changes. Nothing moves an export — the surface is
@@ -10237,7 +10414,8 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRec
 Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
 `AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
 `CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
-`RequestRunInterrupt`, `RequestRunInterruptSchema`, `RecoverAgentRun`, `ReplaceCompactedRange`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `AbsorbQueuedRun`, `AbsorbQueuedRunSchema`,
+`RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
 `AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
@@ -10272,6 +10450,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.62.0",
+  "version": "0.64.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",