oh-my-fable 0.1.2 → 0.2.0

package/README.md

@@ -133,6 +133,14 @@ OpenAI, Ollama, LM Studio, OpenRouter, Groq… — `ollama("llama3.1")` for a lo
 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
 
 Don't want to write code? It ships a CLI (zero extra deps):
@@ -140,7 +148,11 @@ 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 use Claude Code or Codex? drive it — uses that login, no separate 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:
@@ -151,26 +163,33 @@ export ANTHROPIC_API_KEY=sk-...
 npx oh-my-fable run "summarize README.md into SUMMARY.md" --tools fs
 
 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 don't need an Anthropic API key.** Pick how it talks to a model:
 
-| `--provider` | uses | key? |
-| --- | --- | --- |
-| `claude` / `codex` | your Claude Code / Codex CLI login | **none** — rides the CLI's auth |
-| `ollama` | a local Ollama model | **none** |
-| `--base-url <url>` | LM Studio / OpenRouter / Groq / any OpenAI-compatible | per that server |
-| `openai` | OpenAI | `OPENAI_API_KEY` |
-| *(default)* | Anthropic | `ANTHROPIC_API_KEY` |
+| `--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:**
 
-(The CLI-driven providers are text-only — great for planning/reasoning runs; they
-don't expose `--tools`.)
+- `--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. `--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 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
 
@@ -238,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,12 +910,14 @@ 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"
     };
   }
@@ -986,9 +1004,10 @@ function ollama(model, opts = {}) {
 
 // src/providers/cli.ts
 var import_node_child_process = require("child_process");
-function flatten(messages) {
+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);
   }
@@ -1031,6 +1050,10 @@ var CliProvider = class {
   parse;
   env;
   timeoutMs;
+  extraArgs;
+  requestArgs;
+  parseResult;
+  systemInPrompt;
   constructor(opts) {
     this.command = opts.command;
     this.args = opts.args ?? [];
@@ -1039,14 +1062,33 @@ var CliProvider = class {
     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);
-    const args = this.promptVia === "arg" ? [...this.args, prompt] : this.args;
-    const stdout = await runCli(this.command, args, this.promptVia === "stdin" ? prompt : null, this.timeoutMs, this.env);
+    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,
@@ -1056,11 +1098,85 @@ var CliProvider = class {
     };
   }
 };
+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 = {}) {
-  return new CliProvider({ command: "claude", args: ["-p"], promptVia: "arg", label: "claude-code", ...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 = {}) {
-  return new CliProvider({ command: "codex", args: ["exec"], promptVia: "arg", label: "codex", ...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
@@ -1090,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");
@@ -1169,9 +1285,13 @@ function makeProvider(flags) {
   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 {
-    if (provider === "claude" || provider === "claude-code") return claudeCode();
-    if (provider === "codex") return codexCli();
+    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" });
@@ -1258,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();
@@ -1322,28 +1478,36 @@ 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("(default: Anthropic, needs ANTHROPIC_API_KEY)")}
-  --provider claude                         drive your Claude Code CLI \u2014 uses its login, NO separate key
-  --provider codex                          drive your Codex CLI \u2014 same idea
+${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)
-  --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 "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 run "summarize README.md into SUMMARY.md" --tools fs    ${dim("# uses Anthropic")}
+  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".`)}
@@ -1361,6 +1525,8 @@ async function main() {
       return cmdResume(args);
     case "list":
       return cmdList(args);
+    case "show":
+      return cmdShow(args);
     case "demo":
       return cmdDemo();
     default: