oh-my-workflow 0.2.0 → 0.4.0

package/src/adapters/claude.ts

@@ -8,7 +8,7 @@
 // Spawn is injected so the parse/argv logic is tested without a subprocess or an
 // API call; the default spawn uses Bun.spawn and is exercised live under OMW_LIVE.
 
-import type { AgentPort, AgentResult, InvokeRequest } from "./types";
+import type { AgentPort, AgentResult, FollowUpOpts, InvokeRequest } from "./types";
 
 const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
 
@@ -18,6 +18,9 @@ const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(
 export function parseClaudeResult(raw: unknown): AgentResult {
   const j = raw as Record<string, unknown> | null;
   const durationMs = Number(j?.duration_ms) || 0;
+  // Tokens are surfaced on success AND failure: an error/refusal envelope still
+  // carries `usage`, so budget accounting counts a failed node's real spend.
+  const outputTokens = (j?.usage as { output_tokens?: number } | undefined)?.output_tokens;
 
   // A safety/decline refusal (stop_reason "refusal") is a journaled DECLINE — not
   // a crash, and not a real answer. Classify it FIRST, before the is_error/subtype
@@ -33,14 +36,14 @@ export function parseClaudeResult(raw: unknown): AgentResult {
       ok: false,
       kind: "refusal",
       stderr: `refusal${category ? `(${category})` : ""}: ${detail}`.trim(),
-      meta: { durationMs },
+      meta: { durationMs, outputTokens },
     };
   }
 
   if (!j || j.type !== "result" || j.is_error === true || j.subtype !== "success") {
     const subtype = (j?.subtype ?? j?.type ?? "unknown") as string;
     const detail = typeof j?.result === "string" ? j.result : "";
-    return { ok: false, kind: "nonzero_exit", stderr: `${subtype}: ${detail}`.trim(), meta: { durationMs } };
+    return { ok: false, kind: "nonzero_exit", stderr: `${subtype}: ${detail}`.trim(), meta: { durationMs, outputTokens } };
   }
 
   return {
@@ -50,6 +53,7 @@ export function parseClaudeResult(raw: unknown): AgentResult {
       durationMs,
       sessionId: j.session_id as string | undefined,
       costUsd: j.total_cost_usd as number | undefined,
+      outputTokens,
     },
   };
 }
