@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/best-effort.cjs

@@ -0,0 +1,88 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/best-effort.ts
+var best_effort_exports = {};
+__export(best_effort_exports, {
+  bestEffort: () => bestEffort
+});
+module.exports = __toCommonJS(best_effort_exports);
+
+// src/logger.ts
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+// src/best-effort.ts
+var logger = getLogger("subagents");
+function bestEffort(err, context, level = "debug") {
+  const detail = err instanceof Error ? err.message : err;
+  const msg = `[subagents] best-effort ${context} failed`;
+  if (level === "error") {
+    logger.error(msg, { detail });
+  } else {
+    logger.debug(msg, { detail });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  bestEffort
+});

package/dist/best-effort.d.cts

@@ -0,0 +1,14 @@
+/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
+type BestEffortLevel = "debug" | "error";
+/**
+ * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
+ *
+ *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
+ *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
+ *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
+ *
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
+ */
+declare function bestEffort(err: unknown, context: string, level?: BestEffortLevel): void;
+
+export { type BestEffortLevel, bestEffort };

package/dist/best-effort.d.ts

@@ -0,0 +1,14 @@
+/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
+type BestEffortLevel = "debug" | "error";
+/**
+ * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
+ *
+ *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
+ *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
+ *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
+ *
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
+ */
+declare function bestEffort(err: unknown, context: string, level?: BestEffortLevel): void;
+
+export { type BestEffortLevel, bestEffort };

package/dist/best-effort.js

@@ -0,0 +1,8 @@
+import {
+  bestEffort
+} from "./chunk-EJMF63R5.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  bestEffort
+};

package/dist/chunk-365AUV6N.js

@@ -0,0 +1,67 @@
+// src/nesting-guard.ts
+import { AsyncLocalStorage } from "async_hooks";
+var NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+var NATIVE_NESTED_KEYS = ["CLAUDECODE", "ZSW_NESTED"];
+var NATIVE_NESTED_PREFIXES = ["PI_SUBAGENT_"];
+var NestedSpawnRejectedError = class extends Error {
+  code = "nested_spawn_rejected";
+  /** 恢复指引：指向具体下一步，非安慰性文案。 */
+  recovery;
+  constructor() {
+    super(
+      "nested_spawn_rejected: this process is already a subagent (XYZ_AGENT_SUBAGENT=1)"
+    );
+    this.name = "NestedSpawnRejectedError";
+    this.recovery = "Subagents must not spawn further subagents (unbounded recursion guard). Do the work directly inside the current task instead of delegating.";
+  }
+};
+function buildNestedSpawnEnv(baseEnv) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (NATIVE_NESTED_KEYS.includes(key)) continue;
+    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    env[key] = value;
+  }
+  env[NESTED_SPAWN_ENV] = "1";
+  return env;
+}
+function assertNotNestedSpawn(env) {
+  if (env[NESTED_SPAWN_ENV] === "1") {
+    throw new NestedSpawnRejectedError();
+  }
+}
+var ExecutionNestingContext = class {
+  als = new AsyncLocalStorage();
+  baselineState = null;
+  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+  setBaseline(state) {
+    this.baselineState = state;
+  }
+  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+  current() {
+    return this.als.getStore() ?? this.baselineState;
+  }
+  /**
+   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+   */
+  baseline() {
+    return this.baselineState;
+  }
+  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+  run(state, fn) {
+    return this.als.run(state, fn);
+  }
+  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+  enterWith(state) {
+    this.als.enterWith(state);
+  }
+};
+
+export {
+  NESTED_SPAWN_ENV,
+  NestedSpawnRejectedError,
+  buildNestedSpawnEnv,
+  assertNotNestedSpawn,
+  ExecutionNestingContext
+};

package/dist/chunk-3K2P2CM2.js

