roforge-cli 0.3.0

package/src/tools/index.js

@@ -0,0 +1,49 @@
+// Tool registry: merges local tools (web, roblox, project) with the active
+// Studio tier (bridge or MCP). Same contract everywhere:
+//   { name, description, inputSchema, execute(args, ctx) -> string, requiresApproval? }
+// Errors are returned as "ERROR: ..." strings the model can adapt to.
+import { webTools } from "./web.js";
+import { robloxTools } from "./roblox.js";
+import { projectTools } from "./project.js";
+import { bridgeTools, mcpToolsFromList, mcpCaptureNames } from "./studio.js";
+import { McpClient } from "../mcp.js";
+
+export async function buildTools({ cfg, cwd, bridgeServer, luauAnalyzePath }) {
+  const tools = [];
+  const seen = new Set();
+  const add = (list) => {
+    for (const t of list) {
+      if (!t || seen.has(t.name)) continue;
+      seen.add(t.name);
+      tools.push(t);
+    }
+  };
+
+  add(webTools());
+  add(robloxTools());
+  add(projectTools({ cwd, luauAnalyzePath }));
+  if (bridgeServer) add(bridgeTools(bridgeServer));
+
+  // MCP tier (official, built into Studio)
+  if (cfg.studioMode === "mcp" || cfg.studioMode === "auto") {
+    try {
+      const client = new McpClient(cfg.mcpUrl, { timeoutMs: cfg.studioMode === "mcp" ? 30000 : 4000 });
+      await client.connect();
+      const raw = await client.listTools();
+      if (raw.length) {
+        add(mcpToolsFromList(client, raw));
+        cfg._mcpClient = client;
+        cfg._mcpConnected = true;
+        return { tools, mcp: true, bridge: Boolean(bridgeServer), mcpToolCount: raw.length, mcpCapture: mcpCaptureNames(raw) };
+      }
+    } catch {
+      /* fall through to bridge-only */
+    }
+  }
+
+  return { tools, mcp: false, bridge: Boolean(bridgeServer), mcpToolCount: 0, mcpCapture: [] };
+}
+
+export function listToolNames(tools) {
+  return tools.map((t) => t.name);
+}

package/src/tools/project.js