@@ -64,6 +68,9 @@ export type ClaudeAdapterDeps = {
   spawn?: ClaudeSpawn;
   /** Binary name/path; defaults to "claude" on PATH. */
   bin?: string;
+  /** Diagnostic sink for honest-scope notices (e.g. an opt with no faithful CLI
+   *  flag was dropped). Defaults to console.error. */
+  warn?: (msg: string) => void;
 };
 
 /** Default spawn over Bun.spawn. Kills the child after timeoutMs and flags it so
@@ -95,6 +102,15 @@ function defaultSpawn(bin: string): ClaudeSpawn {
 
 export function makeClaudeAdapter(deps: ClaudeAdapterDeps = {}): AgentPort {
   const spawn = deps.spawn ?? defaultSpawn(deps.bin ?? "claude");
+  const warn = deps.warn ?? ((m: string) => console.error(m));
+  // One-time per field: claude -p has no faithful flag for these yet, so they are
+  // dropped rather than silently honored. Warn once so a fan-out isn't spammed.
+  const warnedFields = new Set<string>();
+  const warnUnmapped = (field: string, value: unknown) => {
+    if (warnedFields.has(field)) return;
+    warnedFields.add(field);
+    warn(`omw(claude): \`${field}\` (=${String(value)}) has no claude -p flag; dropped for this run.`);
+  };
 
   async function run(args: string[], cwd?: string, timeoutMs?: number): Promise<AgentResult> {
     let res: ClaudeSpawnResult;
@@ -136,11 +152,21 @@ export function makeClaudeAdapter(deps: ClaudeAdapterDeps = {}): AgentPort {
     invoke(req: InvokeRequest): Promise<AgentResult> {
       const args = ["-p", req.prompt, "--output-format", "json"];
       if (req.model) args.push("--model", req.model);
+      if (req.effort !== undefined) warnUnmapped("effort", req.effort);
+      if (req.agentType !== undefined) warnUnmapped("agentType", req.agentType);
+      // Isolate the node from the host's MCP servers unless asked otherwise:
+      // booting figma/devtools/etc. on every node is the dominant fan-out latency.
+      if (!req.inheritMcp) args.push("--strict-mcp-config");
       return run(args, req.cwd, req.timeoutMs);
     },
-    followUp(sessionId: string, prompt: string): Promise<AgentResult> {
+    // `cwd` must match the original invoke — claude keys session history by
+    // project directory, so resuming elsewhere yields "No conversation found".
+    // MCP isolation must mirror the original invoke so the resume turn sees the
+    // same environment as the turn it continues.
+    followUp(sessionId: string, prompt: string, opts?: FollowUpOpts): Promise<AgentResult> {
       const args = ["-p", prompt, "--resume", sessionId, "--output-format", "json"];
-      return run(args);
+      if (!opts?.inheritMcp) args.push("--strict-mcp-config");
+      return run(args, opts?.cwd, opts?.timeoutMs);
     },
   };
 }

package/src/adapters/codex.ts

@@ -11,7 +11,7 @@
 // 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 { AgentPort, AgentResult, FollowUpOpts, 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));
@@ -141,9 +141,11 @@ export function makeCodexAdapter(deps: CodexAdapterDeps = {}): AgentPort {
       args.push(req.prompt);
       return run(args, req.cwd, req.timeoutMs);
     },
-    followUp(sessionId: string, prompt: string): Promise<AgentResult> {
+    // `cwd` must match the original invoke so resume finds the session.
+    // (MCP isolation / inheritMcp is not yet implemented for codex.)
+    followUp(sessionId: string, prompt: string, opts?: FollowUpOpts): Promise<AgentResult> {
       const args = ["exec", "resume", sessionId, "--json", "-s", sandbox, prompt];
-      return run(args);
+      return run(args, opts?.cwd, opts?.timeoutMs);
     },
   };
 }

package/src/adapters/exec.ts

@@ -0,0 +1,103 @@
+// Config-driven adapter for the simple "prompt in → response text out" coding-agent
+// CLI shape. Every adapter repeats the same spawn / timeout / exit-code / parse
+// boilerplate; this collapses it so a plain one-shot CLI is a few lines of config
+// instead of a hand-written ~100-line file.
+//
+// Use a dedicated adapter (claude.ts, codex.ts) when a CLI has real quirks the
+// generic shape can't carry: a JSON/JSONL envelope, in-session resume (`followUp`,
+// which the schema gate uses for self-repair), a distinct refusal signal, or a
+// cost field. This generic adapter has NO followUp on purpose — a config-only CLI
+// that prints plain text has no session id to resume, so the schema gate falls
+// back to fresh invokes (the documented no-followUp path).
+
+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 type ExecAdapterConfig = {
+  /** Adapter name, surfaced as AgentResult source + in resolveAdapter. */
+  name: string;
+  /** Default binary; overridable via deps.bin. */
+  bin: string;
+  /** Build the args (after the bin) from the request. */
+  argv: (req: { prompt: string; model?: string }) => string[];
+  /** Turn stdout into the response text. Default: trimmed stdout. Returning an
+   *  empty string is treated as "no output" (a terminal failure). */
+  parse?: (stdout: string) => string;
+};
+
+export type ExecAdapterDeps = {
+  spawn?: Spawn;
+  /** Binary name/path; defaults to the config's `bin`. */
+  bin?: string;
+};
+
+/** Shared spawn boilerplate (Bun.spawn + timeout kill + stdout/stderr capture).
+ *  Exported so simple adapters reuse it instead of re-implementing it. */
+export function defaultExecSpawn(bin: string): Spawn {
+  return async (args, opts) => {
+    const proc = Bun.spawn([bin, ...args], {
+      cwd: opts?.cwd,
+      stdin: "ignore", // one-shot mode; don't block waiting on stdin
+      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 };
+  };
+}
+
+/** Map a spawn result onto AgentResult for a plain-text CLI: parsed stdout IS the
+ *  response. A timeout, non-zero exit, or empty parse is a terminal failure (no
+ *  distinct refusal signal — a soft decline arrives as normal text). */
+export function parseExecResult(res: SpawnResult, parse: (s: string) => string, name: string): AgentResult {
+  if (res.timedOut) {
+    return { ok: false, kind: "timeout", stderr: res.stderr || `${name} timed out`, meta: { durationMs: 0 } };
+  }
+  const text = parse(res.stdout).trim();
+  if (res.code !== 0) {
+    return {
+      ok: false,
+      kind: "nonzero_exit",
+      stderr: res.stderr || text || `${name} exited ${res.code}`,
+      meta: { durationMs: 0 },
+    };
+  }
+  if (!text) {
+    return { ok: false, kind: "nonzero_exit", stderr: res.stderr || `${name} produced no output`, meta: { durationMs: 0 } };
+  }
+  return { ok: true, text, meta: { durationMs: 0 } };
+}
+
+export function makeExecAdapter(config: ExecAdapterConfig, deps: ExecAdapterDeps = {}): AgentPort {
+  const spawn = deps.spawn ?? defaultExecSpawn(deps.bin ?? config.bin);
+  const parse = config.parse ?? ((s: string) => s);
+
+  return {
+    name: config.name,
+    async invoke(req: InvokeRequest): Promise<AgentResult> {
+      let res: SpawnResult;
+      try {
+        res = await spawn(config.argv({ prompt: req.prompt, model: req.model }), { cwd: req.cwd, timeoutMs: req.timeoutMs });
+      } catch (e) {
+        return { ok: false, kind: "spawn_failure", stderr: errMsg(e), meta: { durationMs: 0 } };
+      }
+      return parseExecResult(res, parse, config.name);
+    },
+    // No followUp: a plain-text CLI has no session id to resume — see header.
+  };
+}

package/src/adapters/fake.ts

@@ -7,8 +7,8 @@
 import type { AgentPort, AgentResult, AgentFailureKind, InvokeRequest } from "./types";
 
 export type FakeResponse =
-  | { text: string; sessionId?: string; costUsd?: number }
-  | { fail: AgentFailureKind; stderr?: string };
+  | { text: string; sessionId?: string; costUsd?: number; outputTokens?: number }
+  | { fail: AgentFailureKind; stderr?: string; outputTokens?: number };
 
 export type FakeRule = {
   match: (prompt: string) => boolean;
@@ -23,12 +23,12 @@ export type FakeAdapterOptions = {
 
 function toResult(r: FakeResponse, durationMs: number): AgentResult {
   if ("fail" in r) {
-    return { ok: false, kind: r.fail, stderr: r.stderr, meta: { durationMs } };
+    return { ok: false, kind: r.fail, stderr: r.stderr, meta: { durationMs, outputTokens: r.outputTokens } };
   }
   return {
     ok: true,
     text: r.text,
-    meta: { durationMs, sessionId: r.sessionId, costUsd: r.costUsd },
+    meta: { durationMs, sessionId: r.sessionId, costUsd: r.costUsd, outputTokens: r.outputTokens },
   };
 }
 

package/src/adapters/hermes.ts

@@ -0,0 +1,24 @@
+// The hermes adapter (EXPERIMENTAL) — now just a config over the generic
+// exec-adapter (src/adapters/exec.ts). `hermes -z/--oneshot <prompt>` prints ONLY
+// the agent's final response text to stdout, so stdout IS the result (omw's
+// schema gate extracts JSON from it when a `schema` is set). `--yolo` runs the
+// node non-interactively. No in-session followUp (no session id on stdout) → the
+// schema gate falls back to fresh invokes. No cost field.
+
+import type { AgentPort } from "./types";
+import { makeExecAdapter, type ExecAdapterConfig, type ExecAdapterDeps } from "./exec";
+
+export const hermesExec: ExecAdapterConfig = {
+  name: "hermes",
+  bin: "hermes",
+  // `--yolo` so a headless node isn't blocked on tool-confirmation prompts.
+  argv: ({ prompt, model }) => {
+    const args = ["-z", prompt, "--yolo"];
+    if (model) args.push("-m", model);
+    return args;
+  },
+};
+
+export function makeHermesAdapter(deps: ExecAdapterDeps = {}): AgentPort {
+  return makeExecAdapter(hermesExec, deps);
+}

package/src/adapters/types.ts

@@ -17,13 +17,19 @@ export type AgentResult =
         /** Present when the adapter supports session resume (claude --resume). */
         sessionId?: string;
         costUsd?: number;
+        /** Output tokens this node produced, when the adapter reports them.
+         *  Feeds budget accounting (the shared spend counter). */
+        outputTokens?: number;
       };
     }
   | {
       ok: false;
       kind: AgentFailureKind;
       stderr?: string;
-      meta?: { durationMs: number };
+      /** A failure can still report tokens (an error/refusal envelope often
+       *  carries `usage`), so budget accounting counts it. A token-less failure
+       *  (e.g. a killed timeout) simply omits it. */
+      meta?: { durationMs: number; outputTokens?: number };
     };
 
 export type InvokeRequest = {
@@ -32,12 +38,36 @@ export type InvokeRequest = {
   model?: string;
   cwd?: string;
   timeoutMs?: number;
+  /** When true, the node inherits the ambient MCP configuration the CLI would
+   *  normally discover — user/global servers AND the cwd's project `.mcp.json`.
+   *  Default false → the node runs isolated: booting those servers on every node
+   *  is the dominant per-node latency in a fan-out, and inheriting them makes a
+   *  workflow non-reproducible (it behaves differently per machine). A coding-agent
+   *  node rarely needs them. Honored by the claude adapter (--strict-mcp-config);
+   *  the codex adapter does not yet implement isolation, so it is a no-op there. */
+  inheritMcp?: boolean;
+  /** Reasoning-effort hint, passed through to adapters that support it. Adapters
+   *  with no faithful flag (e.g. claude -p today) drop it and warn once. */
+  effort?: "low" | "medium" | "high" | "xhigh" | "max";
+  /** Cross-vendor node profile (a named agent persona). Adapters map it where
+   *  they can; otherwise drop + warn once (honest-scope). */
+  agentType?: string;
 };
 
+/** The subset of InvokeRequest a resume turn must mirror from its original
+ *  invoke so the repair runs in the same environment and obeys the same bounds. */
+export type FollowUpOpts = Pick<InvokeRequest, "cwd" | "inheritMcp" | "timeoutMs">;
+
 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>;
+   *  re-invokes fresh with the error feedback appended to the prompt.
+   *  `opts.cwd` MUST match the original invoke: claude scopes conversation history
+   *  by project directory, so resuming from a different cwd fails to find the
+   *  session ("No conversation found"). `opts.inheritMcp` must mirror the
+   *  original invoke so the resume turn sees the same MCP environment.
+   *  `opts.timeoutMs` must mirror the original invoke so a schema-repair resume
+   *  turn cannot hang longer than the node it is repairing. */
+  followUp?(sessionId: string, prompt: string, opts?: FollowUpOpts): Promise<AgentResult>;
 };

package/src/cli/codemod.ts

@@ -0,0 +1,99 @@
+// `omw codemod <file> [--to-di|--to-omw] [--write]` — mechanical source rewrites
+// for the 0.4→0.5 migration. `--to-di` (default) converts a legacy positional
+// `(rt, args)` workflow to the destructured-DI surface; `--to-omw` (planned)
+// will wrap a native ambient-global script into an omw default export.
+//
+// These are TEXT transforms on a file the engineer passes — best-effort, printed
+// for review (or written back with --write), never run. A regex codemod can't
+// see through aliasing, so the output is a starting point an author confirms.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import type { Io } from "./run";
+
+const HOOKS = "{ agent, parallel, pipeline, phase, log, workflow, budget }";
+
+export type Transform = "to-di" | "to-omw";
+
+export type CodemodResult = { ok: true; output: string; changed: boolean } | { ok: false; error: string };
+
+/** Rewrite a legacy `(rt, args)` default-export workflow to destructured DI:
+ *  the first param `rt` becomes the hooks object, and `rt.agent(...)` etc. become
+ *  bare `agent(...)`. Handles `function` and arrow default exports. */
+export function toDi(src: string): CodemodResult {
+  const fnRe = /(export\s+default\s+(?:async\s+)?function\s*\*?\s*)\(\s*rt\b\s*(,\s*[^)]*)?\)/;
+  const arrowRe = /(export\s+default\s+(?:async\s+)?)\(\s*rt\b\s*(,\s*[^)]*)?\)\s*=>/;
+
+  let out = src;
+  let matched = false;
+  if (fnRe.test(out)) {
+    out = out.replace(fnRe, (_m, pre, rest) => `${pre}(${HOOKS}${rest ?? ""})`);
+    matched = true;
+  } else if (arrowRe.test(out)) {
+    out = out.replace(arrowRe, (_m, pre, rest) => `${pre}(${HOOKS}${rest ?? ""}) =>`);
+    matched = true;
+  }
+
+  if (!matched) {
+    return { ok: false, error: "no legacy `(rt, args)` default export found (already destructured-DI?)" };
+  }
+  // Drop the `rt.` qualifier so hook calls reference the destructured names.
+  out = out.replace(/\brt\./g, "");
+  return { ok: true, output: out, changed: out !== src };
+}
+
+export type CodemodParse =
+  | { ok: true; value: { file: string; transform: Transform; write: boolean } }
+  | { ok: false; error: string };
+
+export function parseCodemodArgs(argv: string[]): CodemodParse {
+  let file: string | undefined;
+  let transform: Transform = "to-di";
+  let write = false;
+  for (const tok of argv) {
+    if (tok === "--to-di") transform = "to-di";
+    else if (tok === "--to-omw") transform = "to-omw";
+    else if (tok === "--write") write = true;
+    else if (file === undefined) file = tok;
+    else return { ok: false, error: `unexpected argument: ${tok}` };
+  }
+  if (file === undefined) return { ok: false, error: "missing file path" };
+  return { ok: true, value: { file, transform, write } };
+}
+
+/** Exit 0 on a successful transform, 1 on a transform/read error, 2 on usage. */
+export async function codemodCommand(argv: string[], io: Io): Promise<number> {
+  const parsed = parseCodemodArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(JSON.stringify({ error: "usage", message: parsed.error }) + "\n");
+    io.stderr("usage: omw codemod <file> [--to-di|--to-omw] [--write]\n");
+    return 2;
+  }
+  const { file, transform, write } = parsed.value;
+
+  if (transform === "to-omw") {
+    io.stderr(JSON.stringify({ error: "not_implemented", message: "--to-omw is not implemented yet; use --to-di" }) + "\n");
+    return 1;
+  }
+
+  let src: string;
+  try {
+    src = readFileSync(file, "utf8");
+  } catch {
+    io.stderr(JSON.stringify({ error: "read_failed", path: file }) + "\n");
+    return 1;
+  }
+
+  const result = toDi(src);
+  if (!result.ok) {
+    io.stderr(JSON.stringify({ error: "transform_failed", message: result.error, path: file }) + "\n");
+    return 1;
+  }
+
+  if (write) {
+    writeFileSync(file, result.output);
+    io.stderr(`✓ ${file} — rewrote to destructured DI\n`);
+  } else {
+    io.stdout(result.output);
+  }
+  return 0;
+}

