@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/dist/builtin/workflows/src/extension/workflow-run-control-command.ts

@@ -0,0 +1,286 @@
+import { cancellationRegistry } from "../runs/background/cancellation-registry.js";
+import { interruptAllRuns, interruptRun, killAllRuns, killRun, pauseRun, resumeRun } from "../runs/background/status.js";
+import type { WorkflowPersistencePort } from "../shared/types.js";
+import { store } from "../shared/store.js";
+import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
+import { renderSessionList } from "../tui/session-list.js";
+import { openKillConfirm, openSessionPicker } from "../tui/session-overlays.js";
+import { deriveGraphTheme } from "../tui/graph-theme.js";
+import { emitChatSurface } from "../tui/chat-surface-message.js";
+import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { ExtensionAPI, PiCommandContext } from "./public-types.js";
+import type { WorkflowCommandReporter } from "./workflow-command-utils.js";
+import { stripYesFlag } from "./workflow-command-utils.js";
+import { workflowPolicyFromContext } from "./workflow-policy.js";
+import {
+  formatAlreadyEndedRetainedMessage,
+  overlaySurfaceFromContext,
+  resolveRunIdPrefix,
+  resolveStageTarget,
+} from "./workflow-targets.js";
+
+export interface WorkflowRunControlDeps {
+  pi: ExtensionAPI;
+  overlay: GraphOverlayPort;
+  getPersistence: () => WorkflowPersistencePort | undefined;
+  runtimeForContext: (ctx?: PiCommandContext) => ExtensionRuntime;
+}
+
+function resolveAttachStageId(runId: string, stageTarget: string | undefined): string | undefined | false {
+  if (!stageTarget) return undefined;
+  const run = store.runs().find((r) => r.id === runId);
+  if (!run) return undefined;
+  const exact = run.stages.find((s) => s.id === stageTarget);
+  const prefix = exact ?? run.stages.find((s) => s.id.startsWith(stageTarget));
+  const byName = prefix ?? run.stages.find((s) => s.name === stageTarget);
+  return byName?.id ?? false;
+}
+
+export async function handleRunControlCommand(
+  action: "connect" | "interrupt" | "kill" | "attach" | "pause" | "resume",
+  rest: string[],
+  ctx: PiCommandContext,
+  reporter: WorkflowCommandReporter,
+  deps: WorkflowRunControlDeps,
+): Promise<boolean> {
+  const policy = workflowPolicyFromContext(ctx);
+  const print = (msg: string): void => reporter.info(msg);
+  const fail = (msg: string): void => reporter.error(msg);
+  const canOpenPicker = (ui: PiCommandContext["ui"] | undefined): boolean =>
+    policy.allowInputPicker && typeof ui?.custom === "function";
+  const confirmationPrompt = policy.allowHumanInput && typeof ctx.ui?.confirm === "function"
+    ? ctx.ui.confirm.bind(ctx.ui)
+    : undefined;
+  const theme = deriveGraphTheme({});
+  const failHeadlessAttachCommand = (targetAction: "connect" | "attach", runId: string, stageId?: string): boolean => {
+    if (policy.allowInputPicker) return false;
+    const displayTarget = stageId ? `${runId.slice(0, 8)} stage ${stageId.slice(0, 8)}` : runId.slice(0, 8);
+    fail(
+      `/workflow ${targetAction} requires an interactive UI surface and cannot attach in non-interactive mode. ` +
+        `Target: ${displayTarget}. Use /workflow status ${runId.slice(0, 8)} or the workflow tool's status/stages/transcript actions for non-interactive inspection.`,
+    );
+    return true;
+  };
+
+  if (action === "connect") {
+    const target = rest.find((t) => !t.startsWith("--"));
+    if (!target) {
+      const ui = ctx.ui;
+      if (!canOpenPicker(ui)) {
+        fail(`${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires an interactive UI surface. Pass a runId: /workflow connect <id>`);
+        return true;
+      }
+      const result = await openSessionPicker(ui, store, theme, "connect");
+      if (result.kind === "close") return true;
+      if (result.kind === "connect") {
+        deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
+        return true;
+      }
+      if (result.kind === "kill") {
+        const run = store.runs().find((r) => r.id === result.runId);
+        if (!run) {
+          fail(`Run not found: ${result.runId}`);
+          return true;
+        }
+        if (run.endedAt !== undefined) {
+          print(formatAlreadyEndedRetainedMessage(result.runId));
+          return true;
+        }
+        const confirmed = await openKillConfirm(ui, run, theme);
+        if (!confirmed) {
+          print(`Cancelled. Run ${result.runId.slice(0, 8)} is still active.`);
+          return true;
+        }
+        const killed = killRun(result.runId, { cancellation: cancellationRegistry, persistence: deps.getPersistence() });
+        if (killed.ok) {
+          emitChatSurface(deps.pi, { kind: "killed", run, previousStatus: killed.previousStatus });
+          print(`Run ${killed.runId.slice(0, 8)} killed and retained for inspection.`);
+        } else if (killed.reason === "already_ended") {
+          print(formatAlreadyEndedRetainedMessage(killed.runId));
+        } else {
+          fail(`Run not found: ${result.runId.slice(0, 8)}.`);
+        }
+      }
+      return true;
+    }
+    const resolved = resolveRunIdPrefix(target);
+    if (resolved.kind === "not_found") {
+      fail(`Run not found: ${target}\n\n${renderSessionList(store.runs(), { theme, includeAll: true })}`);
+      return true;
+    }
+    if (resolved.kind === "ambiguous") {
+      fail(`Ambiguous run prefix "${target}" matches: ${resolved.matches.map((id) => id.slice(0, 12)).join(", ")}`);
+      return true;
+    }
+    if (failHeadlessAttachCommand("connect", resolved.runId)) return true;
+    if (policy.allowInputPicker) deps.overlay.open(resolved.runId, overlaySurfaceFromContext(ctx));
+    print(`Attached to ${resolved.runId.slice(0, 8)}. h/ctrl+d hide · q kill · esc close.`);
+    return true;
+  }
+
+  if (action === "interrupt" || action === "kill") {
+    const { tokens, yes } = stripYesFlag(rest);
+    let target = tokens.find((t) => !t.startsWith("--"));
+    const wantsAll = tokens.includes("--all");
+    const noun = action === "kill" ? "kill" : "interrupt";
+    if (!target && !wantsAll) {
+      target = store.activeRunId() ?? undefined;
+      if (!target) {
+        fail(`No in-flight runs to ${noun}.`);
+        return true;
+      }
+    }
+    if (wantsAll) {
+      const inFlight = topLevelWorkflowRuns(store.runs()).filter((r) => r.endedAt === undefined);
+      if (inFlight.length === 0) {
+        fail(`No in-flight runs to ${noun}.`);
+        return true;
+      }
+      if (!yes && confirmationPrompt) {
+        const title = action === "kill"
+          ? `Kill ${inFlight.length} in-flight workflow runs? Killed runs are retained for inspection.`
+          : `Interrupt all ${inFlight.length} in-flight workflow runs?`;
+        const body = `${action === "kill" ? "Aborts" : "Pauses"}: ${inFlight.map((r) => `${r.name} (${r.id.slice(0, 8)})`).join(", ")}`;
+        if (!(await confirmationPrompt(title, body))) {
+          print("Cancelled.");
+          return true;
+        }
+      }
+      const results = action === "kill"
+        ? killAllRuns({ cancellation: cancellationRegistry, persistence: deps.getPersistence() })
+        : interruptAllRuns();
+      const changed = results.filter((r) => r.ok).length;
+      if (changed > 0) print(action === "kill" ? `Killed and retained ${changed} run(s) for inspection.` : `Interrupted ${changed} run(s).`);
+      else fail(`No in-flight runs to ${noun}.`);
+      return true;
+    }
+    const resolved = resolveRunIdPrefix(target!);
+    if (resolved.kind === "not_found") {
+      fail(`Run not found: ${target}`);
+      return true;
+    }
+    if (resolved.kind === "ambiguous") {
+      fail(`Ambiguous run prefix "${target}" matches multiple runs: ${resolved.matches.map((id) => id.slice(0, 12)).join(", ")}`);
+      return true;
+    }
+    const run = store.runs().find((r) => r.id === resolved.runId);
+    if (action === "kill" && run?.endedAt !== undefined) {
+      print(formatAlreadyEndedRetainedMessage(resolved.runId));
+      return true;
+    }
+    if (!yes && run && (action === "kill" || run.endedAt === undefined) && confirmationPrompt) {
+      const confirmed = action === "kill"
+        ? await openKillConfirm(ctx.ui, run, theme)
+        : await confirmationPrompt(`Interrupt workflow run ${run.name} (${run.id.slice(0, 8)})?`, "Pauses live work so it can be resumed later.");
+      if (!confirmed) {
+        print(action === "kill"
+          ? `Cancelled. Run ${resolved.runId.slice(0, 8)} is still in history/status.`
+          : `Cancelled. Run ${resolved.runId.slice(0, 8)} is still active.`);
+        return true;
+      }
+    }
+    if (action === "kill") {
+      const result = killRun(resolved.runId, { cancellation: cancellationRegistry, persistence: deps.getPersistence() });
+      if (result.ok) {
+        if (run) emitChatSurface(deps.pi, { kind: "killed", run, previousStatus: result.previousStatus });
+        print(`Run ${result.runId.slice(0, 8)} killed and retained for inspection (was ${result.previousStatus}).`);
+      } else if (result.reason === "already_ended") print(formatAlreadyEndedRetainedMessage(result.runId));
+      else fail(`Run not found: ${target}`);
+      return true;
+    }
+    const result = interruptRun(resolved.runId);
+    if (result.ok) print(`Run ${result.runId.slice(0, 8)} interrupted and can be resumed.`);
+    else fail(result.reason === "not_found" ? `Run not found: ${target}` : result.reason === "already_ended" ? `Run already ended: ${target}` : result.reason === "stage_not_found" ? `Stage not found for run ${resolved.runId.slice(0, 8)}.` : `No active stages to interrupt on run ${resolved.runId.slice(0, 8)}.`);
+    return true;
+  }
+
+  if (action === "attach" || action === "pause" || action === "resume") {
+    const target = rest[0];
+    const stageTarget = rest[1];
+    const message = action === "resume" ? rest.slice(2).join(" ").trim() || undefined : undefined;
+    let runId: string;
+    if (!target) {
+      const ui = ctx.ui;
+      if (!canOpenPicker(ui)) {
+        if (action === "pause") {
+          const active = topLevelWorkflowRuns(store.runs()).filter((r) => r.endedAt === undefined);
+          fail(active.length === 0 ? "No active runs to pause." : `Picker requires an interactive UI surface. Active runs:\n${active.map((r) => `  ${r.id.slice(0, 8)}  ${r.name}`).join("\n")}\n\nUsage: /workflow pause <runId> [stageId]`);
+        } else {
+          fail(action === "attach"
+            ? `${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires an interactive UI surface. Pass a runId: /workflow attach <id> [stageId]`
+            : "Usage: /workflow resume <runId> [stageId] [message…]");
+        }
+        return true;
+      }
+      const picked = await openSessionPicker(ui, store, theme, action === "attach" ? "connect" : action);
+      if (action === "attach" && picked.kind === "kill") return handleRunControlCommand("kill", [picked.runId, "-y"], ctx, reporter, deps);
+      if (picked.kind !== (action === "attach" ? "connect" : action)) return true;
+      runId = picked.runId;
+    } else {
+      const resolved = resolveRunIdPrefix(target);
+      if (resolved.kind === "not_found") {
+        fail(`Run not found: ${target}`);
+        return true;
+      }
+      if (resolved.kind === "ambiguous") {
+        fail(`Ambiguous run prefix "${target}" matches: ${resolved.matches.map((id) => id.slice(0, 12)).join(", ")}`);
+        return true;
+      }
+      runId = resolved.runId;
+    }
+    if (action === "attach") {
+      const stageId = resolveAttachStageId(runId, stageTarget);
+      if (stageId === false) {
+        fail(`Stage not found in run ${runId.slice(0, 8)}: ${stageTarget}`);
+        return true;
+      }
+      if (failHeadlessAttachCommand("attach", runId, stageId)) return true;
+      if (policy.allowInputPicker) deps.overlay.open(runId, overlaySurfaceFromContext(ctx), stageId);
+      print(stageId ? `Attached to ${runId.slice(0, 8)} stage ${stageId.slice(0, 8)}. ctrl+d return to graph · esc close.` : `Attached to ${runId.slice(0, 8)}. ↵ chat · ctrl+d detach.`);
+      return true;
+    }
+    const resolvedStage = resolveStageTarget(runId, stageTarget);
+    if (!resolvedStage.ok) {
+      fail(resolvedStage.message);
+      return true;
+    }
+    const stageId = resolvedStage.stageId;
+    const stageRunId = resolvedStage.runId ?? runId;
+    if (action === "pause") {
+      const result = pauseRun(stageRunId, { stageId });
+      if (!result.ok) {
+        fail(result.reason === "not_found" ? `Run not found: ${stageRunId.slice(0, 8)}` : result.reason === "already_ended" ? `Run ${stageRunId.slice(0, 8)} already ended.` : result.reason === "no_active_stages" ? `No pausable stages on run ${stageRunId.slice(0, 8)}.` : `Stage not found: ${stageTarget ?? "(unknown)"}`);
+        return true;
+      }
+      if (policy.allowInputPicker) deps.overlay.open(runId, overlaySurfaceFromContext(ctx), stageId);
+      print(result.paused.length === 0 ? `No stages were paused on run ${stageRunId.slice(0, 8)}.` : `Paused ${result.paused.length} stage(s) on run ${stageRunId.slice(0, 8)}: ${result.paused.map((s) => s.name).join(", ")}`);
+      return true;
+    }
+    const run = store.runs().find((r) => r.id === stageRunId);
+    const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
+    const isResumableContinuation = run !== undefined && !isPaused && ((run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) || (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable"));
+    if (isResumableContinuation) {
+      const continuation = deps.runtimeForContext(ctx).resumeFailedRun(stageRunId, stageId, { policy });
+      continuation.ok ? print(continuation.message) : fail(continuation.message);
+      return true;
+    }
+    const result = resumeRun(stageRunId, { stageId, message });
+    if (!result.ok) {
+      fail(`Run not found: ${stageRunId.slice(0, 8)}`);
+      return true;
+    }
+    if (!isPaused) {
+      if (policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
+      print(result.message ?? `Snapshot available: run ${result.runId} (${result.snapshot.name}) — status: ${result.snapshot.status}, stages: ${result.snapshot.stages.length}`);
+      return true;
+    }
+    if (!message && stageId && policy.allowInputPicker) deps.overlay.open(runId, overlaySurfaceFromContext(ctx), stageId);
+    result.resumed.length === 0
+      ? fail(`No paused stages on run ${stageRunId.slice(0, 8)}.`)
+      : print(`Resumed ${result.resumed.length} stage(s) on run ${stageRunId.slice(0, 8)}${message ? ` with message: "${message}"` : ""}.`);
+    return true;
+  }
+
+  return false;
+}

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -66,7 +66,7 @@ const StageSessionOptionProperties = {
   agentDir: Type.Optional(Type.String()),
   authStorage: Type.Optional(SdkSessionOptionSchema("authStorage")),
   modelRegistry: Type.Optional(SdkSessionOptionSchema("modelRegistry")),
-  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh. A parenthesized context-window token may precede the suffix, e.g. github-copilot/claude-opus-4.8 (1m):high." })),
+  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh. A parenthesized context-window token may precede or follow the suffix, e.g. github-copilot/claude-opus-4.8 (1m):high or github-copilot/claude-opus-4.8:high (1m). Use (long) for a generic long-context marker, or a rounded size matching the model's long tier (e.g. (1m) or (1.1m)); both select the model's advertised long tier." })),
   contextWindow: Type.Optional(Type.Number({ description: "Context-window token budget for the stage session (e.g. 1000000). Non-strict by default: an unsupported value keeps the model's default window. Prefer the per-model `(1m)` token in a model/fallbackModels entry when only specific models should use a larger window." })),
   contextWindowStrict: Type.Optional(Type.Boolean({ description: "Treat an unsupported contextWindow as an error instead of falling back to the model's default window." })),
   thinkingLevel: Type.Optional(SdkSessionOptionSchema("thinkingLevel")),

package/dist/builtin/workflows/src/extension/workflow-stage-results.ts

@@ -0,0 +1,264 @@
+import type { StageSnapshot, StageStatus, ToolEvent } from "../shared/store-types.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+
+export type WorkflowStageSummary = {
+  id: string;
+  name: string;
+  status: StageStatus;
+  sessionId?: string;
+  sessionFile?: string;
+  transcriptPath?: string;
+  error?: string;
+  skippedReason?: string;
+  awaitingInputSince?: number;
+  pendingPrompt?: StageSnapshot["pendingPrompt"];
+  inputRequest?: StageSnapshot["inputRequest"];
+  promptFootprint?: StageSnapshot["promptFootprint"];
+};
+
+export type WorkflowTranscriptEntry = {
+  role: string;
+  text?: string;
+  toolName?: string;
+  output?: string;
+  timestamp?: number;
+};
+
+type MessageContentBlock = { readonly type?: string; readonly text?: string };
+
+export type MessageLike = {
+  readonly role?: string;
+  readonly content?: string | readonly MessageContentBlock[];
+  readonly name?: string;
+  readonly toolName?: string;
+  readonly timestamp?: number;
+  readonly createdAt?: number;
+};
+
+export function cloneStage(stage: StageSnapshot): StageSnapshot & { transcriptPath?: string } {
+  const cloned = structuredClone(stage) as StageSnapshot & { transcriptPath?: string };
+  if (cloned.sessionFile !== undefined) cloned.transcriptPath = cloned.sessionFile;
+  return cloned;
+}
+
+export function summarizeStage(stage: StageSnapshot): WorkflowStageSummary {
+  return {
+    id: stage.id,
+    name: stage.name,
+    status: stage.status,
+    sessionId: stage.sessionId,
+    sessionFile: stage.sessionFile,
+    transcriptPath: stage.sessionFile,
+    error: stage.error,
+    skippedReason: stage.skippedReason,
+    awaitingInputSince: stage.awaitingInputSince,
+    pendingPrompt: stage.pendingPrompt === undefined
+      ? undefined
+      : structuredClone(stage.pendingPrompt),
+    inputRequest: stage.inputRequest === undefined
+      ? undefined
+      : structuredClone(stage.inputRequest),
+    promptFootprint: stage.promptFootprint === undefined
+      ? undefined
+      : structuredClone(stage.promptFootprint),
+  };
+}
+
+const DEFAULT_TRANSCRIPT_LIMIT = 5;
+
+type TranscriptEntrySelection = {
+  entries: WorkflowTranscriptEntry[];
+  truncated: boolean;
+  entryCount: number;
+  entryLimit?: number;
+};
+
+type WorkflowTranscriptResult = Extract<WorkflowToolResult, { action: "transcript" }>;
+
+function isTranscriptPreviewExplicit(args: WorkflowToolArgs): boolean {
+  return args.tail !== undefined || args.limit !== undefined;
+}
+
+export function shouldIncludeSnapshotToolOutput(args: WorkflowToolArgs, sessionFile?: string): boolean {
+  return args.includeToolOutput === true && (
+    isTranscriptPreviewExplicit(args) || sessionFile === undefined
+  );
+}
+
+function requestedTranscriptEntryLimit(args: WorkflowToolArgs): number {
+  const raw = args.tail ?? args.limit;
+  if (raw === undefined) return DEFAULT_TRANSCRIPT_LIMIT;
+  if (!Number.isFinite(raw) || raw <= 0) return 0;
+  return Math.floor(raw);
+}
+
+function selectTranscriptEntries(
+  entries: readonly WorkflowTranscriptEntry[],
+  args: WorkflowToolArgs,
+): TranscriptEntrySelection {
+  const count = requestedTranscriptEntryLimit(args);
+  const entryCount = entries.length;
+  if (count === 0) return { entries: [], truncated: false, entryCount, entryLimit: count };
+  if (entries.length <= count) {
+    return { entries: [...entries], truncated: false, entryCount, entryLimit: count };
+  }
+  return {
+    entries: entries.slice(entries.length - count),
+    truncated: true,
+    entryCount,
+    entryLimit: count,
+  };
+}
+
+function transcriptLazyReadPrompt(path: string): string {
+  return `Transcript not inlined to protect context. Read it lazily from ${path} with your file read tools (read small ranges; rg/grep for targeted lookups).`;
+}
+
+function transcriptFallbackNote(limit: number): string {
+  return `No transcript file path is available for this stage; falling back to a bounded inline preview of up to ${limit} recent ${limit === 1 ? "entry" : "entries"}.`;
+}
+
+export function shapeTranscriptResult(input: {
+  runId: string;
+  stageId: string;
+  source: "live" | "snapshot";
+  entryCount: number;
+  buildEntries: () => readonly WorkflowTranscriptEntry[];
+  args: WorkflowToolArgs;
+  sessionId?: string | undefined;
+  sessionFile?: string | undefined;
+  transcriptPath?: string | undefined;
+}): WorkflowTranscriptResult {
+  const transcriptPath = input.transcriptPath ?? input.sessionFile;
+  if (transcriptPath !== undefined && !isTranscriptPreviewExplicit(input.args)) {
+    const result: WorkflowTranscriptResult = {
+      action: "transcript",
+      runId: input.runId,
+      stageId: input.stageId,
+      source: input.source,
+      entries: [],
+      truncated: input.entryCount > 0,
+      entryCount: input.entryCount,
+      entryLimit: 0,
+      lazyReadPrompt: transcriptLazyReadPrompt(transcriptPath),
+      inlineMode: "path_only",
+    };
+    if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+    if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+    result.transcriptPath = transcriptPath;
+    return result;
+  }
+
+  const limited = selectTranscriptEntries(input.buildEntries(), input.args);
+  const result: WorkflowTranscriptResult = {
+    action: "transcript",
+    runId: input.runId,
+    stageId: input.stageId,
+    source: input.source,
+    entries: limited.entries,
+    truncated: limited.truncated,
+    entryCount: limited.entryCount,
+    entryLimit: limited.entryLimit,
+    inlineMode: transcriptPath === undefined ? "fallback_preview" : "preview",
+  };
+  if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+  if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+  if (transcriptPath !== undefined) result.transcriptPath = transcriptPath;
+  if (transcriptPath === undefined) {
+    result.fallbackNote = transcriptFallbackNote(limited.entryLimit ?? DEFAULT_TRANSCRIPT_LIMIT);
+  }
+  return result;
+}
+
+function messageText(content: MessageLike["content"]): string | undefined {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return undefined;
+  let sawTextBlock = false;
+  const text = content
+    .map((block) => {
+      if (block.type === "text" && typeof block.text === "string") {
+        sawTextBlock = true;
+        return block.text;
+      }
+      return "";
+    })
+    .join("");
+  return sawTextBlock ? text : undefined;
+}
+
+export function transcriptEntryFromMessage(message: MessageLike): WorkflowTranscriptEntry {
+  const entry: WorkflowTranscriptEntry = { role: message.role ?? "unknown" };
+  const text = messageText(message.content);
+  if (text !== undefined) entry.text = text;
+  const toolName = message.toolName ?? message.name;
+  if (toolName !== undefined) entry.toolName = toolName;
+  const timestamp = message.timestamp ?? message.createdAt;
+  if (timestamp !== undefined) entry.timestamp = timestamp;
+  return entry;
+}
+
+function transcriptEntriesFromToolEvents(
+  events: readonly ToolEvent[],
+  includeOutput: boolean,
+): WorkflowTranscriptEntry[] {
+  return events.map((event) => ({
+    role: "tool",
+    toolName: event.name,
+    output: includeOutput ? event.output : undefined,
+    timestamp: event.endedAt ?? event.startedAt,
+  }));
+}
+
+function sortTranscriptEntriesChronologically(
+  entries: readonly WorkflowTranscriptEntry[],
+): WorkflowTranscriptEntry[] {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => {
+      const aTimestamp = a.entry.timestamp;
+      const bTimestamp = b.entry.timestamp;
+      if (
+        typeof aTimestamp === "number" &&
+        typeof bTimestamp === "number" &&
+        aTimestamp !== bTimestamp
+      ) {
+        return aTimestamp - bTimestamp;
+      }
+      return a.index - b.index;
+    })
+    .map(({ entry }) => entry);
+}
+
+function terminalTranscriptEntry(
+  role: "assistant" | "notice",
+  text: string,
+  endedAt: number | undefined,
+): WorkflowTranscriptEntry {
+  const entry: WorkflowTranscriptEntry = { role, text };
+  if (endedAt !== undefined) entry.timestamp = endedAt;
+  return entry;
+}
+
+export function snapshotTranscriptEntries(
+  snapshot: StageSnapshot | undefined,
+  includeOutput: boolean,
+): WorkflowTranscriptEntry[] {
+  if (snapshot === undefined) return [];
+  const entries: WorkflowTranscriptEntry[] = [
+    ...transcriptEntriesFromToolEvents(snapshot.toolEvents ?? [], includeOutput),
+  ];
+  if (snapshot.result !== undefined) {
+    entries.push(terminalTranscriptEntry("assistant", snapshot.result, snapshot.endedAt));
+  }
+  if (snapshot.error !== undefined) {
+    entries.push(terminalTranscriptEntry("notice", snapshot.error, snapshot.endedAt));
+  }
+  return sortTranscriptEntriesChronologically(entries);
+}
+
+export function snapshotTranscriptEntryCount(snapshot: StageSnapshot | undefined): number {
+  return (snapshot?.toolEvents?.length ?? 0)
+    + (snapshot?.result !== undefined ? 1 : 0)
+    + (snapshot?.error !== undefined ? 1 : 0);
+}