oh-my-workflow 0.1.0

package/src/adapters/codex.ts

@@ -0,0 +1,149 @@
+// The codex adapter (EXPERIMENTAL). A node is a whole `codex exec` run. codex
+// streams its result as JSONL dot-notation events on stdout:
+//   thread.started{thread_id} → turn.started → item.completed{item:agent_message}
+//   → turn.completed{usage}
+// We take the LAST agent_message's text as the result and thread_id as the
+// sessionId (for `exec resume` follow-ups). There is no cost field (tokens only),
+// so costUsd stays undefined.
+//
+// Per openai/codex#15451 the stream can include malformed lines; parseCodexJsonl
+// tolerates them line-by-line and, if no final agent_message is found, fails
+// ACTIONABLY (surfaces the reason) rather than silently returning empty — the
+// authoring agent can read WHY in the journal.
+
+import type { AgentPort, AgentResult, InvokeRequest } from "./types";
+import type { ClaudeSpawn as Spawn, ClaudeSpawnResult as SpawnResult } from "./claude";
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+export function parseCodexJsonl(stdout: string): AgentResult {
+  const lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+  let threadId: string | undefined;
+  let lastMessage: string | undefined;
+  let failure: string | undefined;
+  let malformed = 0;
+
+  for (const line of lines) {
+    let ev: Record<string, unknown>;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      malformed++; // #15451 tolerance — skip junk, keep parsing
+      continue;
+    }
+    switch (ev.type) {
+      case "thread.started":
+        threadId = ev.thread_id as string | undefined;
+        break;
+      case "item.completed": {
+        const item = ev.item as { type?: string; text?: string } | undefined;
+        if (item?.type === "agent_message" && typeof item.text === "string") lastMessage = item.text;
+        break;
+      }
+      case "error":
+        failure = typeof ev.message === "string" ? ev.message : JSON.stringify(ev);
+        break;
+      case "turn.failed": {
+        const err = ev.error as { message?: string } | undefined;
+        failure = failure ?? err?.message ?? "turn failed";
+        break;
+      }
+    }
+  }
+
+  if (failure) {
+    // No refusal kind for codex: its stream has no distinct decline signal. A
+    // hard failure (`error` / `turn.failed`) is nonzero_exit; a SOFT decline
+    // ("I can't help with that") instead arrives as a normal agent_message and
+    // returns ok:true below — an invisible abstention we can't tell from a real
+    // answer here. So codex declines are NOT nonzero_exit; refusal is claude-only.
+    return { ok: false, kind: "nonzero_exit", stderr: `codex: ${failure}`, meta: { durationMs: 0 } };
+  }
+  if (lastMessage === undefined) {
+    const hint = malformed > 0 ? ` (${malformed} malformed JSONL line(s))` : "";
+    return {
+      ok: false,
+      kind: "nonzero_exit",
+      stderr: `codex produced no agent_message${hint}`,
+      meta: { durationMs: 0 },
+    };
+  }
+  return { ok: true, text: lastMessage, meta: { durationMs: 0, sessionId: threadId } };
+}
+
+export type CodexAdapterDeps = {
+  spawn?: Spawn;
+  bin?: string;
+  /** codex sandbox policy. Defaults to workspace-write (a coding node needs to
+   *  write); override to read-only for safe demos or danger-full-access. */
+  sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+};
+
+function defaultSpawn(bin: string): Spawn {
+  return async (args, opts) => {
+    const proc = Bun.spawn([bin, ...args], {
+      cwd: opts?.cwd,
+      stdin: "ignore", // codex reads stdin otherwise and hangs waiting for EOF
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (opts?.timeoutMs && opts.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill();
+      }, opts.timeoutMs);
+    }
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    if (timer) clearTimeout(timer);
+    return { code, stdout, stderr, timedOut };
+  };
+}
+
+export function makeCodexAdapter(deps: CodexAdapterDeps = {}): AgentPort {
+  const spawn = deps.spawn ?? defaultSpawn(deps.bin ?? "codex");
+  const sandbox = deps.sandbox ?? "workspace-write";
+
+  async function run(args: string[], cwd?: string, timeoutMs?: number): Promise<AgentResult> {
+    let res: SpawnResult;
+    try {
+      res = await spawn(args, { cwd, timeoutMs });
+    } catch (e) {
+      return { ok: false, kind: "spawn_failure", stderr: errMsg(e), meta: { durationMs: 0 } };
+    }
+    if (res.timedOut) {
+      return { ok: false, kind: "timeout", stderr: res.stderr || `timed out after ${timeoutMs}ms`, meta: { durationMs: 0 } };
+    }
+    if (!res.stdout.trim()) {
+      // No JSONL at all → fall back to the process-level failure.
+      return {
+        ok: false,
+        kind: "nonzero_exit",
+        stderr: res.stderr || `codex exited ${res.code} with no output`,
+        meta: { durationMs: 0 },
+      };
+    }
+    // JSONL present (even on a non-zero exit, e.g. turn.failed) → let the parser
+    // decide ok/fail and surface the reason.
+    return parseCodexJsonl(res.stdout);
+  }
+
+  return {
+    name: "codex",
+    invoke(req: InvokeRequest): Promise<AgentResult> {
+      const args = ["exec", "--json", "-s", sandbox];
+      if (req.model) args.push("-m", req.model);
+      args.push(req.prompt);
+      return run(args, req.cwd, req.timeoutMs);
+    },
+    followUp(sessionId: string, prompt: string): Promise<AgentResult> {
+      const args = ["exec", "resume", sessionId, "--json", "-s", sandbox, prompt];
+      return run(args);
+    },
+  };
+}

