@osolmaz/pi-workflows 0.5.2 → 0.6.0

package/src/workflows/progress.ts

@@ -0,0 +1,326 @@
+import { sanitizeText } from "./text.js";
+import type { WorkflowProgressData, WorkflowTraceEvent, WorkflowUpdateRecord } from "./types.js";
+import { validateProgressData } from "./updates.js";
+
+export type ProgressConfidence = "low" | "medium" | "high";
+
+export type ProgressEstimate = {
+  key: string;
+  data: WorkflowProgressData;
+  sampleCount: number;
+  delta?: number;
+  rateLow?: number;
+  rateMedian?: number;
+  rateHigh?: number;
+  remainingLowMs?: number;
+  remainingMedianMs?: number;
+  remainingHighMs?: number;
+  confidence?: ProgressConfidence;
+  sourceEstimatedFinishAt?: string;
+  unavailableReason?: string;
+};
+
+export type ProgressSample = {
+  at: string;
+  data: WorkflowProgressData;
+};
+
+export type ProgressTrackState = {
+  key: string;
+  samples: ProgressSample[];
+  estimate: ProgressEstimate;
+};
+
+const TERMINAL = new Set(["completed", "failed", "cancelled"]);
+
+export function estimateProgress(
+  key: string,
+  samples: ProgressSample[],
+  now = new Date(),
+): ProgressEstimate {
+  if (samples.length === 0) throw new Error("progress estimation requires at least one sample");
+  for (const sample of samples) validateProgressData(sample.data as Record<string, unknown>);
+  const latest = samples.at(-1) as ProgressSample;
+  const data = latest.data;
+  const base: ProgressEstimate = { key, data, sampleCount: 1 };
+  if (TERMINAL.has(data.status)) return base;
+  const sourceFinish = validSourceFinish(latest, now);
+  if (sourceFinish !== undefined) base.sourceEstimatedFinishAt = sourceFinish;
+  if (data.status === "waiting" || data.status === "blocked") {
+    return sourceFinish === undefined
+      ? { ...base, unavailableReason: `progress is ${data.status}` }
+      : base;
+  }
+  if (data.completed === undefined || data.total === undefined) {
+    return sourceFinish === undefined ? { ...base, unavailableReason: "total is unknown" } : base;
+  }
+
+  const epoch = currentEpoch(samples);
+  const intervals: Array<{ rate: number; delta: number }> = [];
+  for (let index = Math.max(1, epoch.length - 8); index < epoch.length; index += 1) {
+    const previous = epoch[index - 1] as ProgressSample;
+    const current = epoch[index] as ProgressSample;
+    const elapsedMs = Date.parse(current.at) - Date.parse(previous.at);
+    const previousCompleted = previous.data.completed;
+    const currentCompleted = current.data.completed;
+    if (elapsedMs <= 0 || previousCompleted === undefined || currentCompleted === undefined)
+      continue;
+    intervals.push({
+      rate: (currentCompleted - previousCompleted) / elapsedMs,
+      delta: currentCompleted - previousCompleted,
+    });
+  }
+  base.sampleCount = intervals.length + 1;
+  const latestDelta = intervals.at(-1)?.delta;
+  if (latestDelta !== undefined) base.delta = latestDelta;
+  if (intervals.length === 0) {
+    return sourceFinish === undefined
+      ? { ...base, unavailableReason: "needs another progress sample" }
+      : base;
+  }
+  const rates = intervals.map((item) => item.rate).sort((a, b) => a - b);
+  const median = quantile(rates, 0.5);
+  const p25 = quantile(rates, 0.25);
+  const p75 = quantile(rates, 0.75);
+  const remaining = Math.max(0, data.total - data.completed);
+  const positive = rates.filter((rate) => rate > 0);
+  if (median <= 0 || positive.length === 0) {
+    return sourceFinish === undefined
+      ? { ...base, unavailableReason: "no positive progress rate" }
+      : base;
+  }
+  const spread = (p75 - p25) / median;
+  const confidence: ProgressConfidence =
+    intervals.length >= 5
+      ? spread <= 0.25
+        ? "high"
+        : spread <= 0.5
+          ? "medium"
+          : "low"
+      : intervals.length >= 2 && spread <= 0.5
+        ? "medium"
+        : "low";
+  const slow = p25 > 0 ? p25 : undefined;
+  const fast = p75 > 0 ? p75 : median;
+  return {
+    ...base,
+    ...(slow !== undefined ? { rateLow: slow } : {}),
+    rateMedian: median,
+    rateHigh: fast,
+    remainingLowMs: remaining / fast,
+    remainingMedianMs: remaining / median,
+    ...(slow !== undefined ? { remainingHighMs: remaining / slow } : {}),
+    confidence,
+  };
+}
+
+export function progressRecordsFromTrace(events: WorkflowTraceEvent[]): WorkflowUpdateRecord[] {
+  const records: WorkflowUpdateRecord[] = [];
+  for (const event of events) {
+    if (
+      event.type !== "update_published" ||
+      event.nodeId === undefined ||
+      event.attemptId === undefined
+    )
+      continue;
+    const payload = event.payload;
+    if (
+      typeof payload.updateId !== "string" ||
+      typeof payload.type !== "string" ||
+      typeof payload.key !== "string" ||
+      payload.data === null ||
+      typeof payload.data !== "object" ||
+      Array.isArray(payload.data)
+    )
+      continue;
+    records.push({
+      updateId: payload.updateId,
+      seq: event.seq,
+      at: event.at,
+      runId: event.runId,
+      nodeId: event.nodeId,
+      attemptId: event.attemptId,
+      type: payload.type,
+      key: payload.key,
+      data: payload.data as Record<string, unknown>,
+    });
+  }
+  return records;
+}
+
+export function appendProgressHistory(
+  history: WorkflowUpdateRecord[],
+  additions: WorkflowUpdateRecord[],
+  maxPerTrack = 9,
+  maxRecords = 576,
+): WorkflowUpdateRecord[] {
+  const retained: WorkflowUpdateRecord[] = [];
+  const counts = new Map<string, number>();
+  const combined = [...history, ...additions];
+  for (let index = combined.length - 1; index >= 0 && retained.length < maxRecords; index -= 1) {
+    const record = combined[index] as WorkflowUpdateRecord;
+    if (record.type !== "progress") continue;
+    const count = counts.get(record.key) ?? 0;
+    if (count >= maxPerTrack) continue;
+    counts.set(record.key, count + 1);
+    retained.push(record);
+  }
+  return retained.reverse();
+}
+
+export function progressTracksFromRecords(
+  records: WorkflowUpdateRecord[],
+  now = new Date(),
+): ProgressTrackState[] {
+  const grouped = new Map<string, ProgressSample[]>();
+  for (const record of records) {
+    if (record.type !== "progress") continue;
+    try {
+      const data = validateProgressData(record.data);
+      const samples = grouped.get(record.key) ?? [];
+      samples.push({ at: record.at, data });
+      grouped.set(record.key, samples);
+    } catch {
+      // Readers skip malformed historical update data instead of failing.
+    }
+  }
+  return [...grouped.entries()].map(([key, samples]) => ({
+    key,
+    samples,
+    estimate: estimateProgress(key, samples, now),
+  }));
+}
+
+export function formatProgressLine(estimate: ProgressEstimate, now = new Date()): string {
+  const { data } = estimate;
+  const label = sanitizeText(data.label ?? estimate.key);
+  const unit = data.unit === undefined ? "" : sanitizeText(data.unit);
+  const count =
+    data.completed === undefined
+      ? data.status
+      : data.total === undefined
+        ? `${formatNumber(data.completed)} ${unit}`.trim()
+        : `${formatNumber(data.completed)}/${formatNumber(data.total)} ${unit}`.trim();
+  let eta = "";
+  if (estimate.sourceEstimatedFinishAt !== undefined) {
+    eta = `source ETA ${formatRemaining(Date.parse(estimate.sourceEstimatedFinishAt) - now.getTime())}`;
+  } else if (estimate.remainingMedianMs !== undefined) {
+    const range =
+      estimate.remainingLowMs !== undefined &&
+      estimate.remainingHighMs !== undefined &&
+      Math.abs(estimate.remainingHighMs - estimate.remainingLowMs) >= 1_000
+        ? `${formatRemaining(estimate.remainingLowMs)}–${formatRemaining(estimate.remainingHighMs)}`
+        : formatRemaining(estimate.remainingMedianMs);
+    eta = `ETA ${range}`;
+  } else if (!TERMINAL.has(data.status)) {
+    eta = `ETA unavailable${estimate.unavailableReason ? ` (${estimate.unavailableReason})` : ""}`;
+  }
+  return [label, count, eta].filter(Boolean).join("  ");
+}
+
+export function formatProgressReport(
+  estimates: ProgressEstimate[],
+  nextCheckMinutes?: number,
+  now = new Date(),
+  maxChars = 4_000,
+): string {
+  const footer = nextCheckMinutes === undefined ? undefined : `Next check: ${nextCheckMinutes} min`;
+  const lines: string[] = [];
+  let omitted = 0;
+  for (const estimate of prioritizeProgressEstimates(estimates)) {
+    const block = [`Progress: ${formatProgressLine(estimate, now)}`];
+    if (estimate.rateMedian !== undefined && estimate.data.unit !== undefined) {
+      const median = estimate.rateMedian * 60_000;
+      const low = estimate.rateLow === undefined ? undefined : estimate.rateLow * 60_000;
+      const high = estimate.rateHigh === undefined ? undefined : estimate.rateHigh * 60_000;
+      const rate =
+        low !== undefined && high !== undefined && Math.abs(high - low) >= 0.01
+          ? `${formatNumber(low)}–${formatNumber(high)}`
+          : formatNumber(median);
+      block.push(`Rate: ${rate} ${estimate.data.unit}/min`);
+      block.push(
+        `Estimate: ${estimate.confidence ?? "low"} confidence, ${estimate.sampleCount} samples`,
+      );
+    }
+    const candidate = [...lines, ...block, ...(footer === undefined ? [] : [footer])].join("\n");
+    if (candidate.length > maxChars) {
+      omitted += 1;
+      continue;
+    }
+    lines.push(...block);
+  }
+  if (omitted > 0) {
+    const marker = `${omitted} progress track${omitted === 1 ? "" : "s"} omitted.`;
+    if (
+      [...lines, marker, ...(footer === undefined ? [] : [footer])].join("\n").length <= maxChars
+    ) {
+      lines.push(marker);
+    }
+  }
+  if (footer !== undefined && [...lines, footer].join("\n").length <= maxChars) lines.push(footer);
+  return lines.join("\n").slice(0, maxChars);
+}
+
+export function formatRemaining(ms: number): string {
+  const value = Math.ceil(Math.max(0, ms) / 1_000) * 1_000;
+  if (value < 60_000) return `${Math.ceil(value / 1_000)}s`;
+  if (value < 3_600_000) return `${Math.ceil(value / 60_000)}m`;
+  if (value < 86_400_000) return `${(value / 3_600_000).toFixed(value < 36_000_000 ? 1 : 0)}h`;
+  return `${(value / 86_400_000).toFixed(1)}d`;
+}
+
+function currentEpoch(samples: ProgressSample[]): ProgressSample[] {
+  const epoch: ProgressSample[] = [];
+  for (const sample of samples) {
+    const prior = epoch.at(-1);
+    if (prior !== undefined && resetsEpoch(prior.data, sample.data)) epoch.length = 0;
+    epoch.push(sample);
+  }
+  return epoch;
+}
+
+function resetsEpoch(previous: WorkflowProgressData, next: WorkflowProgressData): boolean {
+  return (
+    previous.phase !== next.phase ||
+    previous.unit !== next.unit ||
+    previous.total !== next.total ||
+    (previous.completed !== undefined &&
+      next.completed !== undefined &&
+      next.completed < previous.completed) ||
+    (TERMINAL.has(previous.status) && !TERMINAL.has(next.status))
+  );
+}
+
+function validSourceFinish(sample: ProgressSample, now: Date): string | undefined {
+  const finish = sample.data.sourceEstimatedFinishAt;
+  if (finish === undefined) return undefined;
+  const finishMs = Date.parse(finish);
+  const sourceMs = Date.parse(sample.data.sourceUpdatedAt ?? sample.at);
+  return finishMs > sourceMs && finishMs > now.getTime() ? finish : undefined;
+}
+
+function quantile(sorted: number[], p: number): number {
+  if (sorted.length === 1) return sorted[0] as number;
+  const position = (sorted.length - 1) * p;
+  const lower = Math.floor(position);
+  const fraction = position - lower;
+  const a = sorted[lower] as number;
+  const b = sorted[Math.min(lower + 1, sorted.length - 1)] as number;
+  return a + (b - a) * fraction;
+}
+
+export function prioritizeProgressEstimates(estimates: ProgressEstimate[]): ProgressEstimate[] {
+  const weight = (item: ProgressEstimate) =>
+    item.key === "overall"
+      ? -3
+      : item.data.status === "failed" || item.data.status === "blocked"
+        ? -2
+        : item.data.status === "waiting"
+          ? -1
+          : 0;
+  return [...estimates].sort((a, b) => weight(a) - weight(b));
+}
+
+function formatNumber(value: number): string {
+  return new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(value);
+}

