stitchkit 0.84.1 → 0.85.0

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

@@ -12,17 +12,18 @@ import {
 import {
   AgentRuntimeEventSchema,
   agentDurableEventId
-} from "./index-85vfqd7m.js";
+} from "./index-4hk633vz.js";
 import {
   AgentAssistantPlaceholderSchema,
   AgentJsonObjectSchema,
   AgentMessagePartSchema,
   AgentMessageSchema,
   AgentProvenanceSchema,
+  AgentRunOperationSchema,
   AgentRunSchema,
   AgentSnapshotSchema,
   runStateForTerminalReason
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 import {
   isAgentToolError
 } from "./index-3xnq72rz.js";
@@ -1074,6 +1075,73 @@ function createIdleDeadline(parent, timeoutMs) {
   };
 }
 
+// src/agent-runtime/run-operation-lifecycle.ts
+function createAgentRunOperationLifecycle(config) {
+  let active;
+  const record = async (operation) => {
+    const current = config.currentRun();
+    const snapshot = appliedSnapshot(await config.store.recordRunOperation({
+      conversationId: current.conversationId,
+      runId: current.id,
+      expectedRevision: current.revision,
+      ownerId: config.runtimeEpoch,
+      ...current.fencingToken !== undefined && { fencingToken: current.fencingToken },
+      operation
+    }), "run operation");
+    config.acceptSnapshot(snapshot);
+    const run = findRun(snapshot.runs, current.id);
+    active = operation;
+    await config.publish({
+      type: "run-operation",
+      eventId: agentDurableEventId("run-operation", run.id, snapshot.version),
+      conversationId: run.conversationId,
+      runId: run.id,
+      snapshotVersion: snapshot.version,
+      operation,
+      emittedAt: config.now().toISOString()
+    });
+  };
+  return {
+    startCompaction(operationId) {
+      return record(AgentRunOperationSchema.parse({
+        operationId,
+        kind: "compaction",
+        phase: "started",
+        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();
+      }
+      return record(AgentRunOperationSchema.parse({
+        ...active,
+        phase: "first-output",
+        firstOutputAt: config.now().toISOString()
+      }));
+    },
+    finish(phase) {
+      if (!active || ["completed", "failed", "cancelled"].includes(active.phase)) {
+        return Promise.resolve();
+      }
+      return record(AgentRunOperationSchema.parse({
+        ...active,
+        phase,
+        finishedAt: config.now().toISOString()
+      }));
+    }
+  };
+}
+
 // src/agent-runtime/run-execution.ts
 function snapshotForRunPrompt(snapshot, runId) {
   const runIndex = snapshot.runs.findIndex((candidate) => candidate.id === runId);
@@ -1184,7 +1252,7 @@ function createRunExecutor(dependencies) {
     let observedVersion = snapshot.version;
     const parts = [];
     const absorbed = new Map;
-    let eventCount = 0;
+    let eventsSinceCheckpoint = 0;
     let sequence = 0;
     let terminalReason = "success";
     let nonModelUsage = input.acceptedRun.usage;
@@ -1199,6 +1267,18 @@ function createRunExecutor(dependencies) {
     let terminalPolicyName;
     const idleDeadline = createIdleDeadline(input.signal, idleTimeoutMs);
     const executionSignal = idleDeadline.signal;
+    const operationLifecycle = createAgentRunOperationLifecycle({
+      store: config.store,
+      runtimeEpoch,
+      currentRun: () => run,
+      acceptSnapshot: (next) => {
+        snapshot = next;
+        observedVersion = next.version;
+        run = findRun(next.runs, run.id);
+      },
+      publish,
+      now
+    });
     const updateReasoning = (text, metadata) => {
       const provider = providerEnvelope(metadata);
       if (reasoningPartIndex === undefined) {
@@ -1256,14 +1336,30 @@ function createRunExecutor(dependencies) {
     };
     try {
       if (config.history?.compact) {
-        const compacted = await config.history.compact({
-          conversationId: run.conversationId,
-          store: config.store,
-          signal: executionSignal
-        });
-        snapshot = compacted.snapshot;
-        observedVersion = snapshot.version;
-        run = findRun(snapshot.runs, run.id);
+        await operationLifecycle.startCompaction(generateId());
+        let compacted;
+        try {
+          compacted = await config.history.compact({
+            conversationId: run.conversationId,
+            store: config.store,
+            signal: executionSignal
+          });
+          snapshot = compacted.snapshot;
+          observedVersion = snapshot.version;
+          run = findRun(snapshot.runs, run.id);
+          await operationLifecycle.finish("completed");
+        } catch (error) {
+          const latest = await config.store.loadRun({
+            conversationId: run.conversationId,
+            runId: run.id
+          });
+          if (latest?.run.ownerId === runtimeEpoch) {
+            observedVersion = latest.snapshotVersion;
+            run = latest.run;
+          }
+          await operationLifecycle.finish(executionSignal.aborted ? "cancelled" : "failed");
+          throw error;
+        }
         if (compacted.usage) {
           nonModelUsage = addUsage(nonModelUsage, compacted.usage);
           usage = modelUsage ? addUsage(nonModelUsage, modelUsage) : nonModelUsage;
@@ -1418,6 +1514,9 @@ function createRunExecutor(dependencies) {
         abortSignal: executionSignal,
         maxRetries: 0,
         stopWhen: stopConditions,
+        onLanguageModelCallStart: async (event) => {
+          await operationLifecycle.startModelRequest(event.callId, step);
+        },
         repairToolCall: deferredToolRepair(config.loop?.prepareStep),
         ...config.loop?.toolApproval && {
           toolApproval: config.loop.toolApproval,
@@ -1428,6 +1527,13 @@ function createRunExecutor(dependencies) {
         },
         ...(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
@@ -1442,11 +1548,14 @@ function createRunExecutor(dependencies) {
       });
       for await (const part of result.stream) {
         idleDeadline.touch();
-        eventCount += 1;
+        eventsSinceCheckpoint += 1;
         sequence += 1;
-        if (firstOutputAt === undefined && ["text-delta", "reasoning-delta", "tool-call", "file", "source"].includes(part.type)) {
+        if (firstOutputAt === undefined && (part.type === "text-delta" && part.text.length > 0 || part.type === "reasoning-delta" && part.text.length > 0 || part.type === "tool-input-delta" && part.delta.length > 0 || part.type === "tool-call")) {
           firstOutputAt = performance.now();
         }
+        if (part.type === "text-delta" && part.text.length > 0 || part.type === "reasoning-delta" && part.text.length > 0 || part.type === "tool-input-delta" && part.delta.length > 0 || part.type === "tool-call") {
+          await operationLifecycle.firstOutput();
+        }
         if (part.type === "text-delta") {
           appendText(parts, part.text);
           await publish({
@@ -1552,6 +1661,7 @@ function createRunExecutor(dependencies) {
               status: "interrupted",
               emittedAt: now().toISOString()
             });
+            await checkpoint();
             throw part.error;
           }
           const output = isAgentToolError(part.error) ? jsonValue(part.error.output) : { message: "Tool execution failed" };
@@ -1661,6 +1771,7 @@ function createRunExecutor(dependencies) {
           terminalReason = part.error instanceof AgentContextOverflowError ? "context_overflow" : "provider_failure";
           internalCause = part.error;
         } else if (part.type === "finish-step") {
+          await operationLifecycle.finish(part.finishReason === "error" ? "failed" : "completed");
           const stepTrace = trace ? config.observe?.rootTrace(trace) : undefined;
           const stepUsage = selectedModel.normalizeUsage?.({
             usage: part.usage,
@@ -1696,9 +1807,21 @@ function createRunExecutor(dependencies) {
           modelUsage = mergeModelTotals(normalizeSdkUsage(part.totalUsage), modelUsage);
           usage = nonModelUsage ? addUsage(nonModelUsage, modelUsage) : modelUsage;
         }
-        if (eventCount % checkpointEveryEvents === 0)
+        const structuralBoundary = [
+          "tool-call",
+          "tool-result",
+          "tool-error",
+          "tool-output-denied",
+          "tool-approval-request",
+          "tool-approval-response",
+          "finish-step"
+        ].includes(part.type);
+        if (structuralBoundary || eventsSinceCheckpoint >= checkpointEveryEvents) {
           await checkpoint();
+          eventsSinceCheckpoint = 0;
+        }
       }
+      await operationLifecycle.finish(executionSignal.aborted ? "cancelled" : terminalReason === "provider_failure" ? "failed" : "completed");
       if (terminalPolicyName !== undefined)
         terminalReason = "policy_stop";
       if (executionSignal.aborted)
@@ -1732,6 +1855,10 @@ function createRunExecutor(dependencies) {
         observedVersion = latest.snapshotVersion;
         run = latestRun;
       }
+      const staleOwner = isToolExecutionControlError(error) && error.reason === "stale_run";
+      if (!staleOwner) {
+        await operationLifecycle.finish(executionSignal.aborted || durableInterrupt ? "cancelled" : "failed");
+      }
       if (isToolExecutionControlError(error) || executionSignal.aborted || durableInterrupt) {
         terminalReason = executionSignal.aborted ? abortTerminalReason(executionSignal) : "interrupted";
         parts.push(AgentMessagePartSchema.parse({

package/dist/{index-5s3zajp8.js → index-ff0kcqvp.js}

@@ -1,10 +1,10 @@
 import {
   AgentRuntimeEventSchema
-} from "./index-85vfqd7m.js";
+} from "./index-4hk633vz.js";
 import {
   AgentMessagePartSchema,
   AgentSnapshotSchema
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 
 // src/agent-runtime/control-schema.ts
 import { z } from "zod";
@@ -82,7 +82,13 @@ var AgentMultiSessionCursorSchema = z.object({
   }).strict())
 }).strict();
 function durable(event) {
-  return ["admission", "assistant-checkpoint", "run-state", "terminal"].includes(event.type);
+  return [
+    "admission",
+    "assistant-checkpoint",
+    "run-state",
+    "run-operation",
+    "terminal"
+  ].includes(event.type);
 }
 function advanceAgentMultiSessionCursor(raw, event) {
   const cursor = AgentMultiSessionCursorSchema.parse(raw);

package/dist/{index-11vzj2sk.js → index-fq492hg0.js}

@@ -5,12 +5,13 @@ import {
   AgentMessageSchema,
   AgentRecordIdSchema,
   AgentRecordVersionSchema,
+  AgentRunOperationSchema,
   AgentRunSchema,
   AgentSnapshotSchema,
   AgentTerminalReasonSchema,
   AgentUsageSchema,
   runStateForTerminalReason
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 
 // src/agent-runtime/conversations.ts
 import { z } from "zod";
@@ -114,6 +115,14 @@ var CheckpointRunAssistantSchema = z3.object({
   assistant: AgentMessageSchema,
   usage: AgentUsageSchema.optional()
 });
+var RecordRunOperationSchema = z3.object({
+  conversationId: AgentRecordIdSchema,
+  runId: AgentRecordIdSchema,
+  expectedRevision: AgentRecordVersionSchema,
+  ownerId: z3.string().min(1),
+  fencingToken: AgentRecordVersionSchema.optional(),
+  operation: AgentRunOperationSchema
+});
 var CommitRunTerminalSchema = z3.object({
   conversationId: AgentRecordIdSchema,
   runId: AgentRecordIdSchema,
@@ -437,6 +446,19 @@ function reduceStore(current, operation) {
       historyMutations: [{ type: "upsert-assistant", message: input.assistant }]
     });
   }
+  if (operation.type === "operation" && run) {
+    const input = operation.input;
+    if (run.revision !== input.expectedRevision || run.state !== "running" && run.state !== "interrupt_requested" || run.ownerId !== input.ownerId || input.fencingToken !== undefined && run.fencingToken !== input.fencingToken) {
+      return conflict(run.revision);
+    }
+    const next = AgentRunSchema.parse({
+      ...run,
+      lastOperation: input.operation,
+      revision: run.revision + 1,
+      updatedAt: new Date().toISOString()
+    });
+    return applied(current, { runs: replaceRun(current.runs, next) }, { runRecords: [AgentStoredRunSchema.parse({ schemaVersion: 1, run: next })] });
+  }
   if (operation.type === "interrupt" && run) {
     if (run.revision !== operation.input.expectedRevision || run.state !== "running") {
       return conflict(run.revision);
@@ -794,6 +816,10 @@ function createAgentRuntimeStore(driver) {
       type: "checkpoint",
       input: CheckpointRunAssistantSchema.parse(input)
     }),
+    recordRunOperation: (input) => mutate({
+      type: "operation",
+      input: RecordRunOperationSchema.parse(input)
+    }),
     requestRunInterrupt: (input) => mutate({
       type: "interrupt",
       input: RequestRunInterruptSchema.parse(input)
@@ -988,4 +1014,4 @@ function createMemoryAgentRuntimeStore() {
   return createAgentRuntimeStore(driver);
 }
 
-export { AgentConversationSummarySchema, AgentConversationPageSchema, AgentConversationMessagePageSchema, AgentConversationPurgeInputSchema, AgentConversationPurgeResultSchema, AgentConversationPurgedError, purgeAgentConversation, AgentStoreConflictSchema, AgentStoreNotFoundSchema, AgentStoreAppliedSchema, AgentStoreDuplicateSchema, AgentStoreMutationResultSchema, AgentRunViewSchema, AcceptInputAndAssignRunSchema, AcquireAgentRunSchema, CheckpointRunAssistantSchema, CommitRunTerminalSchema, RequestRunInterruptSchema, RecoverAgentRunSchema, ReplaceCompactedRangeSchema, AgentRecoverableDescriptorSchema, AgentRecoverablePageSchema, AgentRuntimeHeadSchema, AgentStoredRunSchema, AgentAdmissionReceiptSchema, AgentHistoryMutationSchema, ACTIVE_AGENT_RUN_STATES, createAgentRuntimeStore, createMemoryAgentRuntimeStore };
+export { AgentConversationSummarySchema, AgentConversationPageSchema, AgentConversationMessagePageSchema, AgentConversationPurgeInputSchema, AgentConversationPurgeResultSchema, AgentConversationPurgedError, purgeAgentConversation, AgentStoreConflictSchema, AgentStoreNotFoundSchema, AgentStoreAppliedSchema, AgentStoreDuplicateSchema, AgentStoreMutationResultSchema, AgentRunViewSchema, AcceptInputAndAssignRunSchema, AcquireAgentRunSchema, CheckpointRunAssistantSchema, RecordRunOperationSchema, CommitRunTerminalSchema, RequestRunInterruptSchema, RecoverAgentRunSchema, ReplaceCompactedRangeSchema, AgentRecoverableDescriptorSchema, AgentRecoverablePageSchema, AgentRuntimeHeadSchema, AgentStoredRunSchema, AgentAdmissionReceiptSchema, AgentHistoryMutationSchema, ACTIVE_AGENT_RUN_STATES, createAgentRuntimeStore, createMemoryAgentRuntimeStore };

package/dist/{index-x1th9s8c.js → index-x15ss2dx.js}

@@ -125,6 +125,54 @@ var AgentRunStateSchema = z.enum([
   "abandoned"
 ]);
 var AgentRunQueuePrioritySchema = z.enum(["interrupt-next"]);
+var AgentRunOperationKindSchema = z.enum(["model-request", "compaction"]);
+var AgentRunOperationPhaseSchema = z.enum([
+  "started",
+  "first-output",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+var AgentRunOperationFieldsSchema = z.object({
+  operationId: AgentRecordIdSchema,
+  kind: AgentRunOperationKindSchema,
+  phase: AgentRunOperationPhaseSchema,
+  step: z.int().nonnegative().optional(),
+  startedAt: AgentTimestampSchema,
+  firstOutputAt: AgentTimestampSchema.optional(),
+  finishedAt: AgentTimestampSchema.optional()
+});
+var AgentRunOperationSchema = AgentRunOperationFieldsSchema.superRefine((operation, ctx) => {
+  if (operation.kind === "model-request" !== (operation.step !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["step"],
+      message: "Only a model request has a step identity"
+    });
+  }
+  if (operation.kind === "compaction" && operation.phase === "first-output") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["phase"],
+      message: "Compaction has no first-output phase"
+    });
+  }
+  if (operation.phase === "first-output" && operation.firstOutputAt === undefined || operation.phase === "started" && operation.firstOutputAt !== undefined || operation.kind === "compaction" && operation.firstOutputAt !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["firstOutputAt"],
+      message: "Only model output phases carry the observed first-output timestamp"
+    });
+  }
+  const terminal = ["completed", "failed", "cancelled"].includes(operation.phase);
+  if (terminal !== (operation.finishedAt !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["finishedAt"],
+      message: "A terminal operation phase carries its observed finish timestamp"
+    });
+  }
+});
 var AgentTerminalReasonSchema = z.enum([
   "success",
   "policy_stop",
@@ -204,6 +252,7 @@ var AgentRunFieldsSchema = z.object({
   terminalPolicyName: z.string().min(1).optional(),
   absorbedIntoRunId: AgentRecordIdSchema.optional(),
   usage: AgentUsageSchema.optional(),
+  lastOperation: AgentRunOperationSchema.optional(),
   createdAt: AgentTimestampSchema,
   updatedAt: AgentTimestampSchema
 });
@@ -277,4 +326,4 @@ var AgentRunMetricsSchema = z.object({
   ttftMs: z.number().nonnegative().optional()
 });
 
-export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentToolApprovalRequestPartSchema, AgentToolApprovalResponsePartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentRunQueuePrioritySchema, AgentTerminalReasonSchema, runStateForTerminalReason, AgentProvenanceSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunSchema, AgentSnapshotSchema, AgentRunMetricsSchema };
+export { AgentRecordIdSchema, AgentRecordVersionSchema, AgentTimestampSchema, AgentJsonObjectSchema, AgentProviderEnvelopeSchema, AgentTextPartSchema, AgentReasoningPartSchema, AgentFilePartSchema, AgentSourcePartSchema, AgentToolCallPartSchema, AgentToolResultPartSchema, AgentToolApprovalRequestPartSchema, AgentToolApprovalResponsePartSchema, AgentOpaquePartSchema, AgentControlPartSchema, AgentMessagePartSchema, AgentMessageRoleSchema, AgentMessageStatusSchema, AgentMessageSchema, AgentAssistantPlaceholderSchema, AgentRunStateSchema, AgentRunQueuePrioritySchema, AgentRunOperationKindSchema, AgentRunOperationPhaseSchema, AgentRunOperationSchema, AgentTerminalReasonSchema, runStateForTerminalReason, AgentProvenanceSchema, AgentUsageValueSchema, AgentCostValueSchema, AgentUsageSchema, AgentRunSchema, AgentSnapshotSchema, AgentRunMetricsSchema };

package/dist/testing.js

@@ -7,7 +7,7 @@ import"./index-3z73fh2c.js";
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 import {
   RealtimeRejectDirectionSchema,
   RealtimeRejectFaultSchema,
@@ -450,10 +450,34 @@ async function conformanceScenario(store, conversationIds) {
   if (!recoverable.items.some((item) => item.run.id === running.id)) {
     throw new Error("A running run must appear in a recoverable scan");
   }
+  const operation = await store.recordRunOperation({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "conformance-owner",
+    fencingToken: checkpointedRun.fencingToken,
+    operation: {
+      operationId: "model-call-1:0",
+      kind: "model-request",
+      phase: "first-output",
+      step: 0,
+      startedAt: "2026-08-22T00:00:01.800Z",
+      firstOutputAt: "2026-08-22T00:00:01.900Z"
+    }
+  });
+  requireOutcome(operation, "applied");
+  const operatedRun = operation.snapshot.runs.find((run) => run.id === running.id);
+  if (operatedRun?.lastOperation?.operationId !== "model-call-1:0") {
+    throw new Error("Run operation identity did not survive its durable mutation");
+  }
+  const operatedView = await store.loadRun({ conversationId, runId: running.id });
+  if (operatedView?.run.lastOperation?.startedAt !== "2026-08-22T00:00:01.800Z") {
+    throw new Error("loadRun did not retain the original operation timestamp");
+  }
   const interrupted = await store.requestRunInterrupt({
     conversationId,
     runId: running.id,
-    expectedRevision: checkpointedRun.revision
+    expectedRevision: operatedRun.revision
   });
   requireOutcome(interrupted, "applied");
   const interruptedRun = interrupted.snapshot.runs.find((run) => run.id === running.id);

package/llms-full.txt

@@ -63,11 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 29 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 30 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `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` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 15 of the 29 minors since 0.56.2, most recently 0.84.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 16 of the 30 minors since 0.56.2, most recently 0.85.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 29 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 30 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -5273,12 +5273,33 @@ transaction. Drivers without this guarantee must leave the capability absent. Se
   while provider metadata stays inside a validated canonical envelope;
 - `assistant-checkpoint` follows a successful checkpoint CAS;
 - `run-state` follows durable queue/acquire/interrupt transitions;
+- `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
+  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
   start and output on completion. A mounted typed failure carries the same safe
   `{ error, details?, _hint? }` envelope as the durable result; an unknown
   internal cause remains generic and stays in local observability only;
 - `terminal` follows the winning terminal CAS.
 
+`loop.checkpointEveryEvents` batches ordinary stream parts (default `20`) and
+does not batch live event delivery. Tool call/result/error/denial, approval
+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.
+
+`compaction` names invocation of the configured callback, including a
+`not_needed` context-budget check; it does not by itself say that history was
+summarized. Operation timestamps are retained wall-clock observations and may
+move backwards after a clock correction. Do not subtract them for duration;
+phase order comes from durable snapshot versions/event order.
+
 These are post-commit notifications, not a transactional outbox: a process can
 crash between the database commit and `publish`. Reconnect should load canonical
 state. Exactly-once external delivery remains an application-owned outbox.
@@ -11022,6 +11043,33 @@ of the range if you want a different one.
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.85.0
+
+Only if you implement `AgentRuntimeStore` directly. Add the new durable
+operation mutation beside the existing run mutations:
+
+```ts
+// before
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  commitRunTerminal,
+  // ...
+}
+
+// after
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  recordRunOperation,
+  commitRunTerminal,
+  // ...
+}
+```
+
+It must atomically replace `AgentRun.lastOperation`, increment the run revision
+and conversation snapshot version, and enforce the supplied owner, fencing
+token and expected revision. Adapters built with `createAgentRuntimeStore`
+already receive the reference implementation; no driver method is added.
+
 ## What your range does, and does not, do for you
 
 A caret range (`"stitchkit": "^0.71.0"`) is a real gate: it resolves `< 0.72.0`,
@@ -15138,7 +15186,9 @@ Server-only optional application runtime. See the
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
 | `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/terminal projections |
+| `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 |
+| `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
 ### Complete runtime inventory
@@ -15268,7 +15318,8 @@ provider and required capabilities without constructing the model; runtime `mode
 runs before durable admission.
 
 Delivery exports are `AgentAdmissionEventSchema`, `AgentCheckpointEventSchema`,
-`AgentRunStateEventSchema`, `AgentTerminalEventSchema`, `AgentTransientDeltaEventSchema`,
+`AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
+`AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
 `AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
 `AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.84.1",
+  "version": "0.85.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",