stitchkit 0.84.0 → 0.85.0

package/dist/{index-85vfqd7m.js → index-4hk633vz.js}

@@ -5,11 +5,12 @@ import {
   AgentRecordIdSchema,
   AgentRecordVersionSchema,
   AgentRunMetricsSchema,
+  AgentRunOperationSchema,
   AgentRunSchema,
   AgentRunStateSchema,
   AgentTerminalReasonSchema,
   AgentTimestampSchema
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 
 // src/agent-runtime/event-schema.ts
 import { z } from "zod";
@@ -63,6 +64,12 @@ var AgentRunStateEventSchema = EventIdentitySchema.extend({
   snapshotVersion: AgentRecordVersionSchema,
   state: AgentRunStateSchema
 });
+var AgentRunOperationEventSchema = EventIdentitySchema.extend({
+  type: z.literal("run-operation"),
+  eventId: AgentRecordIdSchema,
+  snapshotVersion: AgentRecordVersionSchema,
+  operation: AgentRunOperationSchema
+});
 var AgentToolStatusEventSchema = EventIdentitySchema.extend({
   type: z.literal("tool-status"),
   runtimeEpoch: z.string().min(1),
@@ -90,6 +97,7 @@ var AgentRuntimeEventSchema = z.discriminatedUnion("type", [
   AgentReasoningEndEventSchema,
   AgentCheckpointEventSchema,
   AgentRunStateEventSchema,
+  AgentRunOperationEventSchema,
   AgentToolStatusEventSchema,
   AgentTerminalEventSchema
 ]);
@@ -100,7 +108,7 @@ var AgentRuntimeEventCursorSchema = z.object({
   sequence: z.int().nonnegative().optional()
 });
 function isDurableEvent(event) {
-  return event.type === "admission" || event.type === "assistant-checkpoint" || event.type === "run-state" || event.type === "terminal";
+  return event.type === "admission" || event.type === "assistant-checkpoint" || event.type === "run-state" || event.type === "run-operation" || event.type === "terminal";
 }
 function advanceAgentRuntimeEventCursor(rawCursor, event) {
   const cursor = AgentRuntimeEventCursorSchema.parse(rawCursor);
@@ -132,4 +140,4 @@ function agentDurableEventId(type, runId, snapshotVersion) {
   return `${runId}:${type}:${snapshotVersion}`;
 }
 
-export { AgentAdmissionEventSchema, AgentTransientDeltaEventSchema, AgentReasoningStartEventSchema, AgentReasoningDeltaEventSchema, AgentReasoningEndEventSchema, AgentCheckpointEventSchema, AgentRunStateEventSchema, AgentToolStatusEventSchema, AgentTerminalEventSchema, AgentRuntimeEventSchema, AgentRuntimeEventCursorSchema, advanceAgentRuntimeEventCursor, agentDurableEventId };
+export { AgentAdmissionEventSchema, AgentTransientDeltaEventSchema, AgentReasoningStartEventSchema, AgentReasoningDeltaEventSchema, AgentReasoningEndEventSchema, AgentCheckpointEventSchema, AgentRunStateEventSchema, AgentRunOperationEventSchema, AgentToolStatusEventSchema, AgentTerminalEventSchema, AgentRuntimeEventSchema, AgentRuntimeEventCursorSchema, advanceAgentRuntimeEventCursor, agentDurableEventId };

package/dist/{index-cksjz4eg.js → index-66nxrgy0.js}

@@ -8,11 +8,11 @@ import {
   AgentRuntimeHeadSchema,
   AgentStoredRunSchema,
   createAgentRuntimeStore
-} from "./index-19eet1qx.js";
+} from "./index-fq492hg0.js";
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-x1th9s8c.js";
+} from "./index-x15ss2dx.js";
 
 // src/agent-runtime/sqlite.ts
 import { z } from "zod";
@@ -244,19 +244,20 @@ function createSqliteAgentRuntimeStore(config) {
     });
     return result;
   };
