oh-my-fable 0.1.1 → 0.2.0

package/README.md

@@ -128,8 +128,18 @@ console.log(result.ctx.plan.steps);
 npm i oh-my-fable        # zero runtime dependencies
 ```
 
-Node ≥ 18. The `AnthropicProvider` talks to the API over `fetch` — no SDK. Bring
-any model by implementing the `Provider` interface (three methods).
+Node ≥ 18. Ships with `AnthropicProvider` and `OpenAICompatProvider` (works with
+OpenAI, Ollama, LM Studio, OpenRouter, Groq… — `ollama("llama3.1")` for a local
+model with no key), both over `fetch`, no SDK. Or bring any model by implementing
+the `Provider` interface (three methods).
+
+`AnthropicProvider` works with the current flagship models (`claude-opus-4-8`,
+`claude-fable-5`) out of the box — it drops the `temperature` parameter they
+reject — and **prompt-caches the system+tools prefix by default**, so a long
+durable run pays ~10× less on the context it replays every step. Opt into
+`{ thinking: "adaptive", effort: "high" }` for harder planning. The `claude`
+provider can return real `--output-format json` cost/usage and run Claude's own
+tools (`{ tools: true, permissionMode: "acceptEdits" }`).
 
 ## Or use it from the terminal
 
@@ -138,18 +148,48 @@ Don't want to write code? It ships a CLI (zero extra deps):
 ```bash
 npx oh-my-fable demo                       # watch crash → resume, no API key
 
+# ⭐ already pay for Claude Code? drive it as a DURABLE, TOOL-USING agent — your
+#    login, no separate API key, $0 per token. Claude edits files & runs commands:
+npx oh-my-fable run "refactor utils.ts and run the tests" --provider claude --cli-tools
+
+# pure-reasoning over the same login (no tools):
+npx oh-my-fable run "outline a talk on durable agents" --provider claude
+
+# or a LOCAL model (Ollama / LM Studio), also no key:
+npx oh-my-fable run "outline a talk on durable agents" --provider ollama --model llama3.1
+
+# or any hosted model:
 export ANTHROPIC_API_KEY=sk-...
 npx oh-my-fable run "summarize README.md into SUMMARY.md" --tools fs
-npx oh-my-fable run "outline a talk on durable agents" --success "5 sections"
 
 npx oh-my-fable list                       # your saved runs
