stitchkit 0.85.0 → 0.85.1

package/CHANGELOG.md

@@ -15,6 +15,21 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.85.1] — 2026-09-07
+
+### Fixed
+
+- **A later model step cannot outrun its durable lifecycle or the previous
+  structural checkpoint.** AI SDK lifecycle callbacks deliberately suppress
+  callback failures, so the 0.85.0 request-start write could lose a revision
+  race with stream persistence while the provider request still executed. The
+  runtime now uses the callback only for concrete-model call identity; awaited
+  step preparation and model middleware record request admission before `doStream`, and every step
+  after the first waits for the prior step's structural checkpoint. A rejected
+  lifecycle write therefore prevents the provider call instead of producing an
+  unrecorded inference. Deferred-store and failed-admission tests cover both
+  sides of the guarantee. → ADR 0174 (amended).
+
 ## [0.85.0] — 2026-09-07
 
 ### ⚠️ Breaking changes

package/dist/agent-runtime/run-execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-execution.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/run-execution.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAMZ,OAAO,EAAE,KAAK,iBAAiB,EAAuB,MAAM,UAAU,CAAC;AAEvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAqB,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAavE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAKL,KAAK,QAAQ,EAOd,MAAM,WAAW,CAAC;AAuCnB,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO;IACrE,MAAM,EAAE,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,IAAI,MAAM,CAAC;IACrB,GAAG,IAAI,IAAI,CAAC;IACZ,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAC9D,YAAY,EAAE,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC,WAcb;IACtC,WAAW,EAAE,QAAQ,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB,KAAG,OAAO,CAAC,kBAAkB,CAAC,CAuhChC"}
+{"version":3,"file":"run-execution.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/run-execution.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAMZ,OAAO,EAAE,KAAK,iBAAiB,EAAuB,MAAM,UAAU,CAAC;AAEvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAqB,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAavE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAKL,KAAK,QAAQ,EAOd,MAAM,WAAW,CAAC;AAuCnB,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO;IACrE,MAAM,EAAE,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,IAAI,MAAM,CAAC;IACrB,GAAG,IAAI,IAAI,CAAC;IACZ,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAC9D,YAAY,EAAE,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC,WAcb;IACtC,WAAW,EAAE,QAAQ,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB,KAAG,OAAO,CAAC,kBAAkB,CAAC,CAoiChC"}

package/dist/agent-runtime/run-operation-lifecycle.d.ts

@@ -1,3 +1,4 @@
+import { type LanguageModel } from 'ai';
 import type { AgentRuntimeEvent } from './event-schema.js';
 import { type AgentRun, type AgentSnapshot } from './schemas.js';
 import type { AgentRuntimeStore } from './store.js';
@@ -12,8 +13,11 @@ export interface AgentRunOperationLifecycleConfig {
 }
 /** One durable latest-operation state machine for an executing run. */
 export declare function createAgentRunOperationLifecycle(config: AgentRunOperationLifecycleConfig): {
+    noteProviderCall(callId: string): void;
+    prepareModel(model: LanguageModel, step: number, fallbackCallId: string): Promise<LanguageModel>;
+    checkpointStep(step: number): void;
+    failStepCheckpoints(error: unknown): void;
     startCompaction(operationId: string): Promise<void>;
-    startModelRequest(providerCallId: string, step: number): Promise<void>;
     firstOutput(): Promise<void>;
     finish(phase: TerminalOperationPhase): Promise<void>;
 };

package/dist/agent-runtime/run-operation-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-operation-lifecycle.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/run-operation-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EACL,KAAK,QAAQ,EAGb,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,KAAK,sBAAsB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,IAAI,QAAQ,CAAC;IACvB,cAAc,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9C,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,GAAG,IAAI,IAAI,CAAC;CACb;AAED,uEAAuE;AACvE,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,gCAAgC;IA+BrF,eAAe,cAAc,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD,iBAAiB,iBAAiB,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,MAAM,QAAQ,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;EAavD"}
+{"version":3,"file":"run-operation-lifecycle.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/run-operation-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,IAAI,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EACL,KAAK,QAAQ,EAGb,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,KAAK,sBAAsB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,IAAI,QAAQ,CAAC;IACvB,cAAc,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9C,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,GAAG,IAAI,IAAI,CAAC;CACb;AAED,uEAAuE;AACvE,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,gCAAgC;IA4CrF,gBAAgB,SAAS,MAAM,GAAG,IAAI;IAGhC,YAAY,QACT,aAAa,QACd,MAAM,kBACI,MAAM,GACrB,OAAO,CAAC,aAAa,CAAC;IAgCzB,cAAc,OAAO,MAAM,GAAG,IAAI;IAQlC,mBAAmB,QAAQ,OAAO,GAAG,IAAI;IAIzC,eAAe,cAAc,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,MAAM,QAAQ,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;EAavD"}

package/dist/agent-runtime-harness.js

