oh-my-workflow 0.1.0

package/src/cli/run.ts

@@ -0,0 +1,371 @@
+// `omw run <wf> --agent <a> [--args JSON] [--concurrency N] [--pretty]`.
+// Parsing is a pure function so the input contract is testable without touching
+// the filesystem, a clock, or a subprocess.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentPort } from "../adapters/types";
+import { makeFakeAdapter, type FakeAdapterOptions } from "../adapters/fake";
+import { makeClaudeAdapter } from "../adapters/claude";
+import { makeCodexAdapter } from "../adapters/codex";
+import type { Runtime } from "../runtime";
+import { makeRuntime } from "../runtime";
+import { makeJournal, parseJournalLines, type JournalEvent } from "../journal";
+import type { ResumeIndex } from "../resume";
+import { makeResumeIndexFromLines } from "../resume";
+
+export type RunOptions = {
+  wfPath: string;
+  agent: string;
+  args: unknown;
+  concurrency?: number;
+  pretty: boolean;
+  /** Path to a prior run's journal to resume from (longest-unchanged-prefix). */
+  resume?: string;
+};
+
+export type ParseResult =
+  | { ok: true; value: RunOptions }
+  | { ok: false; error: string };
+
+export function parseRunArgs(argv: string[]): ParseResult {
+  let wfPath: string | undefined;
+  let agent: string | undefined;
+  let args: unknown;
+  let concurrency: number | undefined;
+  let pretty = false;
+  let resume: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i]!;
+    switch (tok) {
+      case "--agent":
+        agent = argv[++i];
+        break;
+      case "--args": {
+        const raw = argv[++i];
+        try {
+          args = JSON.parse(raw!);
+        } catch {
+          return { ok: false, error: `--args must be valid JSON, got: ${raw}` };
+        }
+        break;
+      }
+      case "--concurrency": {
+        const raw = argv[++i];
+        const n = Number(raw);
+        if (raw === undefined || !Number.isInteger(n) || n < 1) {
+          return { ok: false, error: `--concurrency must be a positive integer, got: ${raw}` };
+        }
+        concurrency = n;
+        break;
+      }
+      case "--pretty":
+        pretty = true;
+        break;
+      case "--resume":
+        resume = argv[++i];
+        if (!resume) return { ok: false, error: "--resume requires a journal path" };
+        break;
+      default:
+        if (wfPath === undefined) wfPath = tok;
+        else return { ok: false, error: `unexpected argument: ${tok}` };
+    }
+  }
+
+  if (wfPath === undefined) return { ok: false, error: "missing workflow path" };
+  if (agent === undefined) return { ok: false, error: "missing --agent <name>" };
+
+  return { ok: true, value: { wfPath, agent, args, concurrency, pretty, resume } };
+}
+
+// ── workflow execution ──────────────────────────────────────────────────────
+
+/** A loaded workflow module. The orchestration script the host agent authors is
+ *  the default export; `fake` is optional fixtures used only by `--agent fake`
+ *  so the example is deterministic green with no API key. */
+export type LoadedWorkflow = {
+  workflow: (rt: Runtime, args: unknown) => unknown | Promise<unknown>;
+  fake?: FakeAdapterOptions;
+};
+
+/** Either a ready adapter, or a structured "not installed" signal (exit 3). */
+export type AdapterResolution =
+  | { adapter: AgentPort }
+  | { missing: string; installHint: string };
+
+/** Entry filenames tried, in order, when a workflow path is a directory. */
+const ENTRY_NAMES = ["workflow.ts", "workflow.js", "index.ts", "index.js"];
+
+/** Package root, so bundled paths (e.g. `examples/…`) resolve when omw is
+ *  installed and invoked from an arbitrary cwd, not only from inside a clone. */
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Resolve a workflow path: an absolute path as-is; otherwise cwd-relative
+ *  (the user's own workflows) first, then package-relative as a fallback so the
+ *  shipped `examples/…` demo runs post-install. The cwd path is kept for the
+ *  not-found error so the message points where the user actually looked. */
+export function resolveWorkflowPath(wfPath: string): string {
+  if (isAbsolute(wfPath)) return wfPath;
+  const fromCwd = resolve(process.cwd(), wfPath);
+  if (existsSync(fromCwd)) return fromCwd;
+  // Fall back to the package-bundled demo ONLY for the `examples/` namespace, so
+  // a user's mistyped workflow path can't silently resolve to a shipped file.
+  if (wfPath === "examples" || wfPath.startsWith("examples/")) {
+    const fromPkg = resolve(PKG_ROOT, wfPath);
+    if (existsSync(fromPkg)) return fromPkg;
+  }
+  return fromCwd;
+}
+
+/** Load a workflow module from a file path or a directory (resolved to its
+ *  conventional entry). The default export is the orchestration fn; a missing
+ *  default is an authoring bug surfaced as a load error, not a silent no-op. */
+export async function loadWorkflow(wfPath: string): Promise<LoadedWorkflow> {
+  const abs = resolveWorkflowPath(wfPath);
+  let entry = abs;
+  let isDir = false;
+  try {
+    isDir = statSync(abs).isDirectory();
+  } catch {
+    throw new Error(`workflow path not found: ${wfPath}`);
+  }
+  if (isDir) {
+    const found = ENTRY_NAMES.map((n) => join(abs, n)).find((p) => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    });
+    if (!found) throw new Error(`no workflow entry (${ENTRY_NAMES.join(", ")}) in directory: ${wfPath}`);
+    entry = found;
+  }
+
+  const mod = await import(entry);
+  if (typeof mod.default !== "function") {
+    throw new Error(`workflow ${wfPath} must default-export a function (rt, args) => result`);
+  }
+  return { workflow: mod.default, fake: mod.fake };
+}
+
+export type RunDeps = {
+  loadWorkflow: (wfPath: string) => Promise<LoadedWorkflow>;
+  resolveAdapter: (name: string, wf: LoadedWorkflow) => AdapterResolution;
+  journalSink: (line: string) => void;
+  now: () => number;
+  runId: () => string;
+  /** A prior run's journal as a lookup; when present, nodes whose key hits are
+   *  served from it and the adapter is skipped. Built by runCommand from the
+   *  --resume file so runWorkflow stays fs-free. */
+  resume?: ResumeIndex;
+  /** Optional human-facing tree (--pretty). Pure side-channel; never stdout. */
+  stderr?: (line: string) => void;
+};
+
+export type RunOutcome = {
+  exitCode: number;
+  /** The result JSON — a single blob, stdout only. Present on exit 0 and on
+   *  exit 4 (completed, but a node hit internal_error). */
+  stdout?: string;
+  /** Structured error for stderr on a non-zero exit. */
+  error?: object;
+};
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+export async function runWorkflow(opts: RunOptions, deps: RunDeps): Promise<RunOutcome> {
+  let loaded: LoadedWorkflow;
+  try {
+    loaded = await deps.loadWorkflow(opts.wfPath);
+  } catch (e) {
+    return { exitCode: 1, error: { error: "load_failed", message: errMsg(e), wf: opts.wfPath } };
+  }
+
+  const resolved = deps.resolveAdapter(opts.agent, loaded);
+  if ("missing" in resolved) {
+    return {
+      exitCode: 3,
+      error: { error: "adapter_missing", adapter: resolved.missing, install_hint: resolved.installHint },
+    };
+  }
+
+  const runId = deps.runId();
+  const journal = makeJournal({ sink: deps.journalSink, now: deps.now });
+  const rt = makeRuntime({ adapter: resolved.adapter, journal, concurrency: opts.concurrency, resume: deps.resume });
+
+  journal.runStart({ run: runId, wf: opts.wfPath });
+  try {
+    const result = await loaded.workflow(rt, opts.args);
+    // internal_error is an AUTHOR bug (e.g. a JSON Schema that won't compile),
+    // not a flaky node — the null-contract absorbs it so the run completes, but
+    // we escalate to exit 4 so a caller (or authoring agent) doesn't read the
+    // null as a legitimate abstention. The partial result still goes to stdout.
+    const internalErrors = journal
+      .events()
+      .filter((e): e is Extract<JournalEvent, { ev: "agent_end" }> => e.ev === "agent_end" && !e.ok && e.kind === "internal_error")
+      .map((e) => e.call);
+    journal.runEnd({ ok: internalErrors.length === 0 });
+    if (internalErrors.length > 0) {
+      return {
+        exitCode: 4,
+        stdout: JSON.stringify(result),
+        error: {
+          error: "internal_error_nodes",
+          calls: internalErrors,
+          hint: "a node failed to compile/execute (likely an invalid JSON Schema) — see the journal's internal_error entries",
+        },
+      };
+    }
+    return { exitCode: 0, stdout: JSON.stringify(result) };
+  } catch (e) {
+    // A throw escaping the workflow body is a SCRIPT error (the authored JS), not
+    // a node failure — node failures are swallowed by the null-contract. Exit 1.
+    journal.runEnd({ ok: false });
+    return { exitCode: 1, error: { error: "script_error", message: errMsg(e), wf: opts.wfPath } };
+  }
+}
+
+// ── adapter resolution ──────────────────────────────────────────────────────
+
+/** Install hints surfaced (exit 3) when an adapter's CLI isn't on PATH. The
+ *  `fake` adapter is always available — it is the free, no-key demo engine. */
+const INSTALL_HINTS: Record<string, string> = {
+  claude: "npm i -g @anthropic-ai/claude-code  (then `claude login`)",
+  codex: "npm i -g @openai/codex  (experimental adapter)",
+  pi: "see https://github.com/parallel-ai/pi  (experimental adapter)",
+};
+
+/** PATH probe — injected so the missing→installed branch is testable. */
+const defaultBinExists = (bin: string): boolean => Bun.which(bin) != null;
+
+export function resolveAdapter(
+  name: string,
+  wf: LoadedWorkflow,
+  binExists: (bin: string) => boolean = defaultBinExists,
+): AdapterResolution {
+  if (name === "fake") return { adapter: makeFakeAdapter(wf.fake) };
+  if (name === "claude") {
+    // A real adapter exists, but exit 3 (adapter_missing) if the CLI isn't on
+    // PATH — tell the user what to install rather than failing mid-run.
+    if (!binExists("claude")) return { missing: "claude", installHint: INSTALL_HINTS.claude! };
+    return { adapter: makeClaudeAdapter() };
+  }
+  if (name === "codex") {
+    if (!binExists("codex")) return { missing: "codex", installHint: INSTALL_HINTS.codex! };
+    return { adapter: makeCodexAdapter() };
+  }
+  // pi lands here as it is built; until then, fail actionably.
+  return {
+    missing: name,
+    installHint: INSTALL_HINTS[name] ?? `unknown adapter "${name}". Try --agent fake for the free demo.`,
+  };
+}
+
+// ── process wiring (the bin entry calls runCommand) ─────────────────────────
+
+export type Io = {
+  stdout: (s: string) => void;
+  stderr: (s: string) => void;
+  /** Directory for journal files; defaults to ".omw". */
+  omwDir?: string;
+  runId?: () => string;
+};
+
+const defaultRunId = (): string => "r-" + Date.now().toString(36);
+
+/** Wire real fs/import deps and run. Returns the exit code; writes the result
+ *  JSON to stdout, the journal to <omwDir>/<runId>.jsonl, and any error JSON to
+ *  stderr. Usage errors (parse failures) are exit 2. */
+export async function runCommand(argv: string[], io: Io): Promise<number> {
+  const parsed = parseRunArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(JSON.stringify({ error: "usage", message: parsed.error }));
+    io.stderr(
+      "\nusage: omw run <workflow> --agent <fake|claude|codex|pi> [--args JSON] [--concurrency N] [--resume <journal.jsonl>] [--pretty]",
+    );
+    return 2;
+  }
+
+  const omwDir = io.omwDir ?? ".omw";
+  const runId = (io.runId ?? defaultRunId)();
+  const journalPath = join(omwDir, `${runId}.jsonl`);
+
+  // Resume: load the prior journal into an index. A read failure is exit 1 (an
+  // unreadable --resume path is a user error, not a reason to silently run live).
+  let resume: ResumeIndex | undefined;
+  if (parsed.value.resume) {
+    let lines: string[];
+    try {
+      lines = readFileSync(parsed.value.resume, "utf8").split("\n");
+    } catch {
+      io.stderr(JSON.stringify({ error: "resume_read_failed", path: parsed.value.resume }) + "\n");
+      return 1;
+    }
+    resume = makeResumeIndexFromLines(lines);
+    if (resume.size === 0) {
+      // Readable but no cached nodes (empty/truncated/wrong file). Warn instead
+      // of silently re-running every node live — which the user would read as a
+      // free resume while paying full adapter cost.
+      io.stderr(JSON.stringify({ warning: "resume_empty", path: parsed.value.resume }) + "\n");
+    }
+  }
+
+  const events: string[] = [];
+  const outcome = await runWorkflow(parsed.value, {
+    loadWorkflow,
+    resolveAdapter,
+    journalSink: (line) => {
+      events.push(line);
+      // Create .omw/ lazily on the first journal line, so a failed load/adapter
+      // resolution (which records nothing) doesn't litter an empty directory.
+      if (events.length === 1) mkdirSync(omwDir, { recursive: true });
+      appendFileSync(journalPath, line + "\n");
+    },
+    now: () => Date.now(),
+    runId: () => runId,
+    resume,
+  });
+
+  if (outcome.stdout !== undefined) io.stdout(outcome.stdout + "\n");
+  if (outcome.error) io.stderr(JSON.stringify(outcome.error) + "\n");
+
+  // Only surface the journal when a run actually recorded one — a load/adapter
+  // failure (exit 1/3) writes no events, so pointing at an empty file misleads.
+  if (events.length > 0) {
+    if (parsed.value.pretty) io.stderr(renderTree(events) + "\n");
+    io.stderr(`journal: ${journalPath}\n`);
+  }
+  return outcome.exitCode;
+}
+
+/** A phase/fan-out tree from journal JSONL lines — the --pretty side-channel and
+ *  the shared renderer reused by `omw replay`. Pure: events in, string out. */
+export function renderTree(lines: string[]): string {
+  const out: string[] = [];
+  let ok = 0;
+  let failed = 0;
+  for (const e of parseJournalLines(lines)) {
+    switch (e.ev) {
+      case "run_start":
+        out.push(`run ${e.run}${e.wf ? ` (${e.wf})` : ""}`);
+        break;
+      case "phase":
+        out.push(`  ▸ ${e.title}`);
+        break;
+      case "agent_start":
+        out.push(`    • ${e.label ?? `call#${e.call}`} [${e.adapter}]`);
+        break;
+      case "agent_end":
+        if (e.ok) ok++;
+        else failed++;
+        out.push(`      ${e.ok ? "✓" : `✗ ${e.kind ?? "fail"}`} call#${e.call}`);
+        break;
+      case "run_end":
+        out.push(`run_end ok=${e.ok} · ${ok} ok / ${failed} failed`);
+        break;
+    }
+  }
+  return out.join("\n");
+}

package/src/cli/validate.ts

@@ -0,0 +1,110 @@
+// `omw validate <wf> [--json]` — pre-flight check that spawns NO agents and does
+// NOT run the workflow body. omw workflows are imperative JS, so a node's schema
+// isn't knowable statically; what IS cheap to check is that the module loads and
+// default-exports a function, and that a `fake` fixture is well-formed — the
+// silent-degradation traps the SKILL warns about (top-level `responses`, a string
+// `match`, or no rules+default), each of which makes `--agent fake` match nothing
+// and quietly return `{}`. Runtime schema bugs surface separately as the exit-4
+// internal_error escalation in `omw run`.
+
+import type { Io } from "./run";
+import { loadWorkflow, type LoadedWorkflow } from "./run";
+
+export type ValidateReport = {
+  wf: string;
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+};
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** Lint a `fake` fixture for shapes that silently match nothing. Returns
+ *  human-readable warnings (empty = clean, or no fixture at all). */
+export function lintFake(fake: unknown): string[] {
+  const warnings: string[] = [];
+  if (fake == null) return warnings;
+  if (typeof fake !== "object") {
+    warnings.push(`fake must be an object { rules, default }, got ${typeof fake}`);
+    return warnings;
+  }
+  const f = fake as Record<string, unknown>;
+  if ("responses" in f) {
+    warnings.push("`fake.responses` at the top level is ignored — responses belong inside `fake.rules[].responses`");
+  }
+  const rules = f.rules;
+  if (rules !== undefined && !Array.isArray(rules)) {
+    warnings.push("`fake.rules` must be an array");
+  } else if (Array.isArray(rules)) {
+    rules.forEach((r, i) => {
+      if (r == null || typeof r !== "object") {
+        warnings.push(`fake.rules[${i}] must be an object { match, responses }`);
+        return;
+      }
+      const rule = r as Record<string, unknown>;
+      if (typeof rule.match !== "function") {
+        warnings.push(`fake.rules[${i}].match must be a predicate function (prompt) => boolean, got ${typeof rule.match}`);
+      }
+      if (!Array.isArray(rule.responses)) {
+        warnings.push(`fake.rules[${i}].responses must be an array`);
+      }
+    });
+  }
+  const hasRules = Array.isArray(rules) && rules.length > 0;
+  if (!hasRules && f.default === undefined) {
+    warnings.push("`fake` has no `rules` and no `default` — every node falls back to `{}` and will likely fail its schema");
+  }
+  return warnings;
+}
+
+/** Load the workflow (no run) and lint its fixture. `load` is injectable so the
+ *  check is testable without the filesystem. */
+export async function validateWorkflow(
+  wfPath: string,
+  load: (p: string) => Promise<LoadedWorkflow> = loadWorkflow,
+): Promise<ValidateReport> {
+  let loaded: LoadedWorkflow;
+  try {
+    loaded = await load(wfPath);
+  } catch (e) {
+    return { wf: wfPath, ok: false, errors: [errMsg(e)], warnings: [] };
+  }
+  return { wf: wfPath, ok: true, errors: [], warnings: lintFake(loaded.fake) };
+}
+
+export type ValidateParse =
+  | { ok: true; value: { wfPath: string; json: boolean } }
+  | { ok: false; error: string };
+
+export function parseValidateArgs(argv: string[]): ValidateParse {
+  let wfPath: string | undefined;
+  let json = false;
+  for (const tok of argv) {
+    if (tok === "--json") json = true;
+    else if (wfPath === undefined) wfPath = tok;
+    else return { ok: false, error: `unexpected argument: ${tok}` };
+  }
+  if (wfPath === undefined) return { ok: false, error: "missing workflow path" };
+  return { ok: true, value: { wfPath, json } };
+}
+
+/** Exit 0 only when the workflow loads AND any fake fixture is well-formed; exit
+ *  1 on a load error or a fixture problem; exit 2 on a usage error. */
+export async function validateCommand(argv: string[], io: Io): Promise<number> {
+  const parsed = parseValidateArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(JSON.stringify({ error: "usage", message: parsed.error }) + "\n");
+    io.stderr("usage: omw validate <workflow> [--json]\n");
+    return 2;
+  }
+
+  const report = await validateWorkflow(parsed.value.wfPath);
+  if (parsed.value.json) {
+    io.stdout(JSON.stringify(report) + "\n");
+  } else {
+    for (const e of report.errors) io.stderr(`✗ ${e}\n`);
+    for (const w of report.warnings) io.stderr(`⚠ ${w}\n`);
+    if (report.ok && report.warnings.length === 0) io.stdout(`✓ ${report.wf} — ok\n`);
+  }
+  return report.ok && report.warnings.length === 0 ? 0 : 1;
+}