package/src/workflows/schema.ts

@@ -86,7 +86,9 @@ export function assertValidActionNode(node: ActionNodeDefinition, nodeId = "acti
     if (typeof node.exec !== "function") {
       fail(`node ${nodeId} exec must be a function`);
     }
-    assertOptionalFunction((node as ShellActionNodeDefinition).parse, `node ${nodeId} parse`);
+    const shell = node as ShellActionNodeDefinition;
+    assertOptionalFunction(shell.parse, `node ${nodeId} parse`);
+    assertShellUpdates(shell, nodeId);
   } else if (typeof (node as FunctionActionNodeDefinition).run !== "function") {
     fail(`node ${nodeId} run must be a function`);
   }
@@ -101,9 +103,29 @@ export function assertValidShellActionNode(
     fail(`node ${nodeId} requires an exec function`);
   }
   assertOptionalFunction(node.parse, `node ${nodeId} parse`);
+  assertShellUpdates(node, nodeId);
   assertCommonNodeFields(node, nodeId);
 }
 
+function assertShellUpdates(node: ShellActionNodeDefinition, nodeId: string): void {
+  if (node.updates === undefined) return;
+  if (node.updates === null || typeof node.updates !== "object") {
+    fail(`node ${nodeId} updates must be an object`);
+  }
+  if (typeof node.updates.parseLine !== "function") {
+    fail(`node ${nodeId} updates.parseLine must be a function`);
+  }
+  if (node.updates.streams !== undefined) {
+    if (
+      !Array.isArray(node.updates.streams) ||
+      node.updates.streams.length === 0 ||
+      node.updates.streams.some((stream) => stream !== "stdout" && stream !== "stderr")
+    ) {
+      fail(`node ${nodeId} updates.streams must contain stdout or stderr`);
+    }
+  }
+}
+
 export function assertValidCheckpointNode(
   node: CheckpointNodeDefinition,
   nodeId = "checkpoint",

package/src/workflows/shell.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { CancelledError, TimeoutError } from "./errors.js";
-import type { ShellActionExecution, ShellActionResult } from "./types.js";
+import type { ShellActionExecution, ShellActionResult, ShellUpdateLine } from "./types.js";
 
 /** Default cap on captured stdout/stderr, each. */
 const DEFAULT_MAX_OUTPUT_CHARS = 1_000_000;
@@ -51,6 +51,7 @@ function shellFailure(
 export async function runShellAction(
   spec: ShellActionExecution,
   signal?: AbortSignal,
+  onLine?: (line: ShellUpdateLine) => Promise<void>,
 ): Promise<ShellActionResult> {
   // The node may have been cancelled while an async `exec` callback resolved;
   // never start side effects for an already-abandoned attempt.
@@ -75,6 +76,7 @@ export async function runShellAction(
   let stdout = "";
   let stderr = "";
   let killedBy: "timeout" | "abort" | null = null;
+  let lineError: Error | undefined;
   let timeout: NodeJS.Timeout | undefined;
 
   // Cap retained output so a verbose or unending command cannot exhaust
@@ -114,15 +116,71 @@ export async function runShellAction(
   };
   const onAbort = () => kill("abort");
 
+  const lineBuffers: Record<"stdout" | "stderr", string> = { stdout: "", stderr: "" };
+  const decoders = {
+    stdout: new TextDecoder("utf-8", { fatal: onLine !== undefined }),
+    stderr: new TextDecoder("utf-8", { fatal: onLine !== undefined }),
+  };
+  let lineWork = Promise.resolve();
+  const processChunk = (
+    stream: "stdout" | "stderr",
+    chunk: string,
+    source: NodeJS.ReadableStream & { pause(): unknown; resume(): unknown },
+  ) => {
+    if (stream === "stdout") stdout = appendCapped(stdout, chunk);
+    else stderr = appendCapped(stderr, chunk);
+    if (onLine === undefined || lineError !== undefined) return;
+    source.pause();
+    lineWork = lineWork
+      .then(async () => {
+        const parts = `${lineBuffers[stream]}${chunk}`.split("\n");
+        lineBuffers[stream] = parts.pop() ?? "";
+        if (Buffer.byteLength(lineBuffers[stream], "utf8") > 64 * 1024) {
+          throw new Error(`shell ${stream} update line exceeded 65536 bytes`);
+        }
+        for (const raw of parts) {
+          const text = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+          if (Buffer.byteLength(text, "utf8") > 64 * 1024) {
+            throw new Error(`shell ${stream} update line exceeded 65536 bytes`);
+          }
+          await onLine({ stream, text });
+        }
+      })
+      .catch((error: unknown) => {
+        lineError = error instanceof Error ? error : new Error(String(error));
+        kill("abort");
+      })
+      .finally(() => source.resume());
+  };
+  const flushLines = async () => {
+    await lineWork;
+    if (onLine === undefined || lineError !== undefined) return;
+    for (const stream of ["stdout", "stderr"] as const) {
+      const text = lineBuffers[stream];
+      if (Buffer.byteLength(text, "utf8") > 64 * 1024) {
+        throw new Error(`shell ${stream} update line exceeded 65536 bytes`);
+      }
+      if (text.length > 0)
+        await onLine({ stream, text: text.endsWith("\r") ? text.slice(0, -1) : text });
+    }
+  };
+
+  const decodeChunk = (
+    stream: "stdout" | "stderr",
+    chunk: Buffer,
+    source: NodeJS.ReadableStream & { pause(): unknown; resume(): unknown },
+  ) => {
+    try {
+      processChunk(stream, decoders[stream].decode(chunk, { stream: true }), source);
+    } catch (error) {
+      lineError = error instanceof Error ? error : new Error(String(error));
+      kill("abort");
+    }
+  };
+
   const finish = new Promise<ShellActionResult>((resolve, reject) => {
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk: string) => {
-      stdout = appendCapped(stdout, chunk);
-    });
-    child.stderr.on("data", (chunk: string) => {
-      stderr = appendCapped(stderr, chunk);
-    });
+    child.stdout.on("data", (chunk: Buffer) => decodeChunk("stdout", chunk, child.stdout));
+    child.stderr.on("data", (chunk: Buffer) => decodeChunk("stderr", chunk, child.stderr));
 
     child.once("error", (error) => {
       // Spawn failures (missing executable, EACCES) still get a receipt so
@@ -143,24 +201,49 @@ export async function runShellAction(
     // `close` (unlike `exit`) fires only after stdio has fully closed, so
     // captured output is never truncated.
     child.once("close", (exitCode, signalName) => {
-      const result: ShellActionResult = {
-        command: spec.command,
-        args,
-        cwd,
-        stdout,
-        stderr,
-        exitCode,
-        signal: signalName,
-        durationMs: Date.now() - startMs,
-      };
-      const error = shellFailure(spec, args, result, killedBy);
-      if (error) {
-        // Attach the result so callers can persist the action receipt.
-        (error as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT] = result;
-        reject(error);
-        return;
+      try {
+        processChunk("stdout", decoders.stdout.decode(), child.stdout);
+        processChunk("stderr", decoders.stderr.decode(), child.stderr);
+      } catch (error) {
+        lineError = error instanceof Error ? error : new Error(String(error));
       }
-      resolve(result);
+      void flushLines()
+        .then(() => {
+          const result: ShellActionResult = {
+            command: spec.command,
+            args,
+            cwd,
+            stdout,
+            stderr,
+            exitCode,
+            signal: signalName,
+            durationMs: Date.now() - startMs,
+          };
+          const error = lineError ?? shellFailure(spec, args, result, killedBy);
+          if (error) {
+            // Attach the result so callers can persist the action receipt.
+            (error as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT] = result;
+            reject(error);
+            return;
+          }
+          resolve(result);
+        })
+        .catch((error: unknown) => {
+          const failure = error instanceof Error ? error : new Error(String(error));
+          lineError = failure;
+          const result: ShellActionResult = {
+            command: spec.command,
+            args,
+            cwd,
+            stdout,
+            stderr,
+            exitCode,
+            signal: signalName,
+            durationMs: Date.now() - startMs,
+          };
+          (failure as Error & { [SHELL_RESULT]?: ShellActionResult })[SHELL_RESULT] = result;
+          reject(failure);
+        });
     });
   });
 

package/src/workflows/store.ts

@@ -16,7 +16,10 @@ import type {
   WorkflowSessionEventRecord,
   WorkflowTraceEvent,
   WorkflowTraceEventDraft,
+  WorkflowUpdateInput,
+  WorkflowUpdateRecord,
 } from "./types.js";
+import { MAX_CURRENT_UPDATES, createUpdateId, updateProjection } from "./updates.js";
 
 export const RUN_BUNDLE_SCHEMA = "pi-workflows.run-bundle.v1" as const;
 export const RUN_STATE_SCHEMA = "pi-workflows.run-state.v1" as const;
@@ -429,6 +432,53 @@ export class WorkflowRunStore {
     return await readRunBundle(runDir);
   }
 
+  /** Publish one durable update under the run's serialized claim-fenced writer. */
+  async publishUpdate(
+    runDir: string,
+    state: WorkflowRunState,
+    nodeId: string,
+    attemptId: string,
+    update: WorkflowUpdateInput,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<{ event: WorkflowTraceEvent; record: WorkflowUpdateRecord }> {
+    return await this.withRunLock(runDir, async () => {
+      if (options.signal?.aborted === true) {
+        throw options.signal.reason ?? new Error("workflow update attempt is no longer active");
+      }
+      const exists = (state.updates ?? []).some(
+        (record) => record.type === update.type && record.key === update.key,
+      );
+      if (!exists && (state.updates?.length ?? 0) >= MAX_CURRENT_UPDATES) {
+        throw new Error(`workflow run supports at most ${MAX_CURRENT_UPDATES} current updates`);
+      }
+      const updateId = createUpdateId();
+      const data = JSON.parse(JSON.stringify(update.data)) as Record<string, unknown>;
+      const event = await this.appendTraceEvent(runDir, state.runId, {
+        scope: "node",
+        type: "update_published",
+        nodeId,
+        attemptId,
+        payload: { updateId, type: update.type, key: update.key, data },
+      });
+      const record: WorkflowUpdateRecord = {
+        updateId,
+        seq: event.seq,
+        at: event.at,
+        runId: state.runId,
+        nodeId,
+        attemptId,
+        type: update.type,
+        key: update.key,
+        data,
+      };
+      state.updates = updateProjection(state.updates, record);
+      state.traceSeq = event.seq;
+      state.updatedAt = event.at;
+      await this.writeProjections(runDir, state);
+      return { event, record };
+    });
+  }
+
   /**
    * Persist one transition: append the trace event, then rewrite the
    * projections reflecting it.
@@ -996,6 +1046,8 @@ export type LoadedRunBundle = {
   manifest: WorkflowRunManifest;
   state: WorkflowRunState;
   snapshot: WorkflowDefinitionSnapshot | null;
+  /** Full durable trace when loaded by the current reader. */
+  traceEvents?: WorkflowTraceEvent[];
   sessionBinding: WorkflowSessionBinding | null;
   sessionEntries: WorkflowSessionEntryRecord[];
   sessionEvents: WorkflowSessionEventRecord[];
@@ -1016,8 +1068,16 @@ export async function readLastTraceEvent(
   return events.records.at(-1) ?? null;
 }
 
+export type ReadRunBundleOptions = {
+  /** Load the full append-only trace. Detail views need it; run lists do not. */
+  includeTrace?: boolean;
+};
+
 /** Read a run bundle from disk. Returns null when the bundle is unreadable. */
-export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | null> {
+export async function readRunBundle(
+  runDir: string,
+  options: ReadRunBundleOptions = {},
+): Promise<LoadedRunBundle | null> {
   const manifest = await readJsonFile<WorkflowRunManifest>(path.join(runDir, MANIFEST_PATH));
   if (!manifest || manifest.schema !== RUN_BUNDLE_SCHEMA) {
     return null;
@@ -1035,6 +1095,10 @@ export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | n
   const snapshot = await readJsonFile<WorkflowDefinitionSnapshot>(
     resolveBundlePath(runDir, paths.workflow, WORKFLOW_SNAPSHOT_PATH),
   );
+  const trace =
+    options.includeTrace === true
+      ? await readNdjsonFile<WorkflowTraceEvent>(resolveBundlePath(runDir, paths.trace, TRACE_PATH))
+      : undefined;
   const sessionDir = resolveBundlePath(runDir, paths.session, SESSION_DIR);
   const sessionBinding = await readJsonFile<WorkflowSessionBinding>(
     path.join(sessionDir, "binding.json"),
@@ -1109,6 +1173,7 @@ export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | n
     manifest,
     state,
     snapshot,
+    ...(trace !== undefined ? { traceEvents: trace.records } : {}),
     sessionBinding,
     sessionEntries: entries.records,
     sessionEvents: events.records,
@@ -1147,7 +1212,7 @@ export async function listRunBundles(outputRoot: string): Promise<LoadedRunBundl
   }
   const bundles: LoadedRunBundle[] = [];
   for (const entry of entries) {
-    const bundle = await readRunBundle(path.join(outputRoot, entry));
+    const bundle = await readRunBundle(path.join(outputRoot, entry), { includeTrace: false });
     if (bundle) {
       bundles.push(bundle);
     }