package/src/adapters/fake.ts

@@ -0,0 +1,70 @@
+// The fake adapter is two things at once: the test double for the whole suite,
+// AND the engine behind `--agent fake` — the free, deterministic, no-API-key
+// try-it path that proves the spine (pipeline/parallel/phase + journal +
+// self-repair loop) for a stranger before they touch a real agent. So it is
+// real product code, not just a mock.
+
+import type { AgentPort, AgentResult, AgentFailureKind, InvokeRequest } from "./types";
+
+export type FakeResponse =
+  | { text: string; sessionId?: string; costUsd?: number }
+  | { fail: AgentFailureKind; stderr?: string };
+
+export type FakeRule = {
+  match: (prompt: string) => boolean;
+  responses: FakeResponse[];
+};
+
+export type FakeAdapterOptions = {
+  rules?: FakeRule[];
+  default?: FakeResponse;
+  durationMs?: number;
+};
+
+function toResult(r: FakeResponse, durationMs: number): AgentResult {
+  if ("fail" in r) {
+    return { ok: false, kind: r.fail, stderr: r.stderr, meta: { durationMs } };
+  }
+  return {
+    ok: true,
+    text: r.text,
+    meta: { durationMs, sessionId: r.sessionId, costUsd: r.costUsd },
+  };
+}
+
+export function makeFakeAdapter(opts: FakeAdapterOptions = {}): AgentPort {
+  const rules = opts.rules ?? [];
+  const durationMs = opts.durationMs ?? 0;
+  const fallback: FakeResponse = opts.default ?? { text: "{}" };
+  // Per-rule cursor so a sequence advances across invocations and sticks on last.
+  const cursors = new Map<FakeRule, number>();
+  // sessionId -> issuing rule, so followUp continues the right conversation even
+  // when the retry prompt no longer matches the original rule's predicate.
+  const sessionRule = new Map<string, FakeRule>();
+
+  const advance = (rule: FakeRule): FakeResponse => {
+    const i = cursors.get(rule) ?? 0;
+    const idx = Math.min(i, rule.responses.length - 1);
+    cursors.set(rule, i + 1);
+    const resp = rule.responses[idx] ?? fallback;
+    if ("text" in resp && resp.sessionId) sessionRule.set(resp.sessionId, rule);
+    return resp;
+  };
+
+  const nextForPrompt = (prompt: string): FakeResponse => {
+    const rule = rules.find((r) => r.match(prompt));
+    if (!rule || rule.responses.length === 0) return fallback;
+    return advance(rule);
+  };
+
+  return {
+    name: "fake",
+    async invoke(req: InvokeRequest): Promise<AgentResult> {
+      return toResult(nextForPrompt(req.prompt), durationMs);
+    },
+    async followUp(sessionId: string, prompt: string): Promise<AgentResult> {
+      const rule = sessionRule.get(sessionId);
+      return toResult(rule ? advance(rule) : nextForPrompt(prompt), durationMs);
+    },
+  };
+}

package/src/adapters/types.ts

@@ -0,0 +1,43 @@
+// The contract every adapter implements. omw's only job is to be the thin
+// deterministic glue between an orchestration script and these subprocess nodes.
+// Kept tiny on purpose: a node is a whole coding agent, not a single LLM call.
+
+/** Why an invocation failed. The journal records this `kind` so the authoring
+ *  agent can read WHICH failure happened and repair its own script.
+ *  `refusal` is a DECLINE (the model said no — HTTP 200, `stop_reason:"refusal"`),
+ *  kept distinct from a crash so an abstain-quorum can treat declined ≠ failed. */
+export type AgentFailureKind = "timeout" | "nonzero_exit" | "spawn_failure" | "refusal";
+
+export type AgentResult =
+  | {
+      ok: true;
+      text: string;
+      meta: {
+        durationMs: number;
+        /** Present when the adapter supports session resume (claude --resume). */
+        sessionId?: string;
+        costUsd?: number;
+      };
+    }
+  | {
+      ok: false;
+      kind: AgentFailureKind;
+      stderr?: string;
+      meta?: { durationMs: number };
+    };
+
+export type InvokeRequest = {
+  prompt: string;
+  /** Tier alias ("fast" | "smart") or a raw model string passed through. */
+  model?: string;
+  cwd?: string;
+  timeoutMs?: number;
+};
+
+export type AgentPort = {
+  name: string;
+  invoke(req: InvokeRequest): Promise<AgentResult>;
+  /** Optional in-session follow-up (claude --resume). When absent, the runtime
+   *  re-invokes fresh with the error feedback appended to the prompt. */
+  followUp?(sessionId: string, prompt: string): Promise<AgentResult>;
+};