+npx oh-my-fable show  run_abc123           # the run's plan, steps & budget as a timeline
 npx oh-my-fable resume run_abc123          # continue one from its checkpoint
 ```
 
-You watch the plan form and each step get reflected on, live. `--tools fs` gives
-the agent a sandboxed `read_file`/`write_file`/`list_dir` (confined to the working
-directory) so a terminal run can actually produce files; without it, runs are
-pure-reasoning. Every run is checkpointed, so `resume <runId>` always works.
+**You don't need an Anthropic API key.** Pick how it talks to a model:
+
+| `--provider` | uses | key? | tools? |
+| --- | --- | --- | --- |
+| `claude` | your Claude Code login | **none** | `--cli-tools` → Claude runs Read/Write/Edit/Bash itself |
+| `codex` | your Codex CLI login | **none** | `--cli-tools` → workspace-write |
+| `ollama` | a local Ollama model | **none** | `--tools fs` (harness-run) |
+| `--base-url <url>` | LM Studio / OpenRouter / Groq / any OpenAI-compatible | per that server | `--tools fs` |
+| `openai` | OpenAI | `OPENAI_API_KEY` | `--tools fs` |
+| *(default)* | Anthropic | `ANTHROPIC_API_KEY` | `--tools fs` |
+
+**Two ways to give an agent hands:**
+
+- `--cli-tools` (claude/codex) — the CLI runs its **own** tools (file edits, shell)
+  on your subscription. oh-my-fable stays the durable planner/reflector around it:
+  it plans, checkpoints every step, and reflects — Claude does the work. Tune with
+  `--permission-mode acceptEdits|dontAsk|plan` and `--allow "Read,Edit,Bash(npm test)"`.
+- `--tools fs` (API providers) — the harness gives the agent a sandboxed
+  `read_file`/`write_file`/`list_dir`, confined to the working directory.
+
+You watch the plan form and each step get reflected on, live. Every run is
+checkpointed, so `resume <runId>` always works — and `show <runId>` prints the
+whole run (plan, steps, budget) from its serialized `RunContext`.
 
 ## Tools
 
@@ -217,7 +257,7 @@ architecture writeup is in [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
 ## Roadmap
 
-- A web dashboard that tails a run's events and lets you resume from any checkpoint.
+- A web dashboard that tails a run's events and lets you resume from any checkpoint (`show <runId>` is the CLI version of this today).
 - More providers in-repo (OpenAI-compatible, local) — though it's a 3-method interface.
 - Parallel step execution for independent branches of the plan DAG.
 - Human-in-the-loop: pause for approval as a first-class step status.

package/dist/cli.cjs

@@ -812,6 +812,10 @@ var reply = {
 };
 
 // src/providers/anthropic.ts
+function modelRejectsSampling(model) {
+  const m = model.toLowerCase();
+  return m.includes("opus-4-7") || m.includes("opus-4-8") || m.includes("fable") || m.includes("mythos");
+}
 function coalesce(messages) {
   const out = [];
   for (const m of messages) {
@@ -830,6 +834,9 @@ var AnthropicProvider = class {
   version;
   maxRetries;
   defaultMaxTokens;
+  cache;
+  thinking;
+  effort;
   constructor(opts = {}) {
     this.apiKey = opts.apiKey ?? process.env["ANTHROPIC_API_KEY"] ?? "";
     this.model = opts.model ?? "claude-sonnet-4-6";
@@ -837,6 +844,9 @@ var AnthropicProvider = class {
     this.version = opts.version ?? "2023-06-01";
     this.maxRetries = opts.maxRetries ?? 4;
     this.defaultMaxTokens = opts.defaultMaxTokens ?? 4096;
+    this.cache = opts.cache ?? true;
+    this.thinking = opts.thinking;
+    this.effort = opts.effort;
     if (!this.apiKey) {
       throw new Error("AnthropicProvider needs an API key (pass { apiKey } or set ANTHROPIC_API_KEY).");
     }
@@ -852,12 +862,18 @@ var AnthropicProvider = class {
     const body = {
       model: this.model,
       max_tokens: req.maxTokens ?? this.defaultMaxTokens,
-      temperature: req.temperature ?? 1,
       messages: convo
     };
+    if (typeof req.temperature === "number" && !this.thinking && !modelRejectsSampling(this.model)) {
+      body["temperature"] = req.temperature;
+    }
+    if (this.thinking === "adaptive") body["thinking"] = { type: "adaptive" };
+    if (this.effort) body["output_config"] = { effort: this.effort };
     let sys = system;
     if (req.responseFormat === "json") sys = (sys ? sys + "\n\n" : "") + "Output ONLY valid JSON. No prose, no code fences.";
-    if (sys) body["system"] = sys;
+    if (sys) {
+      body["system"] = this.cache ? [{ type: "text", text: sys, cache_control: { type: "ephemeral" } }] : sys;
+    }
     if (req.tools?.length) {
       body["tools"] = req.tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters }));
     }
@@ -894,17 +910,275 @@ var AnthropicProvider = class {
       if (block.type === "text" && block.text) content += block.text;
       else if (block.type === "tool_use" && block.name) toolCalls.push({ id: block.id ?? block.name, name: block.name, input: block.input });
     }
+    const u = data.usage ?? {};
+    const tokensIn = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
     const map = { end_turn: "end", tool_use: "tool_use", max_tokens: "max_tokens", stop_sequence: "end" };
     return {
       content,
       toolCalls: toolCalls.length ? toolCalls : void 0,
-      tokensIn: data.usage?.input_tokens ?? 0,
-      tokensOut: data.usage?.output_tokens ?? 0,
+      tokensIn,
+      tokensOut: u.output_tokens ?? 0,
       stopReason: map[data.stop_reason ?? ""] ?? "end"
     };
   }
 };
 
+// src/providers/openai.ts
+var FINISH = { stop: "end", tool_calls: "tool_use", function_call: "tool_use", length: "max_tokens" };
+var OpenAICompatProvider = class {
+  name;
+  baseUrl;
+  apiKey;
+  model;
+  maxRetries;
+  defaultMaxTokens;
+  constructor(opts) {
+    if (!opts.baseUrl) throw new Error("OpenAICompatProvider needs a baseUrl.");
+    if (!opts.model) throw new Error("OpenAICompatProvider needs a model.");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.model = opts.model;
+    this.name = opts.label ?? "openai-compatible";
+    this.maxRetries = opts.maxRetries ?? 4;
+    this.defaultMaxTokens = opts.defaultMaxTokens ?? 4096;
+  }
+  estimateTokens(messages) {
+    return estimateTokens(messages);
+  }
+  async complete(req) {
+    const body = {
+      model: this.model,
+      messages: req.messages.map((m) => ({ role: m.role, content: m.content })),
+      max_tokens: req.maxTokens ?? this.defaultMaxTokens,
+      temperature: req.temperature ?? 1
+    };
+    if (req.tools?.length) {
+      body["tools"] = req.tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters } }));
+    }
+    const data = await withRetry(
+      async () => {
+        const headers = { "content-type": "application/json" };
+        if (this.apiKey) headers["authorization"] = `Bearer ${this.apiKey}`;
+        const res = await fetch(`${this.baseUrl}/chat/completions`, { method: "POST", headers, body: JSON.stringify(body) });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          const err = new Error(`${this.name} ${res.status}: ${text.slice(0, 300)}`);
+          err.status = res.status;
+          throw err;
+        }
+        return await res.json();
+      },
+      {
+        retries: this.maxRetries,
+        isRetryable: (e) => {
+          const s = e.status;
+          return s === void 0 || s === 429 || s >= 500 && s < 600;
+        }
+      }
+    );
+    const choice = data.choices?.[0];
+    const content = typeof choice?.message?.content === "string" ? choice.message.content : "";
+    const toolCalls = [];
+    for (const tc of choice?.message?.tool_calls ?? []) {
+      if (!tc.function?.name) continue;
+      let input = {};
+      try {
+        input = tc.function.arguments ? JSON.parse(tc.function.arguments) : {};
+      } catch {
+        input = tc.function.arguments ?? {};
+      }
+      toolCalls.push({ id: tc.id ?? tc.function.name, name: tc.function.name, input });
+    }
+    return {
+      content,
+      toolCalls: toolCalls.length ? toolCalls : void 0,
+      tokensIn: data.usage?.prompt_tokens ?? 0,
+      tokensOut: data.usage?.completion_tokens ?? 0,
+      stopReason: FINISH[choice?.finish_reason ?? ""] ?? "end"
+    };
+  }
+};
+function ollama(model, opts = {}) {
+  return new OpenAICompatProvider({ baseUrl: "http://localhost:11434/v1", model, label: "ollama", ...opts });
+}
+
+// src/providers/cli.ts
+var import_node_child_process = require("child_process");
+function flatten(messages, includeSystem) {
+  const parts = [];
+  for (const m of messages) {
+    if (m.role === "system" && !includeSystem) continue;
+    if (m.role === "assistant") parts.push(`Assistant: ${m.content}`);
+    else parts.push(m.content);
+  }
+  return parts.join("\n\n");
+}
+function runCli(command, args, input, timeoutMs, env) {
+  return new Promise((resolve2, reject) => {
+    let child;
+    try {
+      child = (0, import_node_child_process.spawn)(command, args, { env: { ...process.env, ...env } });
+    } catch (e) {
+      return reject(e);
+    }
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`${command} timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+    child.stdout.on("data", (d) => out += d);
+    child.stderr.on("data", (d) => err += d);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e.code === "ENOENT" ? new Error(`"${command}" is not installed or not on your PATH.`) : e);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve2(out);
+      else reject(new Error(`${command} exited ${code}: ${err.trim().slice(0, 300)}`));
+    });
+    if (input !== null) child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+var CliProvider = class {
+  name;
+  command;
+  args;
+  promptVia;
+  parse;
+  env;
+  timeoutMs;
+  extraArgs;
+  requestArgs;
+  parseResult;
+  systemInPrompt;
+  constructor(opts) {
+    this.command = opts.command;
+    this.args = opts.args ?? [];
+    this.promptVia = opts.promptVia ?? "arg";
+    this.parse = opts.parse ?? ((s) => s.trim());
+    this.env = opts.env;
+    this.timeoutMs = opts.timeoutMs ?? 12e4;
+    this.name = opts.label ?? `cli:${opts.command}`;
+    this.extraArgs = opts.extraArgs ?? [];
+    this.requestArgs = opts.requestArgs;
+    this.parseResult = opts.parseResult;
+    this.systemInPrompt = opts.systemInPrompt ?? true;
+  }
+  estimateTokens(messages) {
+    return estimateTokens(messages);
+  }
+  async complete(req) {
+    const prompt = flatten(req.messages, this.systemInPrompt);
+    const reqArgs = this.requestArgs ? this.requestArgs(req) : [];
+    const argv = [...this.args, ...this.extraArgs, ...reqArgs];
+    const finalArgs = this.promptVia === "arg" ? [...argv, prompt] : argv;
+    const stdout = await runCli(this.command, finalArgs, this.promptVia === "stdin" ? prompt : null, this.timeoutMs, this.env);
+    if (this.parseResult) {
+      const r = this.parseResult(stdout);
+      const content2 = r.content ?? "";
+      return {
+        content: content2,
+        toolCalls: r.toolCalls,
+        tokensIn: r.tokensIn ?? estimateTokens(req.messages),
+        tokensOut: r.tokensOut ?? Math.ceil(content2.length / 4),
+        stopReason: r.stopReason ?? "end",
+        sessionId: r.sessionId,
+        costUsd: r.costUsd
+      };
+    }
+    const content = this.parse(stdout);
+    return {
+      content,
+      tokensIn: estimateTokens(req.messages),
+      tokensOut: Math.ceil(content.length / 4),
+      stopReason: "end"
+    };
+  }
+};
+var num = (x) => typeof x === "number" && Number.isFinite(x) ? x : 0;
+function parseClaudeJson(stdout) {
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    return { content: stdout.trim() };
+  }
+  let content;
+  if (data["structured_output"] !== void 0) {
+    const so = data["structured_output"];
+    content = typeof so === "string" ? so : JSON.stringify(so);
+  } else {
+    content = typeof data["result"] === "string" ? data["result"] : stdout.trim();
+  }
+  const usage = data["usage"] ?? {};
+  const tokensIn = num(usage["input_tokens"]) + num(usage["cache_read_input_tokens"]) + num(usage["cache_creation_input_tokens"]);
+  const tokensOut = num(usage["output_tokens"]);
+  const out = { content };
+  if (tokensIn) out.tokensIn = tokensIn;
+  if (tokensOut) out.tokensOut = tokensOut;
+  if (typeof data["session_id"] === "string") out.sessionId = data["session_id"];
+  if (typeof data["total_cost_usd"] === "number") out.costUsd = data["total_cost_usd"];
+  return out;
+}
+function claudeRequestArgs(req, opts) {
+  const args = [];
+  if (opts.json) args.push("--output-format", "json");
+  if (opts.appendSystem) {
+    let sys = req.messages.filter((m) => m.role === "system").map((m) => m.content).join("\n\n");
+    if (req.responseFormat === "json") sys = (sys ? sys + "\n\n" : "") + "Output ONLY valid JSON. No prose, no code fences.";
+    if (sys) args.push("--append-system-prompt", sys);
+  }
+  if (opts.jsonSchema && req.responseFormat === "json") args.push("--json-schema", JSON.stringify(opts.jsonSchema));
+  return args;
+}
+var DEFAULT_CLAUDE_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
+function claudeCode(opts = {}) {
+  const json = opts.json ?? true;
+  const appendSystem = opts.appendSystem ?? true;
+  const extra = [];
+  if (opts.model) extra.push("--model", opts.model);
+  if (opts.tools) {
+    const allow = Array.isArray(opts.tools) ? opts.tools : DEFAULT_CLAUDE_TOOLS;
+    extra.push("--allowedTools", allow.join(","), "--permission-mode", opts.permissionMode ?? "acceptEdits");
+  } else if (opts.permissionMode) {
+    extra.push("--permission-mode", opts.permissionMode);
+  }
+  for (const d of opts.addDirs ?? []) extra.push("--add-dir", d);
+  if (opts.resumeSessionId) extra.push("--resume", opts.resumeSessionId);
+  return new CliProvider({
+    command: "claude",
+    args: ["-p"],
+    promptVia: "arg",
+    label: "claude-code",
+    timeoutMs: opts.timeoutMs,
+    env: opts.env,
+    extraArgs: extra,
+    requestArgs: (req) => claudeRequestArgs(req, { json, appendSystem, jsonSchema: opts.jsonSchema }),
+    parseResult: json ? parseClaudeJson : void 0,
+    systemInPrompt: !appendSystem
+  });
+}
+function codexCli(opts = {}) {
+  const extra = [];
+  if (opts.model) extra.push("--model", opts.model);
+  const sandbox = opts.sandbox ?? (opts.tools ? "workspace-write" : void 0);
+  if (sandbox) extra.push("--sandbox", sandbox);
+  const approval = opts.approval ?? (opts.tools ? "never" : void 0);
+  if (approval) extra.push("--ask-for-approval", approval);
+  return new CliProvider({
+    command: "codex",
+    args: ["exec"],
+    promptVia: "arg",
+    label: "codex",
+    timeoutMs: opts.timeoutMs,
+    env: opts.env,
+    extraArgs: extra
+  });
+}
+
 // src/index.ts
 function buildDeps(config, serializable) {
   const provider = config.provider;
@@ -932,7 +1206,7 @@ async function runWith(ctx, config) {
 
 // src/cli.ts
 init_store();
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var useColor = process.stdout.isTTY && !process.env["NO_COLOR"];
 var c = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
 var cyan = c("36");
@@ -1006,10 +1280,31 @@ function renderer() {
   };
 }
 function makeProvider(flags) {
+  const str = (k) => typeof flags[k] === "string" ? flags[k] : void 0;
+  const model = str("model");
+  const provider = str("provider");
+  const baseUrl = str("base-url");
+  const apiKey = str("api-key");
+  const permissionMode = str("permission-mode");
+  const allowList = typeof flags["allow"] === "string" ? flags["allow"].split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  const cliTools = flags["cli-tools"] === true;
+  const toolsOpt = allowList ?? (cliTools ? true : void 0);
   try {
-    return new AnthropicProvider({ model: typeof flags["model"] === "string" ? flags["model"] : void 0 });
+    if (provider === "claude" || provider === "claude-code") return claudeCode({ model, tools: toolsOpt, permissionMode });
+    if (provider === "codex") return codexCli({ model, tools: cliTools || !!allowList });
+    if (provider === "ollama") return ollama(model ?? "llama3.1", baseUrl ? { baseUrl } : {});
+    if (provider === "openai") {
+      return new OpenAICompatProvider({ baseUrl: baseUrl ?? "https://api.openai.com/v1", apiKey: apiKey ?? process.env["OPENAI_API_KEY"], model: model ?? "gpt-4o-mini", label: "openai" });
+    }
+    if (baseUrl) {
+      if (!model) fail("--base-url needs --model too.");
+      return new OpenAICompatProvider({ baseUrl, apiKey: apiKey ?? process.env["OPENAI_API_KEY"], model });
+    }
+    return new AnthropicProvider({ model });
   } catch (err) {
-    fail(err.message + "\nSet ANTHROPIC_API_KEY, or run `oh-my-fable demo` (no key needed).");
+    fail(
+      err.message + "\n\nNo API key needed \u2014 pick one:\n  --provider claude                    (your Claude Code login)\n  --provider ollama --model llama3.1   (a local model)\nOr just watch the mechanics:  oh-my-fable demo"
+    );
   }
 }
 function commonConfig(flags, provider) {
@@ -1083,6 +1378,42 @@ async function cmdList(args) {
   }
   process.stdout.write("\n");
 }
+async function cmdShow(args) {
+  const runId = args._[0];
+  if (!runId) fail("Give a run id: oh-my-fable show <runId>   (see `oh-my-fable list`)");
+  const store = new FileStore(typeof args.flags["runs-dir"] === "string" ? args.flags["runs-dir"] : "runs");
+  const ctx = await store.load(runId);
+  if (!ctx) fail(`no run ${runId} \u2014 try \`oh-my-fable list\``);
+  const icon = { done: green("\u2714"), failed: red("\u2717"), running: yellow("\u25B6"), skipped: dim("\u2013"), pending: dim("\xB7") };
+  const p = ctx.plan;
+  const planColor = p.status === "done" ? green : p.status === "failed" ? red : yellow;
+  process.stdout.write(`
+  ${dim("\u2500\u2500 run")} ${mag(ctx.runId)} ${dim("\u2500\u2500")}
+`);
+  process.stdout.write(`  ${bold("goal")}  ${ctx.goal.description}
+`);
+  if (ctx.goal.successCriteria?.length) process.stdout.write(`  ${dim("done when")}  ${dim(ctx.goal.successCriteria.join("; "))}
+`);
+  process.stdout.write(`  ${bold("plan")}  ${planColor(p.status)} ${dim(`\xB7 rev ${p.revision} \xB7 ${p.steps.length} steps`)}
+
+`);
+  for (const s of p.steps) {
+    process.stdout.write(`  ${icon[s.status] ?? "\xB7"} ${s.intent}${s.attempts > 1 ? dim(`  \xD7${s.attempts}`) : ""}
+`);
+    if (s.result) process.stdout.write(`     ${dim("\u21B3 " + s.result.replace(/\s+/g, " ").slice(0, 120))}
+`);
+  }
+  const b = ctx.budget;
+  const mins = Math.max(0, Math.round((Date.parse(ctx.updatedAt) - Date.parse(ctx.createdAt)) / 6e4));
+  process.stdout.write(`
+  ${dim(`budget: ${b.steps} steps \xB7 ${b.tokens.toLocaleString()} tokens \xB7 ${b.replans} replans \xB7 ~${mins}m`)}
+`);
+  if (ctx.digests.length) process.stdout.write(`  ${dim(`compacted: ${ctx.digests.length} digest${ctx.digests.length === 1 ? "" : "s"}`)}
+`);
+  if (p.status !== "done") process.stdout.write(`  ${dim("resume:")} ${cyan(`oh-my-fable resume ${ctx.runId}`)}
+`);
+  process.stdout.write("\n");
+}
 async function cmdDemo() {
   const { MemoryStore: MemoryStore2 } = await Promise.resolve().then(() => (init_store(), store_exports));
   const store = new MemoryStore2();
@@ -1147,23 +1478,37 @@ function help() {
 ${bold("oh-my-fable")} ${dim("v" + VERSION)} \u2014 give an agent a goal; it plans, self-corrects, and survives crashes.
 
 ${bold("Usage")}
-  oh-my-fable run "<goal>"        run an agent on a goal (needs ANTHROPIC_API_KEY)
+  oh-my-fable run "<goal>"        run an agent on a goal
   oh-my-fable resume <runId>      continue a crashed/halted run from its checkpoint
+  oh-my-fable show <runId>        print a run's plan, steps, and budget as a timeline
   oh-my-fable list                list saved runs
   oh-my-fable demo                watch crash \u2192 resume, scripted (no API key)
 
+${bold("Model")} ${dim("\u2014 no API key needed; ride a CLI login you already have")}
+  --provider claude                         drive your Claude Code login \u2014 NO separate API key
+  --provider claude --cli-tools             \u2026and let Claude edit files / run tools itself (durable agent on your sub)
+  --provider codex  --cli-tools             drive your Codex login, workspace-write
+  --provider ollama --model llama3.1        a LOCAL model \u2014 no API key, no cost
+  --provider openai --model gpt-4o-mini     OpenAI (OPENAI_API_KEY)
+  --base-url <url> --model <id> [--api-key] any OpenAI-compatible server (LM Studio, OpenRouter, Groq, \u2026)
+  ${dim("(default: Anthropic API, needs ANTHROPIC_API_KEY)")}
+
 ${bold("Options for run")}
-  --success "a; b"   success criteria (semicolon-separated)
-  --tools fs         allow sandboxed read_file/write_file/list_dir (default: none)
-  --model <id>       model for the Anthropic provider
-  --max-steps <n>    step budget          --max-tokens <n>   token budget
-  --runs-dir <dir>   where checkpoints live (default: runs/)
-  --quiet            no live event stream
+  --model <id>          model/alias for the chosen provider (e.g. opus, sonnet, llama3.1)
+  --cli-tools           let a CLI provider run its own tools (claude/codex); pairs with --permission-mode
+  --permission-mode <m> claude: acceptEdits (default) | dontAsk | plan
+  --allow "Read,Edit"   claude: exact tool allowlist instead of the file-only default
+  --success "a; b"      success criteria (semicolon-separated)
+  --tools fs            give the harness sandboxed read_file/write_file/list_dir (API providers)
+  --max-steps <n>       step budget          --max-tokens <n>   token budget
+  --runs-dir <dir>      where checkpoints live (default: runs/)
+  --quiet               no live event stream
 
 ${bold("Examples")}
-  oh-my-fable run "summarize README.md into SUMMARY.md" --tools fs
-  oh-my-fable run "outline a talk on durable agents" --success "an outline with 5 sections"
-  oh-my-fable demo
+  oh-my-fable run "refactor utils.ts and run the tests" --provider claude --cli-tools   ${dim("# no API key")}
+  oh-my-fable run "outline a talk on durable agents" --provider ollama --model llama3.1
+  oh-my-fable show run_abc123                                          ${dim("# inspect any saved run")}
+  oh-my-fable demo                                                    ${dim("# no key at all")}
 
 ${dim(`It's also a library: import { run, AnthropicProvider } from "oh-my-fable".`)}
 `);
@@ -1180,6 +1525,8 @@ async function main() {
       return cmdResume(args);
     case "list":
       return cmdList(args);
+    case "show":
+      return cmdShow(args);
     case "demo":
       return cmdDemo();
     default: