roforge-cli 0.3.0

package/README.md

@@ -0,0 +1,58 @@
+# roforge-cli
+
+**RoForge** — a Claude-Code-style local AI agent for Roblox Studio. Bring your
+own API key, zero backend, zero npm dependencies.
+
+```
+roforge                     interactive TUI (auto-connects to Studio)
+roforge chat -m "prompt"    one-shot mode (streams to stdout)
+roforge providers           list providers, keys, and free-routing order
+roforge login --provider <p> store an API key
+roforge analyze <file...>   official Luau analyzer
+```
+
+## Install
+
+```bash
+# GitHub Packages (published — any GitHub token with read:packages works)
+npm config set @hacvilke:registry https://npm.pkg.github.com
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc
+npm i -g @hacvilke/roforge-cli
+
+# …or clone the repo and run `node cli/bin/roforge.js`
+roforge
+```
+
+Requires Node ≥ 18.17. No other dependencies.
+
+## Free tiers (no card needed)
+
+`roforge providers` shows what you have. With `provider: "auto"` (default) the
+CLI routes to the best free model you have a key for:
+
+- **Gemini** — `gemini-2.5-flash` (~1,500 req/day free) → aistudio.google.com
+- **Groq** — `llama-3.3-70b-versatile` (~1,000 req/day free) → console.groq.com
+- **OpenRouter** — `:free` models (e.g. `qwen/qwen3-coder:free`) → openrouter.ai
+- Anthropic / OpenAI — paid, highest priority when free tiers are exhausted
+
+## Connecting to Studio
+
+1. **Built-in MCP (recommended)**: Studio → File → Studio Settings → Beta
+   Features → MCP Server, pick a port. `roforge` probes `http://127.0.0.1:8998`
+   (configurable via `ROFORGE_MCP_URL`).
+2. **RoForge Bridge plugin** (our fallback): install from the repo
+   (`studio-bridge/`) — see the full README in the project repo.
+
+With Studio connected, the agent can read the DataModel, read/write scripts,
+create/delete instances, run Luau, **see the viewport** (vision), set
+checkpoints and **undo its own edits**, find/bulk-create instances, and diff
+the hierarchy.
+
+## Where
+
+Full docs live in the project repo — `README.md`, `docs/CLI.md`,
+`docs/BRIDGE.md`, `PROGRESS.md`.
+
+> **Publishing:** before `npm publish`, set a real `repository`/`homepage`/`bugs`
+> URL in `cli/package.json` (left empty on purpose so no placeholder is
+> shipped).

package/bin/roforge.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+// RoForge — local Claude-Code-style agent for Roblox Studio.
+// Zero dependencies, zero backend. Your key goes only to the model provider.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { resolveConfig, apiKeyFor, modelFor, CONFIG_FILE, saveFileConfig, PROVIDERS, providerHasKey, effectiveProvider } from "../src/config.js";
+import { Session } from "../src/session.js";
+import { BridgeServer } from "../src/bridge/server.js";
+import { probeMcp } from "../src/mcp.js";
+import { TUI } from "../src/tui/tui.js";
+import { bold, dim, red, green, cyan, yellow, gray } from "../src/tui/ansi.js";
+
+const argv = process.argv.slice(2);
+const command = argv[0] || "tui";
+const flags = parseFlags(argv.slice(1));
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (a.startsWith("-") && a.length === 2) {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        flags[a.slice(1)] = next;
+        i++;
+      } else {
+        flags[a.slice(1)] = true;
+      }
+    } else {
+      flags._pos = (flags._pos || []).concat(a);
+    }
+  }
+  return flags;
+}
+
+function findLuauAnalyze() {
+  const candidates = [
+    process.env.ROFORGE_LUAU_ANALYZE,
+    "luau-analyze",
+    path.resolve(process.cwd(), "luau-analyze"),
+  ].filter(Boolean);
+  for (const c of candidates) {
+    try {
+      execFileSync(c, ["--help"], { stdio: "ignore" });
+      return c;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}
+
+async function main() {
+  const cfg = resolveConfig();
+  if (flags.provider && PROVIDERS[flags.provider]) cfg.provider = flags.provider;
+  cfg._apiKeyPresent = Boolean(apiKeyFor(cfg));
+
+  switch (command) {
+    case "version":
+    case "--version":
+    case "-v": {
+      const pkg = JSON.parse(fs.readFileSync(path.resolve(path.dirname(process.argv[1]), "../package.json"), "utf8"));
+      console.log(`roforge ${pkg.version}`);
+      return;
+    }
+
+    case "login": {
+      const provider =
+        flags.provider || (cfg.provider !== "auto" && PROVIDERS[cfg.provider] ? cfg.provider : null);
+      if (!provider) {
+        console.error(red("usage: roforge login --provider <gemini|groq|openrouter|anthropic|openai>"));
+        process.exit(1);
+      }
+      const promptKey = async (label) => {
+        process.stderr.write(`Paste ${label} (input hidden): `);
+        let val = "";
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(true);
+          for await (const chunk of process.stdin) {
+            for (const ch of String(chunk)) {
+              if (ch === "\r" || ch === "\n" || ch === "\x04") {
+                process.stdin.setRawMode(false);
+                console.error("");
+                return val;
+              }
+              if (ch === "\x7f" || ch === "\b") val = val.slice(0, -1);
+              else if (ch >= " " || ch === "\t") val += ch;
+            }
+          }
+        } else {
+          for await (const chunk of process.stdin) val += String(chunk);
+          return val.trim();
+        }
+      };
+      const hint = {
+        gemini: "Gemini API key (free at aistudio.google.com)",
+        groq: "Groq API key (console.groq.com)",
+        openrouter: "OpenRouter API key (openrouter.ai)",
+        anthropic: "Anthropic API key",
+        openai: "OpenAI API key",
+      }[provider];
+      const val = await promptKey(hint);
+      if (!val) {
+        console.error(red("no key entered"));
+        process.exit(1);
+      }
+      saveFileConfig({ [PROVIDERS[provider].keyField]: val });
+      console.error(green(`saved ${provider} key to ${CONFIG_FILE}`) + dim(" (0600 perms recommended)"));
+      try {
+        fs.chmodSync(CONFIG_FILE, 0o600);
+      } catch {
+        /* windows */
+      }
+      return;
+    }
+
+    case "studio": {
+      const bridge = new BridgeServer({ port: cfg.bridge.port, host: cfg.bridge.host, token: cfg.bridge.token });
+      try {
+        await bridge.start();
+      } catch (e) {
+        console.error(red(`bridge could not start on port ${cfg.bridge.port}: ${e.message}`));
+        process.exit(1);
+      }
+      const mcp = await probeMcp(cfg.mcpUrl);
+      console.log(bold("RoForge — Studio connection") + "\n");
+      if (mcp.ok) {
+        console.log(`${green("●")} studio MCP (built into Studio): ${mcp.toolCount} tools @ ${cfg.mcpUrl}`);
+      } else {
+        console.log(`${red("○")} studio MCP: not reachable @ ${cfg.mcpUrl}`);
+        console.log(dim("  enable: Roblox Studio → File → Studio Settings → Beta Features → 'MCP Server'"));
+      }
+      console.log(`${yellow("○")} bridge plugin: waiting for Studio @ http://${bridge.host}:${bridge.port}`);
+      console.log(dim(`  bridge token: ${cfg.bridge.token}`));
+      console.log(dim("  (paste the token into the RoForge Bridge plugin's settings in Studio)"));
+      console.log(dim("\nthis process stays running as the bridge — Ctrl+C to stop"));
+      const stop = () => {
+        bridge.stop();
+        process.exit(0);
+      };
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+      return;
+    }
+
+    case "tools": {
+      const bridge = new BridgeServer({ port: cfg.bridge.port, host: cfg.bridge.host, token: cfg.bridge.token });
+      await bridge.start();
+      const session = new Session({ cfg, cwd: process.cwd(), bridgeServer: bridge, luauAnalyzePath: null, ui: {} });
+      await session.init();
+      console.log(bold(`tools (${session.tools.length})`));
+      for (const t of session.tools) {
+        const tier = t.tier ? gray(` [${t.tier}]`) : "";
+        const appr = t.requiresApproval ? gray(" (approve)") : "";
+        console.log(`  ${cyan(t.name)}${tier}${appr} — ${dim(t.description.split(".")[0])}`);
+      }
+      bridge.stop();
+      return;
+    }
+
+    case "chat": {
+      const prompt = flags.m || flags.message;
+      if (!prompt) {
+        console.error(red('usage: roforge chat -m "your prompt"  (or just run `roforge` for the TUI)'));
+        process.exit(1);
+      }
+      await oneShot(cfg, prompt);
+      return;
+    }
+
+    case "analyze": {
+      const files = flags._pos || [];
+      if (!files.length) {
+        console.error(red("usage: roforge analyze <file.lua ...>"));
+        process.exit(1);
+      }
+      const luau = findLuauAnalyze();
+      if (!luau) {
+        console.error(red("luau-analyze not found. Install it (https://github.com/luau-lang/luau/releases) or set ROFORGE_LUAU_ANALYZE."));
+        process.exit(1);
+      }
+      for (const f of files) {
+        let stdout = "";
+        let failed = false;
+        try {
+          stdout = execFileSync(luau, [f], { stdio: "pipe" }).toString();
+        } catch (e) {
+          // luau-analyze reports on stderr
+          const buf = (e.stderr && e.stderr.length ? e.stderr : e.stdout) || Buffer.alloc(0);
+          stdout = buf.toString();
+          failed = true;
+        }
+        // The standalone analyzer doesn't know Roblox's built-in globals
+        // (game, script, Instance, task, …). Those are expected noise; only
+        // real problems (syntax, type, undefined locals) should fail.
+        const issues = stdout
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean)
+          .filter((l) => !/Unknown global|consider assigning to it first/i.test(l));
+        if (failed && issues.length) {
+          console.log(`${red("FAIL")} ${f}\n${stdout}`);
+          process.exitCode = 1;
+        } else if (failed && !issues.length) {
+          console.log(`${green("ok  ")} ${f}` + (stdout.trim() ? dim("  (only expected Roblox-global notes)") : ""));
+        } else {
+          console.log(`${green("ok  ")} ${f}`);
+        }
+      }
+      return;
+    }
+
+    case "config": {
+      const sub = flags._pos && flags._pos[0];
+      if (sub === "set" && flags._pos[1] && flags._pos[2]) {
+        const key = flags._pos[1];
+        const value = flags._pos[2];
+        saveFileConfig({ [key]: value });
+        console.log(`${key} = ${value}`);
+      } else {
+        console.log(JSON.stringify(cfg, (k, v) => (/Key$/.test(k) ? (v ? "•••set•••" : "") : v), 2));
+      }
+      return;
+    }
+
+    case "providers": {
+      const eff = effectiveProvider(cfg);
+      console.log(bold("providers") + dim("  (provider → model for auto mode)\n"));
+      for (const [name, meta] of Object.entries(PROVIDERS)) {
+        const has = providerHasKey(cfg, name);
+        const marker = eff === name ? green("◀ active") : has ? green("key set") : dim("no key");
+        const free = meta.hasFreeTier ? dim(` · free tier: ${meta.freeModel}`) : "";
+        console.log(`  ${has ? green("●") : dim("№")} ${name.padEnd(11)} ${marker.padEnd(12)} ${has ? meta.defaultModel : dim(meta.defaultModel)}${free}`);
+      }
+      console.log(dim("\nset a key: roforge login --provider <name>   ·   pin a model: roforge chat -m hi --model gemini:gemini-2.5-flash"));
+      console.log(dim("auto mode picks the first key above (free tiers first). freeFirst=false reverses the order."));
+      return;
+    }
+
+    case "help":
+    case "--help":
+    case "-h": {
+      printHelp();
+      return;
+    }
+
+    case "tui": {
+      await runTUI(cfg);
+      return;
+    }
+
+    default:
+      console.error(red(`unknown command: ${command}`));
+      printHelp();
+      process.exit(1);
+      return;
+  }
+}
+
+async function runTUI(cfg) {
+  const bridge = new BridgeServer({ port: cfg.bridge.port, host: cfg.bridge.host, token: cfg.bridge.token });
+  try {
+    await bridge.start();
+  } catch (e) {
+    console.error(yellow(`bridge disabled (port ${cfg.bridge.port} busy): ${e.message}`));
+  }
+  const session = new Session({
+    cfg,
+    cwd: process.cwd(),
+    bridgeServer: bridge.server ? bridge : null,
+    luauAnalyzePath: findLuauAnalyze(),
+    ui: {},
+  });
+  try {
+    await session.init();
+  } catch (e) {
+    console.error(red(`init: ${e.message}`));
+  }
+  const tui = new TUI(session);
+  session.ui = tui; // wire the event sink
+  const ok = await tui.start();
+  if (!ok) {
+    bridge.stop();
+    return;
+  }
+  process.on("exit", () => bridge.stop());
+  // keep the bridge alive while the TUI runs
+  await new Promise(() => {
+    /* stays until process exit */
+  });
+}
+
+async function oneShot(cfg, prompt) {
+  const bridge = new BridgeServer({ port: cfg.bridge.port, host: cfg.bridge.host, token: cfg.bridge.token });
+  try {
+    await bridge.start();
+  } catch {
+    /* bridge optional in one-shot */
+  }
+  const session = new Session({
+    cfg,
+    cwd: process.cwd(),
+    bridgeServer: bridge.server ? bridge : null,
+    luauAnalyzePath: findLuauAnalyze(),
+    ui: {
+      onText: (d) => process.stdout.write(d),
+      onToolStart: (tool, args) => {
+        let a;
+        try {
+          a = JSON.stringify(args || {});
+        } catch {
+          a = "{}";
+        }
+        if (a.length > 80) a = a.slice(0, 77) + "…";
+        process.stderr.write(gray(`[tool] ${tool.name}(${a})\n`));
+      },
+      onToolEnd: (tool, args, result) => {
+        const first = String(result || "").split("\n")[0].slice(0, 120);
+        process.stderr.write(result.startsWith("ERROR") ? red(`  ↳ ${first}\n`) : dim(`  ↳ ${first}\n`));
+      },
+      onWarn: (m) => process.stderr.write(red(m + "\n")),
+      onInfo: (m) => process.stderr.write(gray(m + "\n")),
+      onStatus: (m) => {
+        if (String(m).includes("tok")) process.stderr.write(gray(m + "\n"));
+      },
+    },
+  });
+  await session.init();
+  const out = await session.send(prompt);
+  process.stdout.write("\n");
+  bridge.stop();
+  process.exit(out.ok ? 0 : 1);
+}
+
+function printHelp() {
+  console.log(`
+${bold("RoForge")} — local Claude-Code-style agent for Roblox Studio. BYOK, zero backend.
+
+${bold("Usage")}
+  roforge                     interactive TUI (starts the local bridge)
+  roforge chat -m "prompt"    one-shot mode (streams to stdout)
+  roforge studio              keep the Studio bridge running + show connection status
+  roforge tools               list all tools
+  roforge login --provider <p> store a key (gemini|groq|openrouter|anthropic|openai)
+  roforge providers           list providers, keys, and auto-routing order
+  roforge analyze <file...>   run the official Luau analyzer on files
+  roforge config [set k v]    show / set configuration
+  roforge version
+
+${bold("How it connects to Studio")}
+  1. Built-in MCP (recommended): Studio → File → Studio Settings → Beta Features →
+     ${bold("MCP Server")} — roforge talks to it at http://localhost:3004/mcp automatically.
+  2. RoForge Bridge plugin: install studio-bridge/dist/RoForgeBridge.rbxm into Studio,
+     paste the bridge token (shown by ${bold("roforge studio")}) into the plugin.
+
+${bold("Model providers (BYOK, zero backend)")}
+  auto (default): first configured key wins, free tiers first:
+  gemini → groq → openrouter → anthropic → openai
+  free tiers: Gemini 2.5 Flash (~1,500 req/day), Groq Llama 3.3 70B (~1,000 req/day),
+  OpenRouter ":free" models (e.g. qwen/qwen3-coder:free)
+  pin: --provider <p> or --model <provider>:<model> · ROFORGE_FREE_FIRST=0
+
+${bold("Config & keys")}
+  ~/.roforge/config.json · env: GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY,
+  ANTHROPIC_API_KEY, OPENAI_API_KEY, ROFORGE_MODEL, ROFORGE_PROVIDER,
+  ROFORGE_MCP_URL, ROFORGE_BRIDGE_PORT, ROFORGE_STUDIO_MODE (auto|mcp|bridge)
+  --no-color · ROFORGE_NO_COLOR / NO_COLOR=1   disable ANSI colors
+`);
+}
+
+main().catch((e) => {
+  console.error(red(`error: ${e.stack || e.message || e}`));
+  process.exit(1);
+});

