@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/chunk-E66PKKDL.js

@@ -0,0 +1,772 @@
+// src/execution/shared/usage.ts
+function cloneUsage(usage) {
+  return { ...usage };
+}
+
+// src/execution/turn/step-ledger.ts
+var AgentTurnStateConflictError = class extends Error {
+  conflict;
+  constructor(conflict) {
+    super(
+      `Conflicting turn-state progress for tool call '${conflict.toolCallId}' at step ${conflict.step}: ${conflict.reason}`
+    );
+    this.name = "AgentTurnStateConflictError";
+    this.conflict = conflict;
+  }
+};
+var DEFAULT_RESULT_PREVIEW_CHARS = 2e3;
+var DEFAULT_MAX_RAW_RESULT_CHARS = 8e3;
+function cloneToolRecord(toolCall) {
+  return {
+    ...toolCall,
+    ...toolCall.result !== void 0 ? { result: cloneUnknown(toolCall.result) } : {},
+    ...toolCall.metadata ? { metadata: structuredClone(toolCall.metadata) } : {},
+    ...toolCall.replayPolicy ? { replayPolicy: { ...toolCall.replayPolicy } } : {}
+  };
+}
+function cloneStepRecord(step) {
+  return {
+    ...step,
+    toolCalls: step.toolCalls.map(cloneToolRecord),
+    ...step.usage ? { usage: cloneUsage(step.usage) } : {},
+    ...step.commit ? { commit: { ...step.commit } } : {}
+  };
+}
+function cloneAgentTurnStepLedger(ledger) {
+  return (ledger ?? []).map(cloneStepRecord);
+}
+function latestTimestamp(left, right) {
+  return left > right ? left : right;
+}
+function cloneUnknown(value) {
+  try {
+    return structuredClone(value);
+  } catch {
+    return value;
+  }
+}
+function truncateResultPreview(value, maxChars) {
+  if (value.length <= maxChars) {
+    return { preview: value, truncated: false };
+  }
+  if (maxChars <= 0) {
+    return { preview: "", truncated: true };
+  }
+  const headChars = Math.ceil(maxChars * 0.7);
+  const tailChars = Math.max(0, maxChars - headChars);
+  const head = value.slice(0, headChars);
+  const tail = tailChars > 0 ? value.slice(-tailChars) : "";
+  const omitted = value.length - head.length - tail.length;
+  return {
+    preview: `${head}
+
+... [${omitted} chars truncated] ...${tail ? `
+
+${tail}` : ""}`,
+    truncated: true
+  };
+}
+function serializeToolResult(value) {
+  if (typeof value === "string") {
+    return { text: value, format: "text" };
+  }
+  if (value === void 0) {
+    return { text: "undefined", format: "undefined" };
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return { text: String(value), format: "primitive" };
+  }
+  try {
+    const json = JSON.stringify(value);
+    if (json !== void 0) {
+      return { text: json, format: "json" };
+    }
+  } catch {
+  }
+  return { text: String(value), format: "unserializable" };
+}
+function captureToolResult(value, options = {}) {
+  const { text, format } = serializeToolResult(value);
+  const maxPreviewChars = options.maxPreviewChars ?? DEFAULT_RESULT_PREVIEW_CHARS;
+  const maxRawResultChars = options.maxRawResultChars ?? DEFAULT_MAX_RAW_RESULT_CHARS;
+  const { preview, truncated } = truncateResultPreview(text, maxPreviewChars);
+  const mode = options.mode ?? "preview";
+  return {
+    resultPreview: preview,
+    resultCharLength: text.length,
+    resultTruncated: truncated,
+    resultFormat: format,
+    ...mode === "full" || mode === "small" && text.length <= maxRawResultChars ? { result: cloneUnknown(value) } : {}
+  };
+}
+var STEP_STATUS_RANK = {
+  running: 0,
+  "waiting-tools": 1,
+  completed: 2,
+  committing: 3,
+  committed: 4,
+  failed: 5
+};
+function latestStepStatus(previous, incoming) {
+  return STEP_STATUS_RANK[incoming] >= STEP_STATUS_RANK[previous] ? incoming : previous;
+}
+function latestCommitStatus(previous, incoming) {
+  return incoming === "committed" || previous === "committing" ? incoming : previous;
+}
+function isTerminalToolStatus(status) {
+  return status !== "requested";
+}
+function terminalToolRecordsMatch(previous, incoming) {
+  return previous.status === incoming.status && previous.error === incoming.error && previous.resultPreview === incoming.resultPreview && previous.resultCharLength === incoming.resultCharLength && previous.resultTruncated === incoming.resultTruncated && previous.resultFormat === incoming.resultFormat;
+}
+function assertNoToolResultConflict(step, previous, incoming) {
+  if (!isTerminalToolStatus(previous.status) || !isTerminalToolStatus(incoming.status)) {
+    return;
+  }
+  if (terminalToolRecordsMatch(previous, incoming)) {
+    return;
+  }
+  throw new AgentTurnStateConflictError({
+    kind: "tool-result",
+    step,
+    toolCallId: previous.toolCallId,
+    toolName: incoming.toolName || previous.toolName,
+    previousStatus: previous.status,
+    incomingStatus: incoming.status,
+    reason: previous.status === incoming.status ? "terminal tool results differ" : "terminal tool statuses differ"
+  });
+}
+function mergeToolRecord(step, previous, incoming) {
+  assertNoToolResultConflict(step, previous, incoming);
+  const status = incoming.status === "requested" && previous.status !== "requested" ? previous.status : incoming.status;
+  return cloneToolRecord({
+    ...previous,
+    ...incoming,
+    status,
+    ...previous.args !== void 0 || incoming.args !== void 0 ? { args: incoming.args ?? previous.args } : {},
+    ...previous.requestedAt || incoming.requestedAt ? { requestedAt: incoming.requestedAt ?? previous.requestedAt } : {},
+    ...previous.resolvedAt || incoming.resolvedAt ? { resolvedAt: incoming.resolvedAt ?? previous.resolvedAt } : {},
+    ...previous.resultPreview !== void 0 || incoming.resultPreview !== void 0 ? { resultPreview: incoming.resultPreview ?? previous.resultPreview } : {},
+    ...previous.resultCharLength !== void 0 || incoming.resultCharLength !== void 0 ? {
+      resultCharLength: incoming.resultCharLength ?? previous.resultCharLength
+    } : {},
+    ...previous.resultTruncated !== void 0 || incoming.resultTruncated !== void 0 ? {
+      resultTruncated: incoming.resultTruncated ?? previous.resultTruncated
+    } : {},
+    ...previous.resultFormat || incoming.resultFormat ? { resultFormat: incoming.resultFormat ?? previous.resultFormat } : {},
+    ...previous.result !== void 0 || incoming.result !== void 0 ? { result: incoming.result ?? previous.result } : {},
+    ...previous.metadata || incoming.metadata ? {
+      metadata: {
+        ...previous.metadata ?? {},
+        ...incoming.metadata ?? {}
+      }
+    } : {},
+    ...previous.replayPolicy || incoming.replayPolicy ? { replayPolicy: incoming.replayPolicy ?? previous.replayPolicy } : {}
+  });
+}
+function mergeCommitRecord(previous, incoming) {
+  const base = incoming ?? previous;
+  if (!base) {
+    return void 0;
+  }
+  return {
+    kind: incoming?.kind ?? previous?.kind ?? base.kind,
+    status: previous && incoming ? latestCommitStatus(previous.status, incoming.status) : base.status,
+    ...previous?.startedAt || incoming?.startedAt ? { startedAt: incoming?.startedAt ?? previous?.startedAt } : {},
+    ...previous?.finishedAt || incoming?.finishedAt ? { finishedAt: incoming?.finishedAt ?? previous?.finishedAt } : {},
+    ...previous?.messageRole || incoming?.messageRole ? { messageRole: incoming?.messageRole ?? previous?.messageRole } : {},
+    ...previous?.pendingToolCallCount !== void 0 || incoming?.pendingToolCallCount !== void 0 ? {
+      pendingToolCallCount: incoming?.pendingToolCallCount ?? previous?.pendingToolCallCount
+    } : {}
+  };
+}
+function mergeStepRecord(previous, incoming) {
+  const toolsById = /* @__PURE__ */ new Map();
+  for (const toolCall of previous.toolCalls) {
+    toolsById.set(toolCall.toolCallId, cloneToolRecord(toolCall));
+  }
+  for (const toolCall of incoming.toolCalls) {
+    const existing = toolsById.get(toolCall.toolCallId);
+    toolsById.set(
+      toolCall.toolCallId,
+      existing ? mergeToolRecord(previous.step, existing, toolCall) : cloneToolRecord(toolCall)
+    );
+  }
+  return cloneStepRecord({
+    ...previous,
+    ...incoming,
+    status: latestStepStatus(previous.status, incoming.status),
+    startedAt: previous.startedAt || incoming.startedAt,
+    updatedAt: latestTimestamp(previous.updatedAt, incoming.updatedAt),
+    text: incoming.text.length >= previous.text.length ? incoming.text : previous.text,
+    toolCalls: Array.from(toolsById.values()),
+    ...previous.usage || incoming.usage ? { usage: incoming.usage ?? previous.usage } : {},
+    ...previous.finishReason || incoming.finishReason ? { finishReason: incoming.finishReason ?? previous.finishReason } : {},
+    ...previous.commit || incoming.commit ? { commit: mergeCommitRecord(previous.commit, incoming.commit) } : {}
+  });
+}
+function mergeAgentTurnStepLedgers(previous, incoming) {
+  const byStep = /* @__PURE__ */ new Map();
+  for (const step of cloneAgentTurnStepLedger(previous)) {
+    byStep.set(step.step, step);
+  }
+  for (const step of cloneAgentTurnStepLedger(incoming)) {
+    const existing = byStep.get(step.step);
+    byStep.set(step.step, existing ? mergeStepRecord(existing, step) : step);
+  }
+  return Array.from(byStep.values()).sort(
+    (left, right) => left.step - right.step
+  );
+}
+function findStepIndex(ledger, step) {
+  return ledger.findIndex((entry) => entry.step === step);
+}
+function getStepNumber(event, options) {
+  if ("step" in event && typeof event.step === "number") {
+    return event.step;
+  }
+  return options.currentStep && options.currentStep > 0 ? options.currentStep : void 0;
+}
+function upsertStep(ledger, step, updatedAt, update) {
+  const index = findStepIndex(ledger, step);
+  const existing = index >= 0 ? ledger[index] : {
+    step,
+    status: "running",
+    startedAt: updatedAt,
+    updatedAt,
+    text: "",
+    toolCalls: []
+  };
+  const next = update(existing);
+  if (index >= 0) {
+    ledger[index] = next;
+    return ledger;
+  }
+  ledger.push(next);
+  return ledger;
+}
+function upsertToolCall(record, toolCallId, update) {
+  const toolIndex = record.toolCalls.findIndex(
+    (toolCall) => toolCall.toolCallId === toolCallId
+  );
+  const existing = toolIndex >= 0 ? record.toolCalls[toolIndex] : {
+    toolCallId,
+    toolName: "unknown",
+    status: "requested"
+  };
+  const nextTool = update(existing);
+  const toolCalls = [...record.toolCalls];
+  if (toolIndex >= 0) {
+    toolCalls[toolIndex] = nextTool;
+  } else {
+    toolCalls.push(nextTool);
+  }
+  return {
+    ...record,
+    toolCalls
+  };
+}
+function toolResultStatus(metadata) {
+  return metadata?.approvalCorrection ? "denied" : "succeeded";
+}
+function commitKind(boundary) {
+  if (boundary === "step-commit-start" || boundary === "step-commit-finish") {
+    return "step";
+  }
+  if (boundary === "output-commit-start" || boundary === "output-commit-finish") {
+    return "output";
+  }
+  return void 0;
+}
+function commitStatus(boundary) {
+  if (boundary.endsWith("-start")) {
+    return "committing";
+  }
+  if (boundary.endsWith("-finish")) {
+    return "committed";
+  }
+  return void 0;
+}
+function getCurrentAgentTurnStepRecord(ledger) {
+  const current = ledger?.at(-1);
+  return current ? cloneStepRecord(current) : void 0;
+}
+function advanceAgentTurnStepLedger(ledger, event, updatedAt, options = {}) {
+  const next = cloneAgentTurnStepLedger(ledger);
+  const step = getStepNumber(event, options);
+  switch (event.type) {
+    case "step-start":
+      return upsertStep(next, event.step, updatedAt, (record) => {
+        const rest = { ...record };
+        delete rest.usage;
+        delete rest.finishReason;
+        delete rest.commit;
+        return {
+          ...rest,
+          status: "running",
+          startedAt: record.startedAt || updatedAt,
+          updatedAt,
+          text: "",
+          toolCalls: []
+        };
+      });
+    case "text-delta":
+      if (!step) return next;
+      return upsertStep(next, step, updatedAt, (record) => ({
+        ...record,
+        status: record.status === "failed" ? record.status : "running",
+        updatedAt,
+        text: `${record.text}${event.text}`
+      }));
+    case "tool-start":
+      if (!step) return next;
+      return upsertStep(
+        next,
+        step,
+        updatedAt,
+        (record) => upsertToolCall(
+          {
+            ...record,
+            status: "waiting-tools",
+            updatedAt
+          },
+          event.toolCallId,
+          (toolCall) => ({
+            ...toolCall,
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            args: event.input,
+            status: "requested",
+            requestedAt: updatedAt,
+            ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+          })
+        )
+      );
+    case "tool-result":
+      if (!step) return next;
+      return upsertStep(
+        next,
+        step,
+        updatedAt,
+        (record) => upsertToolCall(
+          {
+            ...record,
+            status: "waiting-tools",
+            updatedAt
+          },
+          event.toolCallId,
+          (toolCall) => ({
+            ...toolCall,
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            status: toolResultStatus(event.metadata),
+            ...captureToolResult(event.result, options.toolResultCapture),
+            resolvedAt: updatedAt,
+            ...event.metadata ? { metadata: structuredClone(event.metadata) } : {},
+            ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+          })
+        )
+      );
+    case "tool-error":
+      if (!step) return next;
+      return upsertStep(
+        next,
+        step,
+        updatedAt,
+        (record) => upsertToolCall(
+          {
+            ...record,
+            status: "waiting-tools",
+            updatedAt
+          },
+          event.toolCallId,
+          (toolCall) => ({
+            ...toolCall,
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            status: "failed",
+            error: event.error,
+            resolvedAt: updatedAt,
+            ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+          })
+        )
+      );
+    case "step-finish":
+      return upsertStep(next, event.step, updatedAt, (record) => ({
+        ...record,
+        status: event.finishReason === "tool-calls" ? "waiting-tools" : "completed",
+        updatedAt,
+        ...event.usage ? { usage: cloneUsage(event.usage) } : {},
+        ...event.finishReason ? { finishReason: event.finishReason } : {}
+      }));
+    case "turn-boundary": {
+      const kind = commitKind(event.boundary);
+      const status = commitStatus(event.boundary);
+      if (!step || !kind || !status) {
+        return next;
+      }
+      return upsertStep(next, step, updatedAt, (record) => ({
+        ...record,
+        status,
+        updatedAt,
+        commit: {
+          kind,
+          status,
+          ...status === "committing" ? { startedAt: updatedAt } : {
+            ...record.commit?.startedAt ? { startedAt: record.commit.startedAt } : {},
+            finishedAt: updatedAt
+          },
+          ...event.messageRole ? { messageRole: event.messageRole } : {},
+          ...event.pendingToolCallCount !== void 0 ? { pendingToolCallCount: event.pendingToolCallCount } : record.commit?.pendingToolCallCount !== void 0 ? { pendingToolCallCount: record.commit.pendingToolCallCount } : {}
+        }
+      }));
+    }
+    case "error":
+      if (!step) return next;
+      return failAgentTurnStepLedger(next, event.error, updatedAt, step);
+    default:
+      return next;
+  }
+}
+function failAgentTurnStepLedger(ledger, error, updatedAt, currentStep) {
+  const next = cloneAgentTurnStepLedger(ledger);
+  const step = currentStep && currentStep > 0 ? currentStep : next.at(-1)?.step;
+  if (!step) {
+    return next;
+  }
+  return upsertStep(next, step, updatedAt, (record) => ({
+    ...record,
+    status: "failed",
+    updatedAt,
+    toolCalls: record.toolCalls.map(
+      (toolCall) => toolCall.status === "requested" ? {
+        ...toolCall,
+        status: "failed",
+        error: error.message,
+        resolvedAt: updatedAt
+      } : toolCall
+    )
+  }));
+}
+
+// src/execution/turn/state.ts
+var EMPTY_USAGE = {
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0
+};
+function normalizeUsage(usage) {
+  if (!usage) {
+    return cloneUsage(EMPTY_USAGE);
+  }
+  return {
+    inputTokens: usage.inputTokens ?? 0,
+    outputTokens: usage.outputTokens ?? 0,
+    totalTokens: usage.totalTokens ?? 0
+  };
+}
+function removeActiveToolCall(toolCalls, toolCallId) {
+  return toolCalls.filter((toolCall) => toolCall.toolCallId !== toolCallId);
+}
+function cloneActiveToolCall(toolCall) {
+  return {
+    ...toolCall,
+    ...toolCall.replayPolicy ? { replayPolicy: { ...toolCall.replayPolicy } } : {}
+  };
+}
+function cloneResolvedToolCall(toolCall) {
+  return {
+    ...toolCall,
+    ...toolCall.metadata ? { metadata: structuredClone(toolCall.metadata) } : {},
+    ...toolCall.replayPolicy ? { replayPolicy: { ...toolCall.replayPolicy } } : {}
+  };
+}
+function toolOutcomeStatus(outcome) {
+  return outcome === "result" ? "succeeded" : "failed";
+}
+function stringifyForConflict(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+function resolvedToolCallsMatch(previous, incoming) {
+  if (previous.outcome !== incoming.outcome) {
+    return false;
+  }
+  if (Object.is(previous.value, incoming.value)) {
+    return true;
+  }
+  const previousJson = stringifyForConflict(previous.value);
+  const incomingJson = stringifyForConflict(incoming.value);
+  return previousJson !== void 0 && previousJson === incomingJson;
+}
+function mergeResolvedToolCalls(step, previous, incoming) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const toolCall of previous) {
+    byId.set(toolCall.toolCallId, cloneResolvedToolCall(toolCall));
+  }
+  for (const toolCall of incoming) {
+    const existing = byId.get(toolCall.toolCallId);
+    if (existing && !resolvedToolCallsMatch(existing, toolCall)) {
+      throw new AgentTurnStateConflictError({
+        kind: "tool-result",
+        step,
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName || existing.toolName,
+        previousStatus: toolOutcomeStatus(existing.outcome),
+        incomingStatus: toolOutcomeStatus(toolCall.outcome),
+        reason: "resolved tool-call results differ"
+      });
+    }
+    byId.set(toolCall.toolCallId, cloneResolvedToolCall(toolCall));
+  }
+  return Array.from(byId.values());
+}
+function mergeActiveToolCalls(previous, incoming, resolved) {
+  const resolvedIds = new Set(resolved.map((toolCall) => toolCall.toolCallId));
+  const byId = /* @__PURE__ */ new Map();
+  for (const toolCall of previous) {
+    if (!resolvedIds.has(toolCall.toolCallId)) {
+      byId.set(toolCall.toolCallId, cloneActiveToolCall(toolCall));
+    }
+  }
+  for (const toolCall of incoming) {
+    if (!resolvedIds.has(toolCall.toolCallId)) {
+      byId.set(toolCall.toolCallId, cloneActiveToolCall(toolCall));
+    }
+  }
+  return Array.from(byId.values());
+}
+function createAgentTurnState(options) {
+  const restore = options.restoreFrom;
+  return {
+    sessionId: options.sessionId,
+    phase: "initializing",
+    step: restore?.step ?? 0,
+    response: restore?.response ?? "",
+    usage: restore?.usage ? cloneUsage(restore.usage) : cloneUsage(EMPTY_USAGE),
+    eventCount: restore?.eventCount ?? 0,
+    activeToolCalls: [],
+    resolvedToolCalls: [],
+    stepLedger: [],
+    startedAt: options.startedAt,
+    updatedAt: options.startedAt
+  };
+}
+function advanceAgentTurnState(state, event, updatedAt, options = {}) {
+  const next = {
+    ...state,
+    usage: cloneUsage(state.usage),
+    activeToolCalls: state.activeToolCalls.map((toolCall) => ({ ...toolCall })),
+    resolvedToolCalls: state.resolvedToolCalls.map((toolCall) => ({
+      ...toolCall,
+      ...toolCall.metadata ? { metadata: structuredClone(toolCall.metadata) } : {}
+    })),
+    stepLedger: cloneAgentTurnStepLedger(state.stepLedger),
+    eventCount: state.eventCount + 1,
+    lastEvent: event,
+    updatedAt
+  };
+  switch (event.type) {
+    case "step-start":
+      next.phase = "running-model";
+      next.step = event.step;
+      next.maxSteps = event.maxSteps;
+      next.activeToolCalls = [];
+      next.resolvedToolCalls = [];
+      next.lastFinishReason = void 0;
+      delete next.error;
+      break;
+    case "text-delta":
+      next.response += event.text;
+      break;
+    case "tool-start":
+      next.phase = "running-tools";
+      next.activeToolCalls = [
+        ...removeActiveToolCall(next.activeToolCalls, event.toolCallId),
+        {
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          input: event.input,
+          startedAt: updatedAt,
+          ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+        }
+      ];
+      break;
+    case "tool-result":
+      next.phase = "running-tools";
+      next.activeToolCalls = removeActiveToolCall(
+        next.activeToolCalls,
+        event.toolCallId
+      );
+      next.resolvedToolCalls = [
+        ...next.resolvedToolCalls,
+        {
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          outcome: "result",
+          value: event.result,
+          ...event.metadata ? { metadata: structuredClone(event.metadata) } : {},
+          resolvedAt: updatedAt,
+          ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+        }
+      ];
+      break;
+    case "tool-error":
+      next.phase = "running-tools";
+      next.activeToolCalls = removeActiveToolCall(
+        next.activeToolCalls,
+        event.toolCallId
+      );
+      next.resolvedToolCalls = [
+        ...next.resolvedToolCalls,
+        {
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          outcome: "error",
+          value: event.error,
+          resolvedAt: updatedAt,
+          ...options.toolReplayPolicy ? { replayPolicy: options.toolReplayPolicy } : {}
+        }
+      ];
+      break;
+    case "step-finish":
+      next.phase = "committing-step";
+      next.step = event.step;
+      next.usage = normalizeUsage(event.usage ?? next.usage);
+      next.lastFinishReason = event.finishReason;
+      break;
+    case "turn-boundary":
+      next.lastBoundary = {
+        kind: event.boundary,
+        createdAt: updatedAt,
+        ...event.step !== void 0 ? { step: event.step } : {},
+        ...event.messageRole ? { messageRole: event.messageRole } : {},
+        ...event.pendingToolCallCount !== void 0 ? { pendingToolCallCount: event.pendingToolCallCount } : {}
+      };
+      switch (event.boundary) {
+        case "input-commit-start":
+        case "input-commit-finish":
+        case "intervention-commit-start":
+        case "intervention-commit-finish":
+          next.phase = "committing-input";
+          break;
+        case "step-commit-start":
+        case "step-commit-finish":
+          next.phase = "committing-step";
+          break;
+        case "output-commit-start":
+        case "output-commit-finish":
+          next.phase = "committing-output";
+          break;
+      }
+      break;
+    case "complete":
+      next.phase = "completed";
+      next.usage = normalizeUsage(event.usage ?? next.usage);
+      break;
+    case "error":
+      next.phase = "failed";
+      next.error = event.error.message;
+      break;
+    default:
+      break;
+  }
+  next.stepLedger = advanceAgentTurnStepLedger(
+    state.stepLedger,
+    event,
+    updatedAt,
+    {
+      currentStep: next.step || state.step,
+      ...options.toolReplayPolicy ? { toolReplayPolicy: options.toolReplayPolicy } : {},
+      ...options.toolResultCapture ? { toolResultCapture: options.toolResultCapture } : {}
+    }
+  );
+  return next;
+}
+function failAgentTurnState(state, error, updatedAt) {
+  return {
+    ...state,
+    usage: cloneUsage(state.usage),
+    activeToolCalls: state.activeToolCalls.map((toolCall) => ({ ...toolCall })),
+    resolvedToolCalls: state.resolvedToolCalls.map((toolCall) => ({
+      ...toolCall,
+      ...toolCall.metadata ? { metadata: structuredClone(toolCall.metadata) } : {}
+    })),
+    stepLedger: failAgentTurnStepLedger(
+      state.stepLedger,
+      error,
+      updatedAt,
+      state.step
+    ),
+    phase: "failed",
+    error: error.message,
+    updatedAt
+  };
+}
+function mergeAgentTurnStateProgress(previous, incoming) {
+  if (!previous) {
+    return {
+      ...incoming,
+      usage: cloneUsage(incoming.usage),
+      activeToolCalls: incoming.activeToolCalls.map(cloneActiveToolCall),
+      resolvedToolCalls: incoming.resolvedToolCalls.map(cloneResolvedToolCall),
+      stepLedger: cloneAgentTurnStepLedger(incoming.stepLedger)
+    };
+  }
+  const resolvedToolCalls = mergeResolvedToolCalls(
+    incoming.step || previous.step,
+    previous.resolvedToolCalls,
+    incoming.resolvedToolCalls
+  );
+  return {
+    ...incoming,
+    usage: cloneUsage(incoming.usage),
+    activeToolCalls: mergeActiveToolCalls(
+      previous.activeToolCalls,
+      incoming.activeToolCalls,
+      resolvedToolCalls
+    ),
+    resolvedToolCalls,
+    stepLedger: mergeAgentTurnStepLedgers(
+      previous.stepLedger,
+      incoming.stepLedger
+    )
+  };
+}
+
+// src/types/messages.ts
+function accumulateUsage(current, next) {
+  if (!next) return current;
+  if (!current) {
+    return {
+      inputTokens: next.inputTokens ?? 0,
+      outputTokens: next.outputTokens ?? 0,
+      totalTokens: next.totalTokens ?? 0,
+      cacheReadTokens: (next.cacheReadTokens ?? 0) || void 0,
+      cacheWriteTokens: (next.cacheWriteTokens ?? 0) || void 0
+    };
+  }
+  const cacheRead = (current.cacheReadTokens ?? 0) + (next.cacheReadTokens ?? 0);
+  const cacheWrite = (current.cacheWriteTokens ?? 0) + (next.cacheWriteTokens ?? 0);
+  return {
+    inputTokens: (current.inputTokens ?? 0) + (next.inputTokens ?? 0),
+    outputTokens: (current.outputTokens ?? 0) + (next.outputTokens ?? 0),
+    totalTokens: (current.totalTokens ?? 0) + (next.totalTokens ?? 0),
+    cacheReadTokens: cacheRead || void 0,
+    cacheWriteTokens: cacheWrite || void 0
+  };
+}
+
+export {
+  cloneUsage,
+  AgentTurnStateConflictError,
+  getCurrentAgentTurnStepRecord,
+  createAgentTurnState,
+  advanceAgentTurnState,
+  failAgentTurnState,
+  mergeAgentTurnStateProgress,
+  accumulateUsage
+};