package/src/cli/omw.ts

@@ -7,6 +7,7 @@ import { runCommand } from "./run";
 import { replayCommand } from "./replay";
 import { validateCommand } from "./validate";
 import { skillCommand } from "./skill";
+import { codemodCommand } from "./codemod";
 
 const io = {
   stdout: (s: string) => process.stdout.write(s),
@@ -24,14 +25,18 @@ async function main(argv: string[]): Promise<number> {
       return validateCommand(rest, io);
     case "skill":
       return skillCommand(rest, io);
+    case "codemod":
+      return codemodCommand(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" +
+          "  run <workflow> [--agent <auto|fake|claude|codex|hermes|pi>] [--args JSON] [--concurrency N] [--budget N] [--resume <journal|runId>] [--strict] [--pretty]\n" +
           "  replay <journal.jsonl> [--json]\n" +
           "  validate <workflow> [--json]\n" +
-          "  skill install [--project]   install the omw authoring skill for your coding agent\n\n" +
+          "  skill install [--project]   install the omw authoring skill for your coding agent\n" +
+          "  codemod <file> [--to-di] [--write]   migrate a legacy (rt, args) workflow to destructured DI\n\n" +
+          "agent-authored workflow:  omw run .omw/workflows/task.ts\n" +
           "free demo (no API key):  omw run examples/deep-research --agent fake\n",
       );
       return cmd === undefined ? 2 : 2;