+  const runTransaction = (access, work) => serial(async () => {
+    database.exec(access === "read" ? "BEGIN" : "BEGIN IMMEDIATE");
+    try {
+      const result = await work(database);
+      database.exec("COMMIT");
+      return result;
+    } catch (error) {
+      database.exec("ROLLBACK");
+      throw error;
+    }
+  });
   const driver = {
     conversations: sqliteConversationPurge(database),
-    transaction: (work) => serial(async () => {
-      database.exec("BEGIN IMMEDIATE");
-      try {
-        const result = await work(database);
-        database.exec("COMMIT");
-        return result;
-      } catch (error) {
-        database.exec("ROLLBACK");
-        throw error;
-      }
-    }),
+    transaction: (work, options) => runTransaction(options?.access ?? "write", work),
     head: {
       async load(transaction, conversationId) {
         const value = transaction.prepare("SELECT version FROM stitchkit_agent_runtime_heads WHERE conversation_id = ?").get(conversationId);
@@ -437,7 +438,7 @@ function createSqliteAgentRuntimeStore(config) {
           `).run(message.conversationId, message.id, position, encodeJson(message));
       }
     },
-    scanRecoverable: (input) => serial(async () => {
+    scanRecoverable: (input) => runTransaction("read", async () => {
       const cursor = input.cursor ? parseRecoveryCursor(input.cursor) : undefined;
       const values = cursor ? [cursor[0], cursor[0], cursor[1], input.limit + 1] : [input.limit + 1];
       const rows = database.prepare(`
@@ -466,7 +467,7 @@ function createSqliteAgentRuntimeStore(config) {
   return {
     store: createAgentRuntimeStore(driver),
     conversations: {
-      list: (input) => serial(async () => {
+      list: (input) => runTransaction("read", async () => {
         if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 1000) {
           throw new TypeError("Conversation page limit must be between 1 and 1000");
         }
@@ -517,7 +518,7 @@ function createSqliteAgentRuntimeStore(config) {
           ...hasMore && last ? { nextCursor: conversationCursor(last.conversation_id) } : {}
         });
       }),
-      messages: (input) => serial(async () => {
+      messages: (input) => runTransaction("read", async () => {
         if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 1000) {
           throw new TypeError("Conversation message page limit must be between 1 and 1000");
         }

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-19eet1qx.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);
@@ -640,7 +662,7 @@ function createAgentRuntimeStore(driver) {
       runIds: referencedRunIds(messages)
     });
     return snapshotOf(head, messages, mergeRunRecords(activeRecords, referencedRecords));
-  });
+  }, { access: "read" });
   const loadRun = (input) => driver.transaction(async (transaction) => {
     const [stored, record] = await Promise.all([
       driver.head.load(transaction, input.conversationId),
@@ -658,7 +680,7 @@ function createAgentRuntimeStore(driver) {
       run: parsed.run,
       ...parsed.terminalAssistant && { assistant: parsed.terminalAssistant }
     });
-  });
+  }, { access: "read" });
   const listActiveRuns = (conversationId) => driver.transaction(async (transaction) => {
     const [records, messages] = await Promise.all([
       driver.runs.listActive(transaction, conversationId),
@@ -674,7 +696,7 @@ function createAgentRuntimeStore(driver) {
       }
     }
     return orderRuns(messages, runs);
-  });
+  }, { access: "read" });
   const mutate = (operation) => driver.transaction(async (transaction) => {
     const conversationId = operationConversationId(operation);
     if (await driver.conversations?.isPurged(transaction, conversationId)) {
@@ -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/dist/tools/async-operation.d.ts

@@ -1,7 +1,7 @@
 import { type ZodObject, type ZodType, z } from 'zod';
 import { AsyncOperationCancelResultSchema, type AsyncOperationCapability } from './async-operation-contract.js';
 export { type AsyncOperationCancelResult, AsyncOperationCancelResultSchema, type AsyncOperationCapability, type AsyncOperationSnapshotSchema, type AsyncOperationSnapshotSchemaWithProgress, createAsyncOperationSnapshotSchema, } from './async-operation-contract.js';
-import type { ContractDef, EndpointDef, EndpointToolAnnotations, HttpMethod } from '../contract/index.js';
+import type { ContractDef, EndpointDef, EndpointToolAnnotations, HttpMethod, Transport } from '../contract/index.js';
 import type { Handlers } from '../server/types.js';
 import { type RuntimeToolDefinition, type RuntimeToolDefinitionWithOutput, type RuntimeToolHandlerContext, type RuntimeToolTransport } from './runtime-tool.js';
 export interface AsyncOperationIdentity {
@@ -148,6 +148,23 @@ interface AsyncOperationContractBaseConfig<TStartInput extends ZodType, TId exte
     artifacts?: TArtifacts;
     descriptions?: Partial<Record<AsyncOperationCapability, string>>;
     scopes?: TScopes;
+    /**
+     * Which transports carry each capability. Absent, an endpoint is a tool on
+     * every transport, which is the framework default.
+     *
+     * It has to be declarable HERE because this contract is built inside the
+     * framework: an application that made tools opt-in with
+     * `createContractFactory({ toolExposure: 'explicit' })` set that default on
+     * its OWN factory, and these endpoints never pass through it. Without this
+     * field a consumer who had decided that agents get only the tools it names
+     * was still handed `start` and `cancel` — both effectful — with no way to say
+     * otherwise short of rebuilding the contract by hand.
+     *
+     * The default is unchanged on purpose. Unlike the tracking ingest, an async
+     * operation is a plausible thing for an agent to start and follow, so this
+     * says who decides rather than deciding for everyone.
+     */
+    expose?: Partial<Record<AsyncOperationCapability, readonly Transport[]>>;
 }
 export type AsyncOperationContractConfig<TStartInput extends ZodType, TId extends ZodType, TSnapshot extends ZodType, TCancel extends true | undefined = undefined, TResult extends ZodType | undefined = undefined, TArtifacts extends ZodType | undefined = undefined, TScope extends string = 'public', TScopes extends Partial<Record<AsyncOperationCapability, string>> = Record<never, never>> = AsyncOperationContractBaseConfig<TStartInput, TId, TSnapshot, TCancel, TResult, TArtifacts, TScope, TScopes> & {
     startOutput?: never;