package/src/journal.ts

@@ -0,0 +1,138 @@
+// The journal is the product's spine: a JSONL record of every step, so the
+// authoring agent can read its own failure and repair its own script. The format
+// is resume-compatible — the resume key (callIndex, promptHash, optsHash) is the
+// same longest-unchanged-prefix idea Claude Code uses, so v2 live-resume layers
+// on without a format change. Hashes exclude wall-clock time on purpose.
+
+import { createHash } from "node:crypto";
+
+const sha256 = (s: string): string => "sha256:" + createHash("sha256").update(s).digest("hex");
+
+/** Stable JSON: object keys sorted recursively so hashing is order-independent.
+ *  undefined-valued keys are dropped (matching JSON.stringify) so that an
+ *  explicitly-undefined optional field hashes identically to an absent one —
+ *  otherwise the resume key drifts between behaviorally-identical opts. */
+function stableStringify(value: unknown): string {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => (v === undefined ? "null" : stableStringify(v))).join(",") + "]";
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    .sort();
+  const body = keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",");
+  return "{" + body + "}";
+}
+
+export const promptHash = (prompt: string): string => sha256(prompt);
+export const optsHash = (opts: unknown): string => sha256(stableStringify(opts ?? null));
+
+export const resumeKey = (k: { call: number; promptHash: string; optsHash: string }): string =>
+  `${k.call}:${k.promptHash}:${k.optsHash}`;
+
+// ── events ────────────────────────────────────────────────────────────────────
+
+export type JournalEvent =
+  | { ev: "run_start"; run: string; wf?: string; args?: string; ts: number }
+  | { ev: "phase"; title: string }
+  | {
+      ev: "agent_start";
+      call: number;
+      label?: string;
+      phase?: string;
+      adapter: string;
+      promptHash: string;
+      optsHash: string;
+      ts: number;
+    }
+  | { ev: "attempt"; call: number; n: number; kind: string; errors?: string[]; stderr?: string; rawText?: string }
+  | {
+      ev: "agent_end";
+      call: number;
+      ok: boolean;
+      kind?: string;
+      result?: unknown;
+      durationMs?: number;
+      // Incremental v2 field: true when this end was served from a resume index
+      // (the adapter was skipped). Absent on a live run — the 7-event STRUCTURE is
+      // unchanged, so old journals stay readable.
+      cached?: boolean;
+      // Diagnostic payload so the authoring agent can read WHY a node failed:
+      // adapter stderr, the node's raw non-conforming text, or an internal error.
+      stderr?: string;
+      rawText?: string;
+      error?: string;
+    }
+  | { ev: "log"; msg: string }
+  | { ev: "run_end"; ok: boolean; stats?: Record<string, unknown> };
+
+export type Sink = (line: string) => void;
+
+export type Journal = {
+  runStart(e: { run: string; wf?: string; args?: string }): void;
+  phase(title: string): void;
+  agentStart(e: {
+    call: number;
+    label?: string;
+    phase?: string;
+    adapter: string;
+    promptHash: string;
+    optsHash: string;
+  }): void;
+  attempt(e: { call: number; n: number; kind: string; errors?: string[]; stderr?: string; rawText?: string }): void;
+  agentEnd(e: {
+    call: number;
+    ok: boolean;
+    kind?: string;
+    result?: unknown;
+    durationMs?: number;
+    cached?: boolean;
+    stderr?: string;
+    rawText?: string;
+    error?: string;
+  }): void;
+  log(msg: string): void;
+  runEnd(e: { ok: boolean; stats?: Record<string, unknown> }): void;
+  events(): JournalEvent[];
+};
+
+/** Parse recorded journal JSONL into events, tolerating blank and malformed
+ *  lines (a partially-flushed journal still yields its valid prefix). The single
+ *  reader shared by resume-index build, `omw replay`, and the --pretty tree, so
+ *  those three never disagree about what a journal file means. */
+export function parseJournalLines(lines: string[]): JournalEvent[] {
+  const events: JournalEvent[] = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      events.push(JSON.parse(line) as JournalEvent);
+    } catch {
+      // skip malformed line
+    }
+  }
+  return events;
+}
+
+export function makeJournal(opts?: { sink?: Sink; now?: () => number }): Journal {
+  const now = opts?.now ?? (() => Date.now());
+  const sink = opts?.sink;
+  const events: JournalEvent[] = [];
+
+  const emit = (e: JournalEvent): void => {
+    events.push(e);
+    sink?.(JSON.stringify(e));
+  };
+
+  return {
+    runStart: (e) => emit({ ev: "run_start", ts: now(), ...e }),
+    phase: (title) => emit({ ev: "phase", title }),
+    agentStart: (e) => emit({ ev: "agent_start", ts: now(), ...e }),
+    attempt: (e) => emit({ ev: "attempt", ...e }),
+    agentEnd: (e) => emit({ ev: "agent_end", ...e }),
+    log: (msg) => emit({ ev: "log", msg }),
+    runEnd: (e) => emit({ ev: "run_end", ...e }),
+    events: () => events,
+  };
+}

package/src/resume.ts

@@ -0,0 +1,48 @@
+// The resume index turns a PRIOR run's journal into a lookup: (call, promptHash,
+// optsHash) -> result. It is the read side of the frozen resume contract — the
+// same longest-unchanged-prefix key the journal records — so v2 live-resume
+// layers on without a format change. Only ok:true ends are cached; a failed node
+// has no entry, so resume re-runs it live (partial-failure recompute).
+
+import { type JournalEvent, parseJournalLines, resumeKey } from "./journal";
+
+export type ResumeKey = { call: number; promptHash: string; optsHash: string };
+
+export type ResumeHit = { found: false } | { found: true; value: unknown };
+
+export type ResumeIndex = {
+  lookup(key: ResumeKey): ResumeHit;
+  /** Count of cached (ok) nodes available to resume. 0 means an empty/truncated/
+   *  wrong journal, so the caller can warn instead of silently re-running live. */
+  size: number;
+};
+
+export function makeResumeIndex(events: JournalEvent[]): ResumeIndex {
+  const byCall = new Map<number, ResumeKey>();
+  const results = new Map<string, unknown>();
+
+  for (const e of events) {
+    if (e.ev === "agent_start") {
+      byCall.set(e.call, { call: e.call, promptHash: e.promptHash, optsHash: e.optsHash });
+    } else if (e.ev === "agent_end" && e.ok) {
+      const k = byCall.get(e.call);
+      if (k) results.set(resumeKey(k), e.result);
+    }
+  }
+
+  return {
+    lookup(key) {
+      const rk = resumeKey(key);
+      if (!results.has(rk)) return { found: false };
+      return { found: true, value: results.get(rk) };
+    },
+    size: results.size,
+  };
+}
+
+/** Build a resume index from raw journal JSONL lines (a recorded run file).
+ *  Tolerates blank/malformed lines the same way the replay summarizer does, so a
+ *  partially-flushed journal still resumes its valid prefix. */
+export function makeResumeIndexFromLines(lines: string[]): ResumeIndex {
+  return makeResumeIndex(parseJournalLines(lines));
+}