package/src/cli/omw.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+// The `omw` entry. Runs the .ts directly under bun (no build step) so
+// `bunx oh-my-workflow run …` works on a stranger's machine. Dispatches the
+// subcommand; the heavy lifting lives in the tested run/replay libraries.
+
+import { runCommand } from "./run";
+import { replayCommand } from "./replay";
+import { validateCommand } from "./validate";
+
+const io = {
+  stdout: (s: string) => process.stdout.write(s),
+  stderr: (s: string) => process.stderr.write(s),
+};
+
+async function main(argv: string[]): Promise<number> {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case "run":
+      return runCommand(rest, io);
+    case "replay":
+      return replayCommand(rest, io);
+    case "validate":
+      return validateCommand(rest, io);
+    default:
+      io.stderr(
+        "usage: omw <command>\n\n" +
+          "commands:\n" +
+          "  run <workflow> --agent <fake|claude|codex|pi> [--args JSON] [--concurrency N] [--resume <journal.jsonl>] [--pretty]\n" +
+          "  replay <journal.jsonl> [--json]\n" +
+          "  validate <workflow> [--json]\n\n" +
+          "free demo (no API key):  omw run examples/deep-research --agent fake\n",
+      );
+      return cmd === undefined ? 2 : 2;
+  }
+}
+
+main(process.argv.slice(2)).then((code) => process.exit(code));

package/src/cli/replay.ts

@@ -0,0 +1,98 @@
+// `omw replay <journal.jsonl> [--json]`. Re-derives the phase / fan-out / stats
+// view from a recorded journal. This is honestly a FIXTURE REPLAY — reading back
+// what a run already recorded — NOT a live resume (re-executing from the longest
+// unchanged prefix), which is v2 and layers on without a format change.
+
+import { readFileSync } from "node:fs";
+import type { Io } from "./run";
+import { parseJournalLines } from "../journal";
+import { renderTree } from "./run";
+
+export type ReplayArgs = { path: string; json: boolean };
+
+export type ReplayParse = { ok: true; value: ReplayArgs } | { ok: false; error: string };
+
+export function parseReplayArgs(argv: string[]): ReplayParse {
+  let path: string | undefined;
+  let json = false;
+  for (const tok of argv) {
+    if (tok === "--json") json = true;
+    else if (path === undefined) path = tok;
+    else return { ok: false, error: `unexpected argument: ${tok}` };
+  }
+  if (path === undefined) return { ok: false, error: "missing journal path" };
+  return { ok: true, value: { path, json } };
+}
+
+export type ReplaySummary = {
+  run?: string;
+  wf?: string;
+  phases: string[];
+  calls: { total: number; ok: number; failed: number };
+  failures: Array<{ call: number; kind?: string }>;
+  ok?: boolean;
+};
+
+export function summarizeJournal(lines: string[]): ReplaySummary {
+  const phases: string[] = [];
+  const failures: Array<{ call: number; kind?: string }> = [];
+  let run: string | undefined;
+  let wf: string | undefined;
+  let ok: boolean | undefined;
+  let total = 0;
+  let okCount = 0;
+  let failed = 0;
+
+  for (const e of parseJournalLines(lines)) {
+    switch (e.ev) {
+      case "run_start":
+        run = e.run;
+        wf = e.wf;
+        break;
+      case "phase":
+        phases.push(e.title);
+        break;
+      case "agent_end":
+        total++;
+        if (e.ok) okCount++;
+        else {
+          failed++;
+          failures.push({ call: e.call, kind: e.kind });
+        }
+        break;
+      case "run_end":
+        ok = e.ok;
+        break;
+    }
+  }
+
+  return { run, wf, phases, calls: { total, ok: okCount, failed }, failures, ok };
+}
+
+/** Read a journal file and print either its reconstructed tree (default) or a
+ *  structured summary (--json). Exit 2 on usage error, 1 if the file is
+ *  unreadable, 0 otherwise. */
+export function replayCommand(argv: string[], io: Io): number {
+  const parsed = parseReplayArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(JSON.stringify({ error: "usage", message: parsed.error }) + "\n");
+    io.stderr("usage: omw replay <journal.jsonl> [--json]\n");
+    return 2;
+  }
+
+  let lines: string[];
+  try {
+    lines = readFileSync(parsed.value.path, "utf8").split("\n");
+  } catch (e) {
+    io.stderr(JSON.stringify({ error: "read_failed", path: parsed.value.path }) + "\n");
+    return 1;
+  }
+
+  if (parsed.value.json) {
+    io.stdout(JSON.stringify(summarizeJournal(lines)) + "\n");
+  } else {
+    io.stdout(renderTree(lines) + "\n");
+    io.stderr("(fixture replay — reconstructed from recorded journal, not a live resume)\n");
+  }
+  return 0;
+}