@@ -0,0 +1,212 @@
+// Project tools: work on the Rojo project on disk (the Claude-Code-style
+// "agent edits your project files" workflow). cwd-scoped, with path guards.
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { truncate } from "../util.js";
+
+const IGNORED = new Set([
+  "node_modules", ".git", "dist", "build", ".rojo", "coverage", ".venv", "out", "target", "__pycache__", ".next",
+]);
+
+function isWithin(root, p) {
+  const rel = path.relative(root, p);
+  return rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+function safeJoin(root, p) {
+  const abs = path.resolve(root, p);
+  if (!isWithin(root, abs)) throw new Error(`path escapes the project root: ${p}`);
+  return abs;
+}
+
+function listTree(root, dir = "", depth = 0, maxDepth = 4, acc = [], cap = { n: 0 }) {
+  if (depth > maxDepth || cap.n > 500) return acc;
+  const entries = fs.readdirSync(path.join(root, dir), { withFileTypes: true })
+    .filter((e) => !IGNORED.has(e.name) && !e.name.startsWith(".rojo"))
+    .sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
+  for (const e of entries) {
+    if (cap.n++ > 500) {
+      acc.push(`${"  ".repeat(depth)}… (truncated)`);
+      return acc;
+    }
+    acc.push(`${"  ".repeat(depth)}${e.name}${e.isDirectory() ? "/" : ""}`);
+    if (e.isDirectory()) listTree(root, path.join(dir, e.name), depth + 1, maxDepth, acc, cap);
+  }
+  return acc;
+}
+
+export function projectTools({ cwd, luauAnalyzePath }) {
+  const root = path.resolve(cwd);
+  return [
+    {
+      name: "project_tree",
+      description: `List the Rojo project tree on disk (root: ${root}). Use before reading or editing files.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          dir: { type: "string", description: "Subdirectory. Default: project root." },
+          max_depth: { type: "integer", description: "1-8. Default 4." },
+        },
+        additionalProperties: false,
+      },
+      execute: async (args) => {
+        const dir = args.dir ? safeJoin(root, args.dir) : root;
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new Error(`not a directory: ${args.dir}`);
+        return listTree(root, dir === root ? "" : path.relative(root, dir), 0, Math.min(Math.max(1, Number(args.max_depth) || 4), 8)).join("\n");
+      },
+    },
+    {
+      name: "project_read",
+      description: "Read a file from the project (relative path).",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+        additionalProperties: false,
+      },
+      execute: async (args) => {
+        const abs = safeJoin(root, args.path);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`no such file: ${args.path}`);
+        const src = fs.readFileSync(abs, "utf8");
+        return truncate(`-- ${args.path} (${src.length} chars)\n${src}`, 24000);
+      },
+    },
+    {
+      name: "project_write",
+      description:
+        "Write (create or overwrite) a file in the project. ALWAYS send the complete new file content, never partial edits.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["path", "content"],
+        additionalProperties: false,
+      },
+      requiresApproval: true,
+      execute: async (args) => {
+        const abs = safeJoin(root, args.path);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, String(args.content));
+        return `Wrote ${String(args.content).length} chars to ${args.path}`;
+      },
+    },
+    {
+      name: "project_edit",
+      description:
+        "Replace an exact text match in a file (first occurrence). Safer than project_write for small changes; old_text must match exactly (whitespace included).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          old_text: { type: "string" },
+          new_text: { type: "string" },
+        },
+        required: ["path", "old_text", "new_text"],
+        additionalProperties: false,
+      },
+      requiresApproval: true,
+      execute: async (args) => {
+        const abs = safeJoin(root, args.path);
+        const src = fs.readFileSync(abs, "utf8");
+        const idx = src.indexOf(args.old_text);
+        if (idx === -1) throw new Error("old_text not found — read the file and retry with the exact text");
+        if (src.indexOf(args.old_text, idx + 1) !== -1) {
+          throw new Error("old_text is not unique in the file — include more surrounding context");
+        }
+        fs.writeFileSync(abs, src.slice(0, idx) + args.new_text + src.slice(idx + args.old_text.length));
+        return `Edited ${args.path}`;
+      },
+    },
+    {
+      name: "project_search",
+      description: "Grep the project files (case-insensitive fixed-string search). Returns file:line matches.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Fixed string to search for" },
+          glob: { type: "string", description: "Only search files whose name contains this, e.g. 'lua'" },
+        },
+        required: ["pattern"],
+        additionalProperties: false,
+      },
+      execute: async (args) => {
+        const needle = String(args.pattern).toLowerCase();
+        const matches = [];
+        const cap = 100;
+        const walk = (dir) => {
+          if (matches.length >= cap) return;
+          for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (matches.length >= cap) return;
+            if (IGNORED.has(e.name) || e.name.startsWith(".")) continue;
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) walk(p);
+            else {
+              if (args.glob && !e.name.toLowerCase().includes(args.glob.toLowerCase())) continue;
+              if (p.length > 300 || !/\.(lua|md|json|txt|rbxl)$/.test(e.name)) continue;
+              try {
+                const lines = fs.readFileSync(p, "utf8").split("\n");
+                for (let i = 0; i < lines.length; i++) {
+                  if (matches.length >= cap) return;
+                  if (lines[i].toLowerCase().includes(needle)) {
+                    matches.push(`${path.relative(root, p)}:${i + 1}: ${lines[i].trim().slice(0, 160)}`);
+                  }
+                }
+              } catch {
+                /* skip unreadable */
+              }
+            }
+          }
+        };
+        walk(root);
+        return matches.length ? matches.join("\n") : `No matches for '${args.pattern}'.`;
+      },
+    },
+    {
+      name: "project_run",
+      description:
+        "Run a command in the project root (e.g. 'rojo build -o dist/RoForge.rbxm', 'node --test test/', 'luau-analyze src/…'). 60s timeout. Use for builds and checks, not long-running servers.",
+      inputSchema: {
+        type: "object",
+        properties: { command: { type: "string", description: "Shell command to run" } },
+        required: ["command"],
+        additionalProperties: false,
+      },
+      requiresApproval: true,
+      execute: async (args) => {
+        const { code, out } = await runShell(String(args.command), root, 60000);
+        const status = code === 0 ? "OK" : `exit ${code}`;
+        return `[${args.command}]\n${status}\n${truncate(out, 8000)}`;
+      },
+    },
+    luauAnalyzePath
+      ? {
+          name: "luau_analyze",
+          description: `Run the official Luau static analyzer on a project file (catches syntax + type errors). Path relative to project root.`,
+          inputSchema: {
+            type: "object",
+            properties: { path: { type: "string" } },
+            required: ["path"],
+            additionalProperties: false,
+          },
+          execute: async (args) => {
+            const abs = safeJoin(root, args.path);
+            if (!fs.existsSync(abs)) throw new Error(`no such file: ${args.path}`);
+            const { code, out } = await runShell(`"${luauAnalyzePath}" "${abs}"`, root, 30000);
+            return code === 0 ? "No analyzer issues found." : truncate(out, 6000);
+          },
+        }
+      : null,
+  ].filter(Boolean);
+}
+
+function runShell(command, cwd, timeoutMs) {
+  return new Promise((resolve) => {
+    execFile("/bin/sh", ["-c", command], { cwd, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err ? (typeof err.code === "number" ? err.code : 1) : 0;
+      resolve({ code, out: [stdout, stderr].filter(Boolean).join("\n") || "(no output)" });
+    });
+  });
+}

package/src/tools/roblox.js

@@ -0,0 +1,95 @@
+// Roblox API tools, run locally against official public endpoints.
+const UA = "RoForge/0.2 (+local; roblox studio agent)";
+
+async function robloxGet(url, timeoutMs = 10000) {
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: { "User-Agent": UA, Accept: "application/json" },
+  }).catch((e) => {
+    throw new Error(`Roblox API unreachable: ${e.cause?.code || e.message}`);
+  });
+  if (res.status === 403) {
+    throw new Error("Roblox API refused the request (403) — commonly from datacenter IPs. Retry later.");
+  }
+  if (!res.ok) throw new Error(`Roblox API HTTP ${res.status}`);
+  return res.json();
+}
+
+function positiveInt(v, field) {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`${field} must be a positive integer`);
+  return n;
+}
+
+export async function gameByUniverse(universeId) {
+  const n = positiveInt(universeId, "universeId");
+  const data = await robloxGet(`https://games.roblox.com/v1/games?universeIds=${n}`);
+  const g = (data.data || [])[0];
+  if (!g) return `No game found for universeId ${n}.`;
+  return [
+    `Game: ${g.name}`,
+    `  gameId: ${g.id}`,
+    `  universeId: ${g.universeId}`,
+    `  playing: ${g.playing}`,
+    `  visits: ${g.visits}`,
+    `  maxPlayers: ${g.maxPlayers}`,
+    `  updated: ${g.updated}`,
+  ].join("\n");
+}
+
+export async function gameByPlace(placeId) {
+  const n = positiveInt(placeId, "placeId");
+  const data = await robloxGet(`https://apis.roblox.com/universes/v1/places/${n}/universe`);
+  const uid = data && data.universeId;
+  if (!uid) return `No universe found for placeId ${n}.`;
+  return `placeId ${n} → universeId ${uid}\n\n${await gameByUniverse(uid)}`;
+}
+
+export async function userLookup(usernames) {
+  if (!Array.isArray(usernames) || !usernames.length) throw new Error("usernames must be a non-empty array");
+  const list = usernames.slice(0, 10).map((u) => String(u).trim()).filter(Boolean);
+  const data = await robloxGet(`https://users.roblox.com/v1/users?userNames=${encodeURIComponent(list.join(","))}`);
+  const users = data.data || [];
+  if (!users.length) return `No users found for: ${list.join(", ")}`;
+  return users
+    .map((u) => `User: ${u.name}\n  id: ${u.id}\n  displayName: ${u.displayName}\n  createdAt: ${u.created}`)
+    .join("\n\n");
+}
+
+export function robloxTools() {
+  return [
+    {
+      name: "roblox_game_lookup",
+      description: "Look up a Roblox game by universeId. Returns name, id, players, visits.",
+      inputSchema: {
+        type: "object",
+        properties: { universeId: { type: "integer" } },
+        required: ["universeId"],
+        additionalProperties: false,
+      },
+      execute: async (args) => gameByUniverse(args.universeId),
+    },
+    {
+      name: "roblox_game_by_place",
+      description: "Look up a Roblox game by placeId (the number in the Studio place URL).",
+      inputSchema: {
+        type: "object",
+        properties: { placeId: { type: "integer" } },
+        required: ["placeId"],
+        additionalProperties: false,
+      },
+      execute: async (args) => gameByPlace(args.placeId),
+    },
+    {
+      name: "roblox_user_lookup",
+      description: "Look up Roblox users by username (1-10). Returns ids, display names, created dates.",
+      inputSchema: {
+        type: "object",
+        properties: { usernames: { type: "array", items: { type: "string" } } },
+        required: ["usernames"],
+        additionalProperties: false,
+      },
+      execute: async (args) => userLookup(args.usernames),
+    },
+  ];
+}

package/src/tools/studio.js

@@ -0,0 +1,296 @@
+// Studio tools — two interchangeable tiers:
+//   • bridge: our RoForge Bridge plugin polls the local BridgeServer
+//   • mcp:    the MCP server built into Roblox Studio (beta), over HTTP
+// Both expose the same tool shape; the agent doesn't care which tier answers.
+
+const BRIDGE_TOOL_NAMES = [
+  "forge_selected",
+  "forge_tree",
+  "forge_read",
+  "forge_write",
+  "forge_create",
+  "forge_delete",
+  "forge_run",
+  "forge_screenshot",
+  "forge_game_info",
+  "forge_viewport",
+  "forge_get_property",
+  "forge_set_property",
+  "forge_get_attributes",
+  "forge_set_attribute",
+  "forge_select",
+  "forge_checkpoint",
+  "forge_undo",
+  "forge_checkpoints",
+  "forge_find",
+  "forge_bulk_create",
+  "forge_snapshot",
+  "forge_diff",
+  "forge_export",
+  "forge_import",
+];
+
+const BRIDGE_DESCRIPTIONS = {
+  forge_selected: "List the instances currently selected in Studio (full path + class).",
+  forge_tree: "Show an indented tree of instances in Studio (default root: workspace). Use to discover names before reading or editing.",
+  forge_read: "Read a script's source in Studio by dotted path (e.g. 'ServerScriptService.Game.Main'), or dump an instance's properties.",
+  forge_write: "Write COMPLETE source to a script in Studio by path. Use after forge_read; send the full new source, never partial edits.",
+  forge_create: "Create an instance in Studio under a parent path, optionally setting simple properties.",
+  forge_delete: "Delete an instance in Studio by path. Destructive.",
+  forge_run: "Run a Luau snippet inside Studio and report return values or the error. For diagnostics only.",
+  forge_screenshot: "Save a screenshot of the Studio 3D viewport to the user's computer (file only; the model cannot see it).",
+  forge_game_info: "Place id, job id, Studio mode, selection count.",
+  forge_viewport: "Capture the Studio 3D viewport as a PNG image that the model can actually SEE (vision). Use to visually inspect the scene after making changes.",
+  forge_get_property: "Read a single property of an instance in Studio by dotted path.",
+  forge_set_property: "Set a single property of an instance in Studio. Destructive.",
+  forge_get_attributes: "List all attributes (name = value) on an instance in Studio.",
+  forge_set_attribute: "Set a string/number/boolean attribute on an instance in Studio. Destructive.",
+  forge_select: "Set the Studio selection to the given instance paths.",
+  forge_checkpoint: "Mark the current Studio state as a named checkpoint in the undo history. Call it BEFORE a batch of destructive changes so they can be rolled back as a unit with forge_undo.",
+  forge_undo: "Undo Studio changes: pass to='name' to roll back to a named checkpoint, or omit to undo one step. Destructive.",
+  forge_checkpoints: "List recorded checkpoints (name, index, steps back) and the current change-history index.",
+  forge_find: "Find instances in Studio by name substring (pattern) and/or ClassName (class_name). Returns up to `limit` full paths (default 50, max 200).",
+  forge_bulk_create: "Create many instances in one call (paste-style): items[] of {path: parent path, class_name, name?, properties?}. Destructive.",
+  forge_snapshot: "Capture the current instance tree under a name, so forge_diff can show what changed later. Keeps the last 10.",
+  forge_diff: "Compare a snapshot to the current instance tree: added (+) and removed (-) instances. Omit name to diff the most recent snapshot.",
+  forge_export: "Export a DataModel subtree as JSON (properties, script sources truncated, attributes). Defaults to workspace, depth 3 (max 6).",
+  forge_import: "Apply a forge_export JSON back into Studio: recreates the instance tree (properties, sources, attributes) under a parent. dry_run=true only reports. Destructive; max 500 nodes.",
+};
+
+const BRIDGE_SCHEMAS = {
+  forge_selected: { type: "object", properties: {}, additionalProperties: false },
+  forge_tree: {
+    type: "object",
+    properties: {
+      root: { type: "string", description: "Root service (workspace, ServerScriptService, …). Default workspace." },
+      max_depth: { type: "integer", description: "1-6. Default 3." },
+    },
+    additionalProperties: false,
+  },
+  forge_read: { type: "object", properties: { path: { type: "string" } }, required: ["path"], additionalProperties: false },
+  forge_write: {
+    type: "object",
+    properties: { path: { type: "string" }, source: { type: "string" }, create: { type: "boolean" } },
+    required: ["path", "source"],
+    additionalProperties: false,
+  },
+  forge_create: {
+    type: "object",
+    properties: {
+      parent_path: { type: "string" },
+      class_name: { type: "string" },
+      name: { type: "string" },
+      properties: { type: "object" },
+    },
+    required: ["parent_path", "class_name"],
+    additionalProperties: false,
+  },
+  forge_delete: { type: "object", properties: { path: { type: "string" } }, required: ["path"], additionalProperties: false },
+  forge_run: { type: "object", properties: { code: { type: "string" } }, required: ["code"], additionalProperties: false },
+  forge_screenshot: {
+    type: "object",
+    properties: { name: { type: "string" }, width: { type: "integer" }, height: { type: "integer" } },
+    additionalProperties: false,
+  },
+  forge_game_info: { type: "object", properties: {}, additionalProperties: false },
+  forge_viewport: {
+    type: "object",
+    properties: {
+      width: { type: "integer", description: "256-1280. Default 1024." },
+      height: { type: "integer", description: "240-720. Default 576." },
+    },
+    additionalProperties: false,
+  },
+  forge_get_property: {
+    type: "object",
+    properties: { path: { type: "string" }, property: { type: "string" } },
+    required: ["path", "property"],
+    additionalProperties: false,
+  },
+  forge_set_property: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      property: { type: "string" },
+      value: { type: "string", description: "New value (numbers/booleans coerced)" },
+    },
+    required: ["path", "property", "value"],
+    additionalProperties: false,
+  },
+  forge_get_attributes: {
+    type: "object",
+    properties: { path: { type: "string" } },
+    required: ["path"],
+    additionalProperties: false,
+  },
+  forge_set_attribute: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      name: { type: "string" },
+      value: { type: "string", description: "New value (string/number/boolean)" },
+    },
+    required: ["path", "name", "value"],
+    additionalProperties: false,
+  },
+  forge_select: {
+    type: "object",
+    properties: {
+      paths: { type: "array", items: { type: "string" }, description: "Dotted instance paths to select" },
+    },
+    required: ["paths"],
+    additionalProperties: false,
+  },
+  forge_checkpoint: {
+    type: "object",
+    properties: { name: { type: "string", description: "Checkpoint label, e.g. 'before-car-tweaks'" } },
+    required: ["name"],
+    additionalProperties: false,
+  },
+  forge_undo: {
+    type: "object",
+    properties: { to: { type: "string", description: "Checkpoint name to roll back to (omit to undo one step)" } },
+    additionalProperties: false,
+  },
+  forge_checkpoints: { type: "object", properties: {}, additionalProperties: false },
+  forge_find: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Name substring, case-insensitive" },
+      class_name: { type: "string", description: "Exact ClassName, e.g. Part, Script" },
+      limit: { type: "integer", description: "Max results, 1-200. Default 50." },
+    },
+    additionalProperties: false,
+  },
+  forge_bulk_create: {
+    type: "object",
+    properties: {
+      items: {
+        type: "array",
+        description: "Instances to create (max 200)",
+        items: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Parent dotted path" },
+            class_name: { type: "string", description: "Instance class, e.g. Part" },
+            name: { type: "string", description: "Instance name (default: class_name)" },
+            properties: { type: "object", description: "Optional properties to set" },
+          },
+          required: ["path", "class_name"],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ["items"],
+    additionalProperties: false,
+  },
+  forge_snapshot: {
+    type: "object",
+    properties: { name: { type: "string", description: "Snapshot label (default: auto)" } },
+    additionalProperties: false,
+  },
+  forge_diff: {
+    type: "object",
+    properties: { name: { type: "string", description: "Snapshot name (default: most recent)" } },
+    additionalProperties: false,
+  },
+  forge_export: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Dotted path of subtree root (default: workspace)" },
+      depth: { type: "integer", description: "Tree depth 1-6 (default 3)" },
+    },
+    additionalProperties: false,
+  },
+  forge_import: {
+    type: "object",
+    properties: {
+      json: { type: "string", description: "The export JSON text" },
+      path: { type: "string", description: "Plugin-folder file containing the export JSON" },
+      parent: { type: "string", description: "Parent path to import under (default: workspace)" },
+      name: { type: "string", description: "Rename the root instance (optional)" },
+      dry_run: { type: "boolean", description: "Only report what would be created" },
+    },
+    additionalProperties: false,
+  },
+};
+
+// Tools that modify the DataModel — gated by the approval prompt.
+const DESTRUCTIVE = new Set([
+  "forge_write",
+  "forge_create",
+  "forge_delete",
+  "forge_run",
+  "forge_set_property",
+  "forge_set_attribute",
+  "forge_undo",
+  "forge_bulk_create",
+  "forge_import",
+]);
+
+export function bridgeTools(bridgeServer) {
+  return BRIDGE_TOOL_NAMES.map((name) => ({
+    name,
+    description: BRIDGE_DESCRIPTIONS[name],
+    inputSchema: BRIDGE_SCHEMAS[name],
+    tier: "bridge",
+    requiresApproval: DESTRUCTIVE.has(name),
+    // Returns a plain string, or {text, image:{base64, mediaType}} when the
+    // tool produced an image (forge_viewport).
+    execute: async (args) => {
+      const out = await bridgeServer.submit(name, args, { timeoutMs: 60000 });
+      if (!out.ok) return `ERROR: ${out.error}`;
+      const r = out.result;
+      if (r && typeof r === "object") {
+        const image =
+          typeof r.imageBase64 === "string" && r.imageBase64.length
+            ? { base64: r.imageBase64, mediaType: r.mediaType || "image/png" }
+            : undefined;
+        return { text: String(r.text ?? ""), image };
+      }
+      return String(r ?? "");
+    },
+  }));
+}
+
+// Wrap Studio's built-in MCP tools as roforge tools. Names are prefixed to
+// avoid clashes with bridge tools; descriptions pass through.
+
+// Studio MCP tools that return a scene capture (vision) — matched by name or
+// description so the model is told they produce a SEEABLE image.
+const CAPTURE_NAME_RE = /screenshot|capture|render|image|viewport/i;
+const CAPTURE_DESC_RE = /screenshot|capture|render|image of|viewport/i;
+export function looksLikeCapture(t) {
+  return CAPTURE_NAME_RE.test(t.name || "") || CAPTURE_DESC_RE.test(t.description || "");
+}
+
+export function mcpCaptureNames(rawTools) {
+  return (rawTools || []).filter(looksLikeCapture).map((t) => t.name);
+}
+
+export function mcpTools(mcpClient) {
+  return (mcpClient._listedTools || []).map((t) => ({
+    name: `studio_${t.name}`,
+    description:
+      (t.description || `Studio MCP tool: ${t.name}`) +
+      (looksLikeCapture(t) ? " Returns an image the model can actually SEE (vision)." : ""),
+    inputSchema: t.inputSchema || { type: "object", properties: {} },
+    tier: "mcp",
+    _mcpName: t.name,
+    _isCapture: looksLikeCapture(t),
+    // MCP write tools are usually named create_*/set_*/delete_* — approve those.
+    requiresApproval: /^(create|set|delete|remove|rename|move|execute|run|write|update|add|destroy|insert|sync|push)/i.test(t.name),
+    execute: async (args) => {
+      const out = await mcpClient.callTool(t.name, args);
+      if (out.isError && !out.image) return `ERROR: ${out.text}`;
+      // structured so a returned image reaches the model's vision channel
+      return { text: out.text, image: out.image };
+    },
+  }));
+}
+
+// After a successful tools/list, store the raw list and build wrapped tools.
+export function mcpToolsFromList(mcpClient, rawTools) {
+  mcpClient._listedTools = rawTools;
+  return mcpTools(mcpClient);
+}