oh-my-workflow 0.2.0 → 0.4.0

package/src/cli/run.ts

@@ -1,15 +1,17 @@
-// `omw run <wf> --agent <a> [--args JSON] [--concurrency N] [--pretty]`.
+// `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 { randomUUID } from "node:crypto";
 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 { makeHermesAdapter } from "../adapters/hermes";
+import type { Runtime, WorkflowMeta } from "../runtime";
 import { makeRuntime } from "../runtime";
 import { makeJournal, parseJournalLines, type JournalEvent } from "../journal";
 import type { ResumeIndex } from "../resume";
@@ -23,6 +25,12 @@ export type RunOptions = {
   pretty: boolean;
   /** Path to a prior run's journal to resume from (longest-unchanged-prefix). */
   resume?: string;
+  /** Opt-in determinism sandbox: forbid Date/Math.random in the script body so a
+   *  run is reproducible (matches native dynamic-workflow's freeze-throw). */
+  strict?: boolean;
+  /** Token ceiling for the whole run; agent() throws BudgetExceededError once the
+   *  shared spend reaches it. */
+  budget?: number;
 };
 
 export type ParseResult =
@@ -36,6 +44,8 @@ export function parseRunArgs(argv: string[]): ParseResult {
   let concurrency: number | undefined;
   let pretty = false;
   let resume: string | undefined;
+  let budget: number | undefined;
+  let strict = false;
 
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i]!;
@@ -61,9 +71,21 @@ export function parseRunArgs(argv: string[]): ParseResult {
         concurrency = n;
         break;
       }
+      case "--budget": {
+        const raw = argv[++i];
+        const n = Number(raw);
+        if (raw === undefined || !Number.isInteger(n) || n < 1) {
+          return { ok: false, error: `--budget must be a positive integer, got: ${raw}` };
+        }
+        budget = n;
+        break;
+      }
       case "--pretty":
         pretty = true;
         break;
+      case "--strict":
+        strict = true;
+        break;
       case "--resume":
         resume = argv[++i];
         if (!resume) return { ok: false, error: "--resume requires a journal path" };
@@ -75,9 +97,8 @@ export function parseRunArgs(argv: string[]): ParseResult {
   }
 
   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 } };
+  return { ok: true, value: { wfPath, agent: agent ?? "auto", args, concurrency, pretty, resume, budget, strict } };
 }
 
 // ── workflow execution ──────────────────────────────────────────────────────