package/demo/e2e-demo.mjs

@@ -0,0 +1,53 @@
+// End-to-end demo (offline): mock Studio MCP + mock Anthropic, real CLI loop.
+// Shows: agent → MCP (Studio) tool → local project tool → streamed answer.
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+const CLI_ROOT = fileURLToPath(new URL("..", import.meta.url));
+import os from "node:os";
+import path from "node:path";
+import { startMockAnthropic, startMockMcp } from "../test/mock-server.js";
+
+const anthropic = await startMockAnthropic({ toolName: "project_tree" });
+const mcp = await startMockMcp();
+
+const cfgDir = fs.mkdtempSync(path.join(os.tmpdir(), "roforge-demo-"));
+fs.writeFileSync(
+  path.join(cfgDir, "config.json"),
+  JSON.stringify({
+    provider: "anthropic",
+    anthropicKey: "demo-key",
+    anthropicBaseUrl: `http://127.0.0.1:${anthropic.address().port}`,
+    mcpUrl: `http://127.0.0.1:${mcp.address().port}/mcp`,
+    approve: "yolo",
+  })
+);
+
+// a tiny fake project to work on
+const proj = fs.mkdtempSync(path.join(os.tmpdir(), "roforge-demo-proj-"));
+fs.mkdirSync(path.join(proj, "src"), { recursive: true });
+fs.writeFileSync(path.join(proj, "src", "Main.lua"), "print('demo project')\n");
+
+const { execFile } = await import("node:child_process");
+try {
+  await new Promise((resolve, reject) => {
+    execFile(
+      process.execPath,
+      ["bin/roforge.js", "chat", "-m", "Summarize the project and list what studio can do."],
+      {
+        cwd: CLI_ROOT,
+        env: { ...process.env, ROFORGE_CONFIG_DIR: cfgDir, NO_COLOR: "1" },
+        stdio: ["ignore", "inherit", "inherit"],
+        timeout: 60000,
+      },
+      (err) => (err ? reject(err) : resolve())
+    );
+  });
+  console.log("\n=== E2E DEMO: OK (agent loop ran against mock Studio MCP + mock model) ===");
+} catch (e) {
+  console.error("\n=== E2E DEMO exited:", e.status ?? e.message, "===");
+} finally {
+  anthropic.close();
+  mcp.close();
+  fs.rmSync(cfgDir, { recursive: true, force: true });
+  fs.rmSync(proj, { recursive: true, force: true });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "roforge-cli",
+  "version": "0.3.0",
+  "description": "RoForge — Claude-Code-style local AI agent for Roblox Studio. BYOK, zero backend, zero dependencies.",
+  "type": "module",
+  "bin": {
+    "roforge": "bin/roforge.js"
+  },
+  "scripts": {
+    "start": "node bin/roforge.js",
+    "test": "node --test test/",
+    "demo": "node demo/e2e-demo.mjs",
+    "install-plugin": "node ../scripts/install-plugin.mjs bridge",
+    "install-plugin:client": "node ../scripts/install-plugin.mjs client"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "MIT",
+  "keywords": [
+    "roblox",
+    "ai",
+    "agent",
+    "cli",
+    "tui",
+    "mcp",
+    "lua",
+    "rojo"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "demo",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hacvilke/roforge.git"
+  },
+  "homepage": "https://github.com/hacvilke/roforge#readme",
+  "bugs": {
+    "url": "https://github.com/hacvilke/roforge/issues"
+  }
+}

package/src/agent.js

@@ -0,0 +1,137 @@
+// The agent loop: chat ↔ model provider ↔ tools, until a final answer.
+// Runs locally — streaming, with an iteration safety cap.
+import { ProviderError } from "./providers/anthropic.js";
+
+const MAX_TOOL_RESULT_CHARS = 24000;
+const MAX_HISTORY_ITEMS = 60;
+
+function truncate(s, n = MAX_TOOL_RESULT_CHARS) {
+  s = String(s ?? "");
+  return s.length > n ? s.slice(0, n) + `\n... [truncated ${s.length - n} chars]` : s;
+}
+
+function trimHistory(history) {
+  while (history.length > MAX_HISTORY_ITEMS) history.shift();
+  if (history.length && history[0].role !== "user") {
+    history.unshift({ role: "user", text: "(Earlier conversation was trimmed to fit the context window.)" });
+  }
+}
+
+/**
+ * run(cfg, provider, history, system, tools, io)
+ * provider: { chatStream(cfg, {model, system, messages, tools, signal}, events) -> {text, toolCalls, usage} }
+ * io: {
+ *   onText(delta), onAssistantDone(text), onToolStart(tool, args), onToolEnd(tool, args, result),
+ *   onIter(n, total), onUsage(usage), onDone(), onAborted(), onError(err),
+ *   shouldAbort() -> bool,        // user pressed Ctrl+C
+ *   approve(name, args) -> bool,  // approval gate (session supplies)
+ * }
+ * returns { ok, text, usage: {input_tokens, output_tokens}, iterations }
+ */
+export async function runAgent(cfg, provider, history, system, tools, io) {
+  const toolByName = new Map(tools.map((t) => [t.name, t]));
+  const maxIterations = cfg.maxIterations || 12;
+  let totalUsage = { input_tokens: 0, output_tokens: 0 };
+  let finalText = "";
+
+  for (let iter = 1; iter <= maxIterations; iter++) {
+    if (io.shouldAbort && io.shouldAbort()) {
+      io.onAborted && io.onAborted();
+      return { ok: false, aborted: true, text: finalText, usage: totalUsage, iterations: iter - 1 };
+    }
+    io.onIter && io.onIter(iter, maxIterations);
+
+    let result;
+    try {
+      result = await provider.chatStream(
+        cfg,
+        {
+          model: cfg._activeModel,
+          maxTokens: cfg.maxTokens,
+          system,
+          messages: history,
+          tools,
+          signal: io.abortSignal,
+        },
+        { onText: io.onText }
+      );
+    } catch (e) {
+      if (io.shouldAbort && io.shouldAbort()) {
+        io.onAborted && io.onAborted();
+        return { ok: false, aborted: true, text: finalText, usage: totalUsage, iterations: iter - 1 };
+      }
+      io.onError && io.onError(e instanceof ProviderError ? e.message : String(e.message || e));
+      return { ok: false, error: true, text: finalText, usage: totalUsage, iterations: iter - 1 };
+    }
+
+    if (result.usage) {
+      totalUsage.input_tokens += result.usage.input_tokens || 0;
+      totalUsage.output_tokens += result.usage.output_tokens || 0;
+      io.onUsage && io.onUsage(totalUsage);
+    }
+
+    const text = result.text || "";
+    const calls = result.toolCalls || [];
+
+    if (text) {
+      finalText = text;
+    }
+    if (!calls.length) {
+      history.push({ role: "assistant", text: text || "(no output)" });
+      trimHistory(history);
+      io.onAssistantDone && io.onAssistantDone(text);
+      io.onDone && io.onDone();
+      return { ok: true, text: finalText, usage: totalUsage, iterations: iter };
+    }
+
+    // record assistant turn with tool calls, then execute each
+    history.push({
+      role: "assistant",
+      text: text || null,
+      calls: calls.map((c) => ({ id: c.id, name: c.name, args: c.input })),
+    });
+
+    for (const call of calls) {
+      if (io.shouldAbort && io.shouldAbort()) {
+        io.onAborted && io.onAborted();
+        return { ok: false, aborted: true, text: finalText, usage: totalUsage, iterations: iter };
+      }
+      const tool = toolByName.get(call.name);
+      let resultStr;
+      let image; // {base64, mediaType} — set when a tool returns an image
+      if (!tool) {
+        resultStr = `ERROR: unknown tool '${call.name}'. Do not call it again.`;
+      } else {
+        io.onToolStart && io.onToolStart(tool, call.input || {});
+        if (tool.requiresApproval) {
+          const ok = (await (io.approve && io.approve(tool.name, call.input || {}))) || false;
+          if (!ok) {
+            resultStr = "ERROR: user declined to run this tool. Choose a different approach or ask the user what they want.";
+            io.onToolEnd && io.onToolEnd(tool, call.input || {}, resultStr);
+            history.push({ role: "tool", id: call.id, name: call.name, result: resultStr });
+            continue;
+          }
+        }
+        try {
+          const raw = await tool.execute(call.input || {}, { cfg, history, iter });
+          if (raw && typeof raw === "object") {
+            resultStr = String(raw.text ?? "");
+            if (raw.image && typeof raw.image.base64 === "string") image = raw.image;
+          } else {
+            resultStr = String(raw ?? "");
+          }
+        } catch (e) {
+          resultStr = `ERROR: ${e.message || e}`;
+        }
+      }
+      resultStr = truncate(resultStr);
+      io.onToolEnd && io.onToolEnd(tool, call.input || {}, resultStr);
+      history.push({ role: "tool", id: call.id, name: call.name, result: resultStr, ...(image ? { image } : {}) });
+      trimHistory(history);
+    }
+  }
+
+  const msg = `Stopped after ${maxIterations} iterations (safety limit). Say "continue" to pick up where I left off.`;
+  io.onError && io.onError(msg);
+  return { ok: false, limit: true, text: finalText, usage: totalUsage, iterations: maxIterations };
+}