@@ -2,7 +2,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-9merfjxf.js";
+} from "./index-jpp7jd1p.js";
 import {
   AgentModelDescriptorSchema
 } from "./index-tg3m2ec5.js";

package/dist/agent-runtime.js

@@ -49,7 +49,7 @@ import {
   registerDeferredToolRepair,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-9merfjxf.js";
+} from "./index-jpp7jd1p.js";
 import {
   AgentModelCapabilitySchema,
   AgentModelCatalogEntrySchema,

package/dist/{index-9merfjxf.js → index-jpp7jd1p.js}

@@ -934,6 +934,9 @@ function repairedSearchCall(toolCall, searchName) {
   };
 }
 
+// src/agent-runtime/run-operation-lifecycle.ts
+import { wrapLanguageModel } from "ai";
+
 // src/agent-runtime/runtime-internals.ts
 import { z as z2 } from "zod";
 function findRun(runs, runId) {
@@ -1078,6 +1081,9 @@ function createIdleDeadline(parent, timeoutMs) {
 // src/agent-runtime/run-operation-lifecycle.ts
 function createAgentRunOperationLifecycle(config) {
   let active;
+  let providerCallId;
+  let checkpointedStep = -1;
+  const checkpointWaiters = new Map;
   const record = async (operation) => {
     const current = config.currentRun();
     const snapshot = appliedSnapshot(await config.store.recordRunOperation({
@@ -1101,7 +1107,57 @@ function createAgentRunOperationLifecycle(config) {
       emittedAt: config.now().toISOString()
     });
   };
+  const startModelRequest = (callId, step) => record(AgentRunOperationSchema.parse({
+    operationId: `${callId}:${step}`,
+    kind: "model-request",
+    phase: "started",
+    step,
+    startedAt: config.now().toISOString()
+  }));
   return {
+    noteProviderCall(callId) {
+      providerCallId = callId;
+    },
+    async prepareModel(model, step, fallbackCallId) {
+      if (step > checkpointedStep + 1) {
+        const waiter = checkpointWaiters.get(step - 1) ?? Promise.withResolvers();
+        checkpointWaiters.set(step - 1, waiter);
+        await waiter.promise;
+      }
+      if (typeof model === "string") {
+        await startModelRequest(fallbackCallId, step);
+        return model;
+      }
+      return wrapLanguageModel({
+        model,
+        middleware: {
+          specificationVersion: "v4",
+          wrapStream: async ({ doStream }) => {
+            const callId = providerCallId;
+            providerCallId = undefined;
+            if (!callId) {
+              throw new Error("AgentRuntime model call reached the provider without lifecycle identity");
+            }
+            await startModelRequest(callId, step);
+            return doStream();
+          }
+        }
+      });
+    },
+    checkpointStep(step) {
+      checkpointedStep = Math.max(checkpointedStep, step);
+      for (const [waitingFor, waiter] of checkpointWaiters) {
+        if (waitingFor > checkpointedStep)
+          continue;
+        checkpointWaiters.delete(waitingFor);
+        waiter.resolve();
+      }
+    },
+    failStepCheckpoints(error) {
+      for (const waiter of checkpointWaiters.values())
+        waiter.reject(error);
+      checkpointWaiters.clear();
+    },
     startCompaction(operationId) {
       return record(AgentRunOperationSchema.parse({
         operationId,
@@ -1110,15 +1166,6 @@ function createAgentRunOperationLifecycle(config) {
         startedAt: config.now().toISOString()
       }));
     },
-    startModelRequest(providerCallId, step) {
-      return record(AgentRunOperationSchema.parse({
-        operationId: `${providerCallId}:${step}`,
-        kind: "model-request",
-        phase: "started",
-        step,
-        startedAt: config.now().toISOString()
-      }));
-    },
     firstOutput() {
       if (active?.kind !== "model-request" || active.phase !== "started") {
         return Promise.resolve();
@@ -1506,16 +1553,17 @@ function createRunExecutor(dependencies) {
         }
         return messages;
       };
+      const fallbackModel = selectedModel.model;
       const result = streamAgentTextBoundary({
-        model: selectedModel.model,
+        model: fallbackModel,
         tools,
         instructions: withCarriedSystem(prompt.instructions),
         messages: history,
         abortSignal: executionSignal,
         maxRetries: 0,
         stopWhen: stopConditions,
-        onLanguageModelCallStart: async (event) => {
-          await operationLifecycle.startModelRequest(event.callId, step);
+        onLanguageModelCallStart: (event) => {
+          operationLifecycle.noteProviderCall(event.callId);
         },
         repairToolCall: deferredToolRepair(config.loop?.prepareStep),
         ...config.loop?.toolApproval && {
@@ -1525,25 +1573,27 @@ function createRunExecutor(dependencies) {
         ...config.loop?.toolApprovalSecret && {
           experimental_toolApprovalSecret: config.loop.toolApprovalSecret
         },
-        ...(config.loop?.prepareStep || injection) && {
-          prepareStep: async (options) => {
-            const previousStep = options.steps.at(-1);
-            if (previousStep) {
-              lastPromptTokens = selectedModel?.normalizeUsage?.({
-                usage: previousStep.usage,
-                providerMetadata: previousStep.providerMetadata
-              })?.inputTokens ?? normalizeSdkUsage(previousStep.usage).inputTokens;
-            }
-            const prepared = await config.loop?.prepareStep?.({
-              ...options,
-              ...runtimeContext
-            });
-            const injected = await takeInjectedMessages();
-            if (injected.length === 0)
-              return prepared;
-            const base = prepared?.messages ?? options.messages;
-            return { ...prepared, messages: [...base, ...injected] };
+        prepareStep: async (options) => {
+          const previousStep = options.steps.at(-1);
+          if (previousStep) {
+            lastPromptTokens = selectedModel?.normalizeUsage?.({
+              usage: previousStep.usage,
+              providerMetadata: previousStep.providerMetadata
+            })?.inputTokens ?? normalizeSdkUsage(previousStep.usage).inputTokens;
           }
+          const prepared = await config.loop?.prepareStep?.({
+            ...options,
+            ...runtimeContext
+          });
+          const injected = await takeInjectedMessages();
+          const preparedStep = injected.length === 0 ? prepared : {
+            ...prepared,
+            messages: [...prepared?.messages ?? options.messages, ...injected]
+          };
+          return {
+            ...preparedStep,
+            model: await operationLifecycle.prepareModel(preparedStep?.model ?? fallbackModel, options.stepNumber, generateId())
+          };
         }
       });
       for await (const part of result.stream) {
@@ -1819,6 +1869,8 @@ function createRunExecutor(dependencies) {
         if (structuralBoundary || eventsSinceCheckpoint >= checkpointEveryEvents) {
           await checkpoint();
           eventsSinceCheckpoint = 0;
+          if (part.type === "finish-step")
+            operationLifecycle.checkpointStep(step - 1);
         }
       }
       await operationLifecycle.finish(executionSignal.aborted ? "cancelled" : terminalReason === "provider_failure" ? "failed" : "completed");
@@ -1844,6 +1896,7 @@ function createRunExecutor(dependencies) {
         }
       }
     } catch (error) {
+      operationLifecycle.failStepCheckpoints(error);
       internalCause = error;
       const latest = await config.store.loadRun({
         conversationId: run.conversationId,

package/llms-full.txt

@@ -5276,8 +5276,11 @@ transaction. Drivers without this guarantee must leave the capability absent. Se
 - `run-operation` follows a successful operation CAS. Its `operation` is the
   durable `AgentRun.lastOperation`: `model-request` or `compaction`, with
   `started`, `first-output`, `completed`, `failed` or `cancelled` phase and the
-  original timestamps. Model request start means the provider call is about to
-  enter `doStream`, not that HTTP transmission is measured. First output is a
+  original timestamps. Concrete models use SDK call identity in an awaited model
+  middleware; global provider IDs use a runtime-generated identity during awaited
+  step preparation. Both durably admit the request before entering `doStream`, so a failed
+  write prevents the provider call. This does not claim HTTP transmission is
+  measured. First output is a
   non-empty text/reasoning/tool-argument delta or complete tool call; metadata,
   usage, files and sources do not count;
 - `tool-status` is transient lifecycle presentation with JSON-safe input on
@@ -5292,7 +5295,9 @@ request/response and step-finish boundaries force an assistant checkpoint and
 reset that batch. The checkpoint is awaited after the managed loop observes the
 normalized boundary. It does **not** promise persistence before a tool side
 effect: tool fencing supplies the real ownership checks around execution, while
-cross-crash effect idempotency stays application-owned. → ADR 0174.
+cross-crash effect idempotency stays application-owned. The following model
+step waits for the previous step-finish checkpoint before its own durable
+request admission and provider invocation. → ADR 0174.
 
 `compaction` names invocation of the configured callback, including a
 `not_needed` context-budget check; it does not by itself say that history was
@@ -15187,7 +15192,7 @@ Server-only optional application runtime. See the
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent`; compose beside application idempotency for [durable operations](../guide/mcp-and-agents.md#durable-application-owned-execution) |
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/run-operation/terminal projections |
-| `AgentRunOperationKindSchema` / `AgentRunOperationPhaseSchema` / `AgentRunOperationSchema` / `AgentRunOperation` | schemas / _type_ | latest durable model-request or compaction phase with operation/step identity and original timestamps |
+| `AgentRunOperationKindSchema` / `AgentRunOperationPhaseSchema` / `AgentRunOperationSchema` / `AgentRunOperation` | schemas / _type_ | latest durable model-request or compaction phase with operation/step identity and original timestamps; request admission is awaited before provider invocation |
 | `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.85.0",
+  "version": "0.85.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",
@@ -285,7 +285,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.79",
+    "ai": "^7.0.93",
     "fake-indexeddb": "^6.2.5",
     "grammy": "^1.45.1",
     "react": "^19.2.8",