@@ -0,0 +1,127 @@
+import {
+  getLogger
+} from "./chunk-75QEMUGV.js";
+
+// src/spawn.ts
+import { spawn } from "child_process";
+var logger = getLogger("engine-sdk/spawn");
+var FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"];
+function spawnEngineChild(opts) {
+  for (const key of FORBIDDEN_OPTION_KEYS) {
+    if (key in opts) {
+      throw new Error(
+        `spawnEngineChild: option "${key}" is hardcoded by the engine spawn contract (detached:false / windowsHide:true / child stdin is always its own pipe); remove it from the call site`
+      );
+    }
+  }
+  const child = spawn(opts.command, [...opts.args], {
+    cwd: opts.cwd,
+    env: opts.env,
+    detached: false,
+    windowsHide: true,
+    stdio: ["pipe", opts.stdout ?? "pipe", opts.stderr ?? "pipe"]
+  });
+  if (opts.signal !== void 0) {
+    opts.signal.addEventListener(
+      "abort",
+      () => {
+        child.kill("SIGTERM");
+      },
+      { once: true }
+    );
+  }
+  return child;
+}
+var DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 3e4;
+var ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
+var SWEEP_INTERVAL_MS = 1e3;
+function resolveHostRequestTimeoutMs(opts) {
+  if (opts.hostRequestTimeoutMs !== void 0) return opts.hostRequestTimeoutMs;
+  const raw = (opts.timeoutEnv ?? process.env)[ENGINE_HOST_REQUEST_TIMEOUT_ENV];
+  if (raw === void 0 || raw === "") return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    logger.warn(
+      `invalid ${ENGINE_HOST_REQUEST_TIMEOUT_ENV}=${JSON.stringify(raw)}, falling back to ${DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS}ms`
+    );
+    return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  }
+  return parsed;
+}
+function killOwnProcessGroup() {
+  const pid = process.pid;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch (err) {
+    logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
+    process.kill(pid, "SIGKILL");
+  }
+}
+function armEngineSelfDestruct(opts) {
+  const timeoutMs = resolveHostRequestTimeoutMs(opts);
+  const killSelf = opts.killSelf ?? killOwnProcessGroup;
+  const pending = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const destroy = (reason) => {
+    if (disposed) return;
+    disposed = true;
+    clearInterval(timer);
+    opts.stdin.removeAllListeners?.("end");
+    opts.stdin.removeAllListeners?.("close");
+    logger.warn(`engine self-destruct: ${reason}`);
+    killSelf();
+  };
+  opts.stdin.once("end", () => destroy("host stdin EOF (end)"));
+  opts.stdin.once("close", () => destroy("host stdin closed"));
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const [id, startedAt] of pending) {
+      if (now - startedAt > timeoutMs) {
+        destroy(`unacked reverse request ${id} exceeded ${timeoutMs}ms without host ack`);
+        return;
+      }
+    }
+  }, SWEEP_INTERVAL_MS);
+  timer.unref?.();
+  return {
+    started(id) {
+      if (!disposed) pending.set(id, Date.now());
+    },
+    acked(id) {
+      pending.delete(id);
+    },
+    settled(id) {
+      pending.delete(id);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearInterval(timer);
+      opts.stdin.removeAllListeners?.("end");
+      opts.stdin.removeAllListeners?.("close");
+    }
+  };
+}
+function pumpNdjsonLines(stream, onLine) {
+  if (stream === null || stream === void 0) return;
+  stream.setEncoding("utf8");
+  let buffer = "";
+  stream.on("data", (chunk) => {
+    buffer += chunk;
+    let nl = buffer.indexOf("\n");
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      onLine(line);
+      nl = buffer.indexOf("\n");
+    }
+  });
+}
+
+export {
+  spawnEngineChild,
+  DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  armEngineSelfDestruct,
+  pumpNdjsonLines
+};

package/dist/chunk-75QEMUGV.js