@@ -88,6 +109,8 @@ export function parseRunArgs(argv: string[]): ParseResult {
 export type LoadedWorkflow = {
   workflow: (rt: Runtime, args: unknown) => unknown | Promise<unknown>;
   fake?: FakeAdapterOptions;
+  /** Optional `export const meta` describing the workflow (name/phases/model). */
+  meta?: WorkflowMeta;
 };
 
 /** Either a ready adapter, or a structured "not installed" signal (exit 3). */
@@ -145,9 +168,11 @@ export async function loadWorkflow(wfPath: string): Promise<LoadedWorkflow> {
 
   const mod = await import(entry);
   if (typeof mod.default !== "function") {
-    throw new Error(`workflow ${wfPath} must default-export a function (rt, args) => result`);
+    throw new Error(
+      `workflow ${wfPath} must default-export a function ({ agent, parallel, pipeline, phase, log, workflow, budget }, args) => result (legacy (rt, args) still supported)`,
+    );
   }
-  return { workflow: mod.default, fake: mod.fake };
+  return { workflow: mod.default, fake: mod.fake, meta: mod.meta };
 }
 
 export type RunDeps = {
@@ -175,6 +200,82 @@ export type RunOutcome = {
 
 const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
 
+/** True when a workflow's first param is NOT an object-destructuring pattern,
+ *  i.e. the legacy positional `(rt, args)` shape. Used only to emit a
+ *  deprecation nudge — never to dispatch, since the same object satisfies both
+ *  contracts. A source sniff via Function.prototype.toString; heuristic by
+ *  nature (it can't see through a bound/wrapped fn), but a non-fatal warning is
+ *  the right altitude for a heuristic. */
+function isLegacyShape(fn: Function): boolean {
+  const src = Function.prototype.toString.call(fn);
+  // New shape = first param is an object-destructuring pattern. Allow an optional
+  // function NAME between `function` and `(` (e.g. `function deepResearch({…})`),
+  // else a named destructured default export is misflagged as legacy.
+  return !/^\s*(async\s+)?function\s*\*?\s*[A-Za-z0-9_$]*\s*\(\s*\{|^\s*\(\s*\{|^\s*async\s*\(\s*\{/.test(src);
+}
+
+/** Run `fn` with Date/Math.random frozen to throw, restoring them after (even on
+ *  throw). Opt-in determinism: a `--strict` run fails loudly if the script reaches
+ *  for wall-clock or randomness, which would make a journal non-reproducible.
+ *  Scoped to the invoke and restored in finally — the engine's injected clock is
+ *  untouched, so journaling/resume still work. Mirrors native's freeze-throw. */
+// Reentrancy state for withStrict. The patch touches PROCESS-GLOBAL Date/
+// Math.random, so overlapping strict runs (nested workflow() or concurrent
+// runWorkflow callers in one process) must share a SINGLE install and restore
+// only when the last one unwinds. A naive per-call save/restore races: a second
+// caller would snapshot the already-patched StrictDate as its "original" and
+// restore it back, leaving the throwing clock installed forever. Depth-counting
+// with the true original captured once (at depth 0) closes that.
+let strictDepth = 0;
+let strictSavedDate: DateConstructor;
+let strictSavedRandom: () => number;
+
+async function withStrict<T>(strict: boolean | undefined, fn: () => T | Promise<T>): Promise<T> {
+  if (!strict) return await fn();
+  const entering = strictDepth === 0;
+  if (entering) {
+    // Snapshot the TRUE originals before any patch (a plain var write, can't throw).
+    strictSavedDate = globalThis.Date;
+    strictSavedRandom = Math.random;
+  }
+  // Increment and enter the try BEFORE patching, so a throw mid-patch (e.g. a
+  // frozen global) still hits finally and restores — no leaked StrictDate.
+  strictDepth++;
+  try {
+    if (entering) {
+      const boom = (what: string): never => {
+        throw new Error(`omw --strict: ${what} is forbidden in a deterministic workflow (pass values in via args)`);
+      };
+      class StrictDate extends strictSavedDate {
+        constructor(...args: any[]) {
+          if (args.length === 0) boom("new Date()");
+          super(...(args as [number]));
+        }
+        static now(): number {
+          return boom("Date.now()");
+        }
+      }
+      globalThis.Date = StrictDate as DateConstructor;
+      Math.random = () => boom("Math.random()");
+    }
+    return await fn();
+  } finally {
+    strictDepth--;
+    if (strictDepth === 0) {
+      // Restore each global independently: if one assignment throws (the global
+      // was frozen mid-run — the same hostile env this guards against), the other
+      // must still be restored, or a throwing patch leaks process-wide. Swallow
+      // the restore error so it can't mask fn()'s real result/error either.
+      try {
+        globalThis.Date = strictSavedDate;
+      } catch {}
+      try {
+        Math.random = strictSavedRandom;
+      } catch {}
+    }
+  }
+}
+
 export async function runWorkflow(opts: RunOptions, deps: RunDeps): Promise<RunOutcome> {
   let loaded: LoadedWorkflow;
   try {
@@ -193,11 +294,54 @@ export async function runWorkflow(opts: RunOptions, deps: RunDeps): Promise<RunO
 
   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 });
+  // One spend accumulator for the whole run: parent + any nested workflow()
+  // child point at it, so the token pool is shared (matches native).
+  const budgetState = { spent: 0 };
+  const rt = makeRuntime({
+    adapter: resolved.adapter,
+    journal,
+    concurrency: opts.concurrency,
+    resume: deps.resume,
+    budget: opts.budget,
+    budgetState,
+    meta: loaded.meta,
+  });
+
+  // workflow(ref, args?) runs another workflow inline as a sub-step, sharing the
+  // resolved adapter + journal + spend pool. One level only: a workflow() inside
+  // a child throws, so a runaway recursion can't hide behind the null-contract.
+  const makeWorkflowHook = (depth: number) =>
+    async (ref: string | { scriptPath: string }, childArgs?: unknown): Promise<unknown> => {
+      if (depth >= 1) throw new Error("workflow() nesting is one level only");
+      const childPath = typeof ref === "string" ? ref : ref.scriptPath;
+      const childLoaded = await deps.loadWorkflow(childPath);
+      const childRt = makeRuntime({
+        adapter: resolved.adapter,
+        journal,
+        concurrency: opts.concurrency,
+        resume: deps.resume,
+        budget: opts.budget,
+        budgetState,
+        meta: childLoaded.meta,
+      });
+      const childHooks = { ...childRt, workflow: makeWorkflowHook(depth + 1) };
+      return await childLoaded.workflow(childHooks as unknown as Runtime, childArgs);
+    };
 
   journal.runStart({ run: runId, wf: opts.wfPath });
   try {
-    const result = await loaded.workflow(rt, opts.args);
+    // The SAME runtime object satisfies both authoring contracts: a legacy
+    // `(rt, args)` script reads `rt.agent`, a new `({ agent }, args)` script
+    // destructures it. No execution-time dispatch — only the deprecation nudge
+    // needs to detect the legacy positional shape. `workflow` is layered on here
+    // (not in makeRuntime) since nesting needs the loader + resolved adapter.
+    const hooks = { ...rt, workflow: makeWorkflowHook(0) };
+    if (isLegacyShape(loaded.workflow)) {
+      deps.stderr?.(
+        "omw: deprecation — positional `rt` authoring is deprecated; destructure hooks `({ agent, ... }, args)`. Removed in 0.5. Run `omw codemod`.\n",
+      );
+    }
+    const result = await withStrict(opts.strict, () => loaded.workflow(hooks, 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
@@ -234,18 +378,72 @@ export async function runWorkflow(opts: RunOptions, deps: RunDeps): Promise<RunO
 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)",
+  hermes: "install the Hermes Agent CLI, then `hermes login`  (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;
+const AUTO_ADAPTERS = ["claude", "codex", "hermes"] as const;
+
+function unique<T>(items: T[]): T[] {
+  return [...new Set(items)];
+}
+
+function autoCandidates(env: Record<string, string | undefined>): string[] {
+  const explicit = env.OMW_AGENT?.trim().toLowerCase();
+  if (explicit && explicit !== "auto") return [explicit];
+
+  const keys = new Set(Object.keys(env).map((k) => k.toUpperCase()));
+  const hostHints: string[] = [];
+  if (keys.has("CLAUDECODE") || keys.has("CLAUDE_CODE") || keys.has("CLAUDE_CODE_ENTRYPOINT")) {
+    hostHints.push("claude");
+  }
+  if (keys.has("CODEX_SANDBOX") || keys.has("CODEX_CLI") || keys.has("OPENAI_CODEX")) {
+    hostHints.push("codex");
+  }
+  if (keys.has("HERMES") || keys.has("HERMES_CLI")) {
+    hostHints.push("hermes");
+  }
+
+  return unique([...hostHints, ...AUTO_ADAPTERS]);
+}
+
+function makeNamedAdapter(name: string, wf: LoadedWorkflow): AgentPort | undefined {
+  if (name === "fake") return makeFakeAdapter(wf.fake);
+  if (name === "claude") return makeClaudeAdapter();
+  if (name === "codex") return makeCodexAdapter();
+  if (name === "hermes") return makeHermesAdapter();
+  return undefined;
+}
 
 export function resolveAdapter(
   name: string,
   wf: LoadedWorkflow,
   binExists: (bin: string) => boolean = defaultBinExists,
+  env: Record<string, string | undefined> = process.env,
 ): AdapterResolution {
   if (name === "fake") return { adapter: makeFakeAdapter(wf.fake) };
+  if (name === "auto") {
+    const candidates = autoCandidates(env);
+    for (const candidate of candidates) {
+      const adapter = makeNamedAdapter(candidate, wf);
+      if (candidate === "fake" && adapter) return { adapter };
+      if (adapter && binExists(candidate)) return { adapter };
+    }
+    const explicit = env.OMW_AGENT?.trim().toLowerCase();
+    if (explicit && explicit !== "auto") {
+      return {
+        missing: explicit,
+        installHint: INSTALL_HINTS[explicit] ?? `unknown adapter "${explicit}". Set OMW_AGENT to claude, codex, or hermes.`,
+      };
+    }
+    return {
+      missing: "auto",
+      installHint:
+        "could not auto-detect an installed coding-agent CLI. Install claude/codex/hermes, set OMW_AGENT=claude|codex|hermes, or pass --agent fake for the no-key demo.",
+    };
+  }
   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.
@@ -256,6 +454,10 @@ export function resolveAdapter(
     if (!binExists("codex")) return { missing: "codex", installHint: INSTALL_HINTS.codex! };
     return { adapter: makeCodexAdapter() };
   }
+  if (name === "hermes") {
+    if (!binExists("hermes")) return { missing: "hermes", installHint: INSTALL_HINTS.hermes! };
+    return { adapter: makeHermesAdapter() };
+  }
   // pi lands here as it is built; until then, fail actionably.
   return {
     missing: name,
@@ -273,7 +475,7 @@ export type Io = {
   runId?: () => string;
 };
 
-const defaultRunId = (): string => "r-" + Date.now().toString(36);
+const defaultRunId = (): string => `r-${Date.now().toString(36)}-${process.pid.toString(36)}-${randomUUID().slice(0, 8)}`;
 
 /** 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
@@ -283,7 +485,7 @@ export async function runCommand(argv: string[], io: Io): Promise<number> {
   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]",
+      "\nusage: omw run <workflow> [--agent <auto|fake|claude|codex|hermes|pi>] [--args JSON] [--concurrency N] [--budget N] [--resume <journal|runId>] [--strict] [--pretty]",
     );
     return 2;
   }
@@ -296,11 +498,17 @@ export async function runCommand(argv: string[], io: Io): Promise<number> {
   // unreadable --resume path is a user error, not a reason to silently run live).
   let resume: ResumeIndex | undefined;
   if (parsed.value.resume) {
+    // Accept either a journal path or a bare runId: if the arg isn't an existing
+    // file, treat it as a runId and resolve <omwDir>/<runId>.jsonl (the path the
+    // run wrote its journal to). Lets `--resume <runId>` mirror the runId printed
+    // on the prior run without the caller reconstructing the path.
+    const resumeArg = parsed.value.resume;
+    const resumePath = existsSync(resumeArg) ? resumeArg : join(omwDir, `${resumeArg}.jsonl`);
     let lines: string[];
     try {
-      lines = readFileSync(parsed.value.resume, "utf8").split("\n");
+      lines = readFileSync(resumePath, "utf8").split("\n");
     } catch {
-      io.stderr(JSON.stringify({ error: "resume_read_failed", path: parsed.value.resume }) + "\n");
+      io.stderr(JSON.stringify({ error: "resume_read_failed", path: resumePath }) + "\n");
       return 1;
     }
     resume = makeResumeIndexFromLines(lines);
@@ -308,7 +516,7 @@ export async function runCommand(argv: string[], io: Io): Promise<number> {
       // 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");
+      io.stderr(JSON.stringify({ warning: "resume_empty", path: resumePath }) + "\n");
     }
   }
 
@@ -326,6 +534,7 @@ export async function runCommand(argv: string[], io: Io): Promise<number> {
     now: () => Date.now(),
     runId: () => runId,
     resume,
+    stderr: io.stderr, // surface the legacy-authoring deprecation nudge to the user
   });
 
   if (outcome.stdout !== undefined) io.stdout(outcome.stdout + "\n");

package/src/cli/skill.ts

@@ -15,7 +15,7 @@ import { fileURLToPath } from "node:url";
 /** Package root, so the bundled skill resolves whether omw runs from a clone or
  *  an npm install invoked from any cwd. (Same technique as run.ts's PKG_ROOT.) */
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const SKILL_NAME = "oh-my-workflow";
+const SKILL_NAME = "omw";
 
 export type SkillIo = {
   stdout: (s: string) => void;
@@ -27,8 +27,10 @@ export type SkillIo = {
   skillDir?: string;
 };
 
+export type SkillAgent = "claude" | "codex" | "opencode";
+
 export type SkillParse =
-  | { ok: true; sub: "install"; project: boolean }
+  | { ok: true; sub: "install"; project: boolean; agent: SkillAgent }
   | { ok: true; sub: "path" }
   | { ok: true; sub: "help" }
   | { ok: false; error: string };
@@ -36,8 +38,11 @@ export type SkillParse =
 const USAGE =
   "usage: omw skill <command>\n\n" +
   "commands:\n" +
-  "  install [--project]   copy the skill into a skills dir so a coding agent picks it up\n" +
-  "                        (default: ~/.claude/skills/oh-my-workflow; --project: ./.claude/skills/…)\n" +
+  "  install [--project] [--codex|--opencode]\n" +
+  "                        copy the skill into a coding agent's skills dir so it's picked up\n" +
+  "                        (default agent: claude → ~/.claude/skills/omw;\n" +
+  "                         --codex → ~/.codex/skills/…; --opencode → ~/.config/opencode/skills/…;\n" +
+  "                         --project targets the cwd instead of home)\n" +
   "  path                  print the bundled SKILL.md path (for cat / piping / pointing an agent at it)\n";
 
 export function parseSkillArgs(argv: string[]): SkillParse {
@@ -51,15 +56,31 @@ export function parseSkillArgs(argv: string[]): SkillParse {
   }
   if (sub === "install") {
     let project = false;
+    let agent: SkillAgent = "claude";
     for (const tok of rest) {
       if (tok === "--project") project = true;
+      else if (tok === "--codex") agent = "codex";
+      else if (tok === "--opencode") agent = "opencode";
       else return { ok: false, error: `unexpected argument: ${tok}` };
     }
-    return { ok: true, sub: "install", project };
+    return { ok: true, sub: "install", project, agent };
   }
   return { ok: false, error: `unknown skill subcommand: ${sub}` };
 }
 
+/** Per-agent destination for the skill, each a DISTINCT dir so a clean-replace
+ *  install never wipes a sibling agent's copy. */
+function skillDest(agent: SkillAgent, root: string): { destDir: string; discovers: string } {
+  switch (agent) {
+    case "codex":
+      return { destDir: join(root, ".codex", "skills", SKILL_NAME), discovers: "Codex" };
+    case "opencode":
+      return { destDir: join(root, ".config", "opencode", "skills", SKILL_NAME), discovers: "opencode" };
+    case "claude":
+      return { destDir: join(root, ".claude", "skills", SKILL_NAME), discovers: "Claude Code" };
+  }
+}
+
 export async function skillCommand(argv: string[], io: SkillIo): Promise<number> {
   const parsed = parseSkillArgs(argv);
   if (!parsed.ok) {
@@ -84,9 +105,10 @@ export async function skillCommand(argv: string[], io: SkillIo): Promise<number>
   }
 
   // install — idempotent: copy the whole skill dir (SKILL.md + any bundled
-  // resources) in place, and report installed vs updated.
-  const base = parsed.project ? join(io.cwd ?? process.cwd(), ".claude") : join(io.homeDir ?? homedir(), ".claude");
-  const destDir = join(base, "skills", SKILL_NAME);
+  // resources) in place, and report installed vs updated. The destination is
+  // per-agent and DISTINCT, so the clean-replace below never wipes a sibling.
+  const root = parsed.project ? (io.cwd ?? process.cwd()) : (io.homeDir ?? homedir());
+  const { destDir, discovers } = skillDest(parsed.agent, root);
   const dest = join(destDir, "SKILL.md");
   const updating = existsSync(dest);
   // Clean replace, not an additive copy: drop a prior install first so a file
@@ -97,8 +119,8 @@ export async function skillCommand(argv: string[], io: SkillIo): Promise<number>
 
   io.stdout(
     `${updating ? "updated" : "installed"} ${SKILL_NAME} skill → ${dest}\n` +
-      `${parsed.project ? "This project's" : "Claude Code"} agent auto-discovers skills here.\n` +
-      `Next: ask your coding agent to "use oh-my-workflow to <your task>".\n`,
+      `${parsed.project ? "This project's" : discovers} agent auto-discovers skills here.\n` +
+      `Next: ask your coding agent with "/omw <your task>".\n`,
   );
   return 0;
 }