@@ -0,0 +1,58 @@
+// src/logger.ts
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+function configureLoggerSink(sink) {
+  getSinkSlot().current = sink;
+}
+function resetLoggerSinkForTests() {
+  getSinkSlot().current = void 0;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+export {
+  configureLoggerSink,
+  resetLoggerSinkForTests,
+  getLogger
+};

package/dist/chunk-7I4XGL5J.js

@@ -0,0 +1,95 @@
+// src/ui-channels.ts
+var NUL = "\0";
+function normalizeChannelName(markerLiteral) {
+  let name = markerLiteral;
+  if (name.startsWith("XYZ_")) {
+    name = name.slice("XYZ_".length);
+  }
+  if (name.endsWith(":")) {
+    name = name.slice(0, -1);
+  }
+  return name.toLowerCase();
+}
+function parseMarkerFromField(str) {
+  if (!str.startsWith(NUL)) return void 0;
+  const literal = str.slice(NUL.length);
+  if (literal === "") return void 0;
+  return normalizeChannelName(literal);
+}
+function parseInlineMarkerFromField(str) {
+  if (!str.startsWith(NUL)) return void 0;
+  const rest = str.slice(NUL.length);
+  const colonIdx = rest.indexOf(":");
+  let literal;
+  if (colonIdx >= 0) {
+    literal = rest.slice(0, colonIdx + 1);
+  } else {
+    literal = rest;
+  }
+  if (literal === "") return void 0;
+  return { channel: normalizeChannelName(literal) };
+}
+function parseFromMarkerString(title, options) {
+  if (title === void 0) return {};
+  const channel = parseMarkerFromField(title);
+  if (channel === void 0) return {};
+  let payload;
+  if (options !== void 0 && options.length > 0) {
+    try {
+      payload = JSON.parse(options[0]);
+    } catch {
+      payload = void 0;
+    }
+  }
+  return { channel, channelPayload: payload };
+}
+function parseFromMarkerArray(widgetLines) {
+  if (widgetLines === void 0 || widgetLines.length === 0) return {};
+  const firstLine = widgetLines[0];
+  if (typeof firstLine !== "string") return {};
+  const parsed = parseInlineMarkerFromField(firstLine);
+  if (parsed === void 0) return {};
+  let payload;
+  const rest = firstLine.slice(NUL.length);
+  const colonIdx = rest.indexOf(":");
+  if (colonIdx >= 0) {
+    const jsonStr = rest.slice(colonIdx + 1);
+    if (jsonStr !== "") {
+      try {
+        payload = JSON.parse(jsonStr);
+      } catch {
+        payload = void 0;
+      }
+    }
+  }
+  return { channel: parsed.channel, channelPayload: payload };
+}
+function parseChannel(req) {
+  switch (req.method) {
+    case "select":
+      return parseFromMarkerString(req.title, req.options);
+    case "setWidget":
+      return parseFromMarkerArray(req.widgetLines);
+    default:
+      return {};
+  }
+}
+function createUiChannelRegistry() {
+  const handlers = /* @__PURE__ */ new Map();
+  return {
+    register(channel, handler) {
+      handlers.set(channel, handler);
+    },
+    resolve(channel) {
+      return handlers.get(channel);
+    },
+    list() {
+      return Array.from(handlers.keys());
+    }
+  };
+}
+
+export {
+  parseChannel,
+  createUiChannelRegistry
+};

package/dist/chunk-A75XDJIC.js

@@ -0,0 +1,227 @@
+// src/journal-replay.ts
+function sumUsageField(a, b) {
+  return (a ?? 0) + (b ?? 0);
+}
+function usageFromNext(next) {
+  return {
+    input: next.input ?? 0,
+    output: next.output ?? 0,
+    cacheRead: next.cacheRead ?? 0,
+    cacheWrite: next.cacheWrite ?? 0,
+    cost: next.cost
+  };
+}
+function addUsage(prev, next) {
+  if (prev === void 0) return usageFromNext(next);
+  return {
+    input: sumUsageField(prev.input, next.input),
+    output: sumUsageField(prev.output, next.output),
+    cacheRead: sumUsageField(prev.cacheRead, next.cacheRead),
+    cacheWrite: sumUsageField(prev.cacheWrite, next.cacheWrite),
+    cost: sumUsageField(prev.cost, next.cost)
+  };
+}
+function emptyTurn() {
+  return { text: "", thinking: "", toolCalls: [], usageDelta: void 0, closed: false };
+}
+function createReplayRecord() {
+  return {
+    // turns[] 初始化为 [空 turn]——第一个 turn 从创建即存在，
+    // updateFromEvent 直接往 turns[last] 累积，无需「无 turn」分支判断。
+    turns: [emptyTurn()],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: void 0
+  };
+}
+function currentTurn(record) {
+  const last = record.turns[record.turns.length - 1];
+  if (last !== void 0 && !last.closed) return last;
+  const fresh = emptyTurn();
+  record.turns.push(fresh);
+  return fresh;
+}
+function findRunningToolCall(record, toolName) {
+  for (let t = record.turns.length - 1; t >= 0; t--) {
+    const turn = record.turns[t];
+    if (turn === void 0) continue;
+    for (let i = turn.toolCalls.length - 1; i >= 0; i--) {
+      const tc = turn.toolCalls[i];
+      if (tc?._status === "running" && tc.toolName === toolName) {
+        return [turn, i];
+      }
+    }
+  }
+  return void 0;
+}
+var runningToolIndex = /* @__PURE__ */ new WeakMap();
+function indexToolStart(record, turn, toolName) {
+  let byName = runningToolIndex.get(record);
+  if (byName === void 0) {
+    byName = /* @__PURE__ */ new Map();
+    runningToolIndex.set(record, byName);
+  }
+  const arr = byName.get(toolName);
+  if (arr === void 0) {
+    byName.set(toolName, [{ turn, idx: turn.toolCalls.length - 1 }]);
+  } else {
+    arr.push({ turn, idx: turn.toolCalls.length - 1 });
+  }
+}
+function applyTextDelta(record, event) {
+  currentTurn(record).text += event.delta;
+}
+function applyThinkingDelta(record, event) {
+  currentTurn(record).thinking += event.delta;
+}
+function applyToolStart(record, event) {
+  const tc = {
+    toolName: event.toolName,
+    args: event.args,
+    result: void 0,
+    isError: false,
+    _status: "running",
+    startedTs: Date.now()
+  };
+  const turn = currentTurn(record);
+  turn.toolCalls.push(tc);
+  indexToolStart(record, turn, event.toolName);
+}
+function matchRunningToolCall(record, toolName) {
+  const byName = runningToolIndex.get(record);
+  const arr = byName?.get(toolName);
+  if (arr !== void 0 && arr.length > 0) {
+    const item = arr[arr.length - 1];
+    arr.pop();
+    const tc = item.turn.toolCalls[item.idx];
+    if (tc !== void 0 && tc._status === "running") {
+      return [item.turn, item.idx];
+    }
+  }
+  return findRunningToolCall(record, toolName);
+}
+function applyToolEnd(record, event) {
+  const matched = matchRunningToolCall(record, event.toolName);
+  if (matched !== void 0) {
+    const [turn, i] = matched;
+    const tc = turn.toolCalls[i];
+    tc.args = event.args ?? tc.args;
+    tc.result = event.result;
+    tc.isError = event.isError ?? false;
+    tc._status = event.isError ? "failed" : "done";
+    return;
+  }
+  currentTurn(record).toolCalls.push({
+    toolName: event.toolName,
+    args: event.args,
+    result: event.result,
+    isError: event.isError ?? false,
+    _status: event.isError ? "failed" : "done",
+    startedTs: Date.now()
+  });
+}
+function applyTurnEnd(record) {
+  const turn = currentTurn(record);
+  turn.closed = true;
+  turn.closedTs = Date.now();
+  record.turnCount += 1;
+  record.lastError = void 0;
+}
+function applyMessageEnd(record, event) {
+  if (event.usage) {
+    const turn = currentTurn(record);
+    turn.usageDelta = addUsage(turn.usageDelta, event.usage);
+    record.totalTokens += (event.usage.input ?? 0) + (event.usage.output ?? 0) + (event.usage.cacheRead ?? 0) + (event.usage.cacheWrite ?? 0);
+  }
+  if (event.error) {
+    record.lastError = event.error;
+  }
+}
+function applyErrorEvent(record, event) {
+  record.lastError = event.message;
+}
+function updateFromEvent(record, event) {
+  switch (event.type) {
+    // ── text / thinking：流式累积进当前 turn ──
+    case "text_delta":
+      return applyTextDelta(record, event);
+    case "thinking_delta":
+      return applyThinkingDelta(record, event);
+    // ── tool_start/end：push 进 currentTurn().toolCalls（含完整 result）──
+    case "tool_start":
+      return applyToolStart(record, event);
+    case "tool_end":
+      return applyToolEnd(record, event);
+    // ── turn_end：闭合当前 turn ──
+    case "turn_end":
+      return applyTurnEnd(record);
+    // ── message_end：usage 增量累加 + totalTokens 累加 ──
+    case "message_end":
+      return applyMessageEnd(record, event);
+    // ── error：存 record.lastError ──
+    case "error":
+      return applyErrorEvent(record, event);
+    // ── compaction：不产生数据（不变）──
+    case "compaction":
+      return;
+    default: {
+      const _exhaustive = event;
+      return _exhaustive;
+    }
+  }
+}
+function toExportedToolCall(tc) {
+  return {
+    toolName: tc.toolName,
+    ...tc.args !== void 0 ? { args: tc.args } : {},
+    ...tc.result !== void 0 ? { result: tc.result } : {},
+    ...tc.isError !== void 0 ? { isError: tc.isError } : {}
+  };
+}
+function toReplayedTurn(turn) {
+  return {
+    text: turn.text,
+    thinking: turn.thinking,
+    toolCalls: turn.toolCalls.map(toExportedToolCall),
+    closed: true
+  };
+}
+function aggregateUsage(turns) {
+  let acc;
+  for (const turn of turns) {
+    const d = turn.usageDelta;
+    if (!d) continue;
+    if (!acc) acc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, total: 0 };
+    acc.input += d.input;
+    acc.output += d.output;
+    acc.cacheRead += d.cacheRead;
+    acc.cacheWrite += d.cacheWrite;
+    acc.cost += d.cost ?? 0;
+  }
+  if (acc) acc.total = acc.input + acc.output + acc.cacheRead + acc.cacheWrite;
+  return acc;
+}
+function eventsToSessionView(events, engineId, sessionId) {
+  const record = createReplayRecord();
+  for (const ev of events) updateFromEvent(record, ev);
+  return {
+    engineId,
+    ...sessionId !== void 0 ? { sessionId } : {},
+    turns: record.turns.map(toReplayedTurn),
+    usage: aggregateUsage(record.turns),
+    source: "journal"
+  };
+}
+function sessionIdFromHandle(handle) {
+  const v = handle.sessionRef["sessionId"];
+  return typeof v === "string" ? v : void 0;
+}
+
+export {
+  createReplayRecord,
+  updateFromEvent,
+  toReplayedTurn,
+  aggregateUsage,
+  eventsToSessionView,
+  sessionIdFromHandle
+};