roforge-cli 0.3.0

package/src/providers/anthropic.js

@@ -0,0 +1,161 @@
+// Anthropic Messages API — streaming (SSE) with tool use.
+// The API key goes directly to api.anthropic.com (or cfg.anthropicBaseUrl).
+import { createSSE } from "../util.js";
+
+export class ProviderError extends Error {}
+
+/**
+ * cfg: resolved config
+ * params: { system, messages (internal history), tools, signal }
+ * events: { onText(delta), onToolStart(name, id) }
+ * returns: { text, toolCalls: [{id, name, input}], stopReason, usage }
+ */
+export async function chatStream(cfg, params, events = {}) {
+  const key = cfg.anthropicKey;
+  if (!key) throw new ProviderError("No Anthropic API key. Run `roforge login` or set ANTHROPIC_API_KEY.");
+  const body = {
+    model: params.model,
+    max_tokens: params.maxTokens || cfg.maxTokens || 8000,
+    stream: true,
+    messages: renderHistory(params.messages),
+  };
+  if (params.system) body.system = params.system;
+  if (params.tools && params.tools.length) body.tools = renderTools(params.tools);
+
+  let res;
+  try {
+    res = await fetch(`${cfg.anthropicBaseUrl}/v1/messages`, {
+      method: "POST",
+      headers: {
+        "x-api-key": key,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+        accept: "text/event-stream",
+      },
+      body: JSON.stringify(body),
+      signal: params.signal,
+    });
+  } catch (e) {
+    throw new ProviderError(`network error calling Anthropic: ${e.cause?.code || e.message}`);
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ProviderError(`Anthropic HTTP ${res.status}: ${text.slice(0, 400)}`);
+  }
+
+  let text = "";
+  let stopReason = null;
+  let usage = { input_tokens: 0, output_tokens: 0 };
+  const toolCalls = [];
+  let currentTool = null;
+
+  const sse = createSSE((ev) => {
+    const d = ev.data;
+    if (typeof d !== "object" || !d) return;
+    switch (ev.event) {
+      case "message_start":
+        if (d.message && d.message.usage) usage = { ...usage, ...d.message.usage };
+        break;
+      case "content_block_start":
+        if (d.content_block && d.content_block.type === "tool_use") {
+          currentTool = { id: d.content_block.id, name: d.content_block.name, input: {}, _json: "" };
+          toolCalls.push(currentTool);
+          events.onToolStart && events.onToolStart(currentTool.name, currentTool.id);
+        }
+        break;
+      case "content_block_delta": {
+        const delta = d.delta;
+        if (!delta) break;
+        if (delta.type === "text_delta") {
+          text += delta.text || "";
+          events.onText && events.onText(delta.text || "");
+        } else if (delta.type === "input_json_delta" && currentTool) {
+          currentTool._json += delta.partial_json || "";
+        }
+        break;
+      }
+      case "content_block_stop":
+        if (currentTool) {
+          try {
+            currentTool.input = currentTool._json ? JSON.parse(currentTool._json) : {};
+          } catch {
+            currentTool.input = {};
+          }
+          delete currentTool._json;
+          currentTool = null;
+        }
+        break;
+      case "message_delta":
+        if (d.delta && d.delta.stop_reason) stopReason = d.delta.stop_reason;
+        if (d.usage) usage = { ...usage, ...d.usage };
+        break;
+      default:
+        break;
+    }
+  });
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    sse.push(decoder.decode(value, { stream: true }));
+  }
+  sse.end();
+
+  return { text, toolCalls, stopReason, usage };
+}
+
+// Internal history → Anthropic messages.
+// items: {role:"user",text} | {role:"assistant",text?,calls?} | {role:"tool",id,name,result}
+export function renderHistory(history) {
+  const msgs = [];
+  for (const item of history) {
+    if (item.role === "user") {
+      msgs.push({ role: "user", content: item.text });
+    } else if (item.role === "assistant") {
+      const blocks = [];
+      if (item.text) blocks.push({ type: "text", text: item.text });
+      if (item.calls) {
+        for (const c of item.calls) {
+          blocks.push({ type: "tool_use", id: c.id, name: c.name, input: c.args || c.input || {} });
+        }
+      }
+      if (blocks.length) msgs.push({ role: "assistant", content: blocks });
+    } else if (item.role === "tool") {
+      // content: string, or [image block, text block] when the tool returned
+      // a vision capture (e.g. forge_viewport).
+      let content = item.result;
+      if (item.image && item.image.base64) {
+        content = [
+          {
+            type: "image",
+            source: {
+              type: "base64",
+              media_type: item.image.mediaType || "image/png",
+              data: item.image.base64,
+            },
+          },
+          { type: "text", text: item.result },
+        ];
+      }
+      const block = { type: "tool_result", tool_use_id: item.id, content };
+      const last = msgs[msgs.length - 1];
+      if (last && last.role === "user" && Array.isArray(last.content)) {
+        last.content.push(block);
+      } else {
+        msgs.push({ role: "user", content: [block] });
+      }
+    }
+  }
+  return msgs;
+}
+
+export function renderTools(tools) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.inputSchema || t.input_schema,
+  }));
+}

package/src/providers/gemini.js

@@ -0,0 +1,141 @@
+// Google Gemini (Generative Language API) — streaming (SSE) with function
+// calling and inline images. The API key goes directly to Google
+// (generativelanguage.googleapis.com, or cfg.geminiBaseUrl for mocks).
+//
+// Free tier: gemini-2.5-flash & Flash-Lite at ~1,500 req/day, no card needed.
+import { createSSE } from "../util.js";
+import { ProviderError } from "./anthropic.js";
+
+let callCounter = 0;
+
+/**
+ * cfg: resolved config
+ * params: { model, maxTokens, system, messages (internal history), tools, signal }
+ * events: { onText(delta), onToolStart(name, id) }
+ * returns: { text, toolCalls: [{id, name, input}], stopReason, usage }
+ */
+export async function chatStream(cfg, params, events = {}) {
+  const key = cfg.geminiKey;
+  if (!key) throw new ProviderError("No Gemini API key. Run `roforge login --provider gemini` or set GEMINI_API_KEY (free at aistudio.google.com).");
+  const base = (cfg.geminiBaseUrl || "https://generativelanguage.googleapis.com").replace(/\/$/, "");
+  const body = {
+    contents: renderHistory(params.messages),
+    generationConfig: { maxOutputTokens: params.maxTokens || cfg.maxTokens || 8000 },
+  };
+  if (params.system) body.systemInstruction = { parts: [{ text: params.system }] };
+  if (params.tools && params.tools.length) body.tools = [{ functionDeclarations: renderTools(params.tools) }];
+
+  let res;
+  try {
+    res = await fetch(`${base}/v1beta/models/${params.model}:streamGenerateContent?alt=sse`, {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": key,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: params.signal,
+    });
+  } catch (e) {
+    throw new ProviderError(`network error calling Gemini: ${e.cause?.code || e.message}`);
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ProviderError(`Gemini HTTP ${res.status}: ${text.slice(0, 400)}`);
+  }
+
+  let text = "";
+  let stopReason = null;
+  let usage = { input_tokens: 0, output_tokens: 0 };
+  const toolCalls = [];
+  const seenTools = new Set();
+
+  const sse = createSSE((ev) => {
+    const d = ev.data;
+    if (typeof d !== "object" || !d) return;
+    if (d.usageMetadata) {
+      usage.input_tokens = d.usageMetadata.promptTokenCount || usage.input_tokens;
+      usage.output_tokens = d.usageMetadata.candidatesTokenCount || usage.output_tokens;
+    }
+    const candidate = (d.candidates || [])[0];
+    if (!candidate) return;
+    if (candidate.finishReason) {
+      stopReason =
+        candidate.finishReason === "STOP" ? "end_turn" : candidate.finishReason === "MAX_TOKENS" ? "max_tokens" : candidate.finishReason.toLowerCase();
+    }
+    const parts = (candidate.content && candidate.content.parts) || [];
+    for (const part of parts) {
+      if (typeof part.text === "string" && part.text) {
+        text += part.text;
+        events.onText && events.onText(part.text);
+      } else if (part.functionCall && part.functionCall.name) {
+        const id = `call_gem_${++callCounter}_${toolCalls.length}`;
+        const rec = { id, name: part.functionCall.name, input: part.functionCall.args || {} };
+        if (!seenTools.has(id)) {
+          seenTools.add(id);
+          toolCalls.push(rec);
+          events.onToolStart && events.onToolStart(rec.name, rec.id);
+        }
+      }
+    }
+  });
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    sse.push(decoder.decode(value, { stream: true }));
+  }
+  sse.end();
+
+  return { text, toolCalls, stopReason, usage };
+}
+
+// Internal history → Gemini `contents` (role "user"/"model", parts arrays).
+// Consecutive same-role turns are merged (Gemini requires alternation; our
+// history has one assistant turn followed by N tool results).
+export function renderHistory(history) {
+  const contents = [];
+  const push = (role, parts) => {
+    if (!parts.length) return;
+    const last = contents[contents.length - 1];
+    if (last && last.role === role) {
+      last.parts.push(...parts);
+    } else {
+      contents.push({ role, parts });
+    }
+  };
+  for (const item of history) {
+    if (item.role === "user") {
+      push("user", [{ text: item.text }]);
+    } else if (item.role === "assistant") {
+      const parts = [];
+      if (item.text) parts.push({ text: item.text });
+      if (item.calls) {
+        for (const c of item.calls) {
+          parts.push({ functionCall: { name: c.name, args: c.args || c.input || {} } });
+        }
+      }
+      push("model", parts);
+    } else if (item.role === "tool") {
+      const parts = [
+        { functionResponse: { name: item.name, response: { result: item.result } } },
+      ];
+      if (item.image && item.image.base64) {
+        parts.push({ inlineData: { mimeType: item.image.mediaType || "image/png", data: item.image.base64 } });
+      }
+      push("user", parts);
+    }
+  }
+  return contents;
+}
+
+export function renderTools(tools) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: t.inputSchema || t.input_schema,
+  }));
+}

package/src/providers/groq.js

@@ -0,0 +1,16 @@
+// Groq — fast inference for open-weight models (Llama, Gemma, DeepSeek
+// distills). OpenAI-compatible, so this reuses the OpenAI streaming client
+// with provider-specific key/base. Free tier: ~1,000 req/day per model.
+// The key goes directly to api.groq.com (or cfg.groqBaseUrl for mocks).
+import { chatStream as openaiChatStream } from "./openai.js";
+
+export function chatStream(cfg, params, events = {}) {
+  const mapped = {
+    ...cfg,
+    openaiKey: cfg.groqKey,
+    openaiBaseUrl: cfg.groqBaseUrl || "https://api.groq.com/openai",
+  };
+  return openaiChatStream(mapped, { ...params, model: params.model }, events);
+}
+
+export { renderHistory, renderTools } from "./openai.js";

package/src/providers/openai.js

@@ -0,0 +1,138 @@
+// OpenAI Chat Completions — streaming (SSE) with function calling.
+// The API key goes directly to api.openai.com (or cfg.openaiBaseUrl).
+import { createSSE } from "../util.js";
+import { ProviderError } from "./anthropic.js";
+
+export async function chatStream(cfg, params, events = {}) {
+  const key = cfg.openaiKey;
+  if (!key) throw new ProviderError("No OpenAI API key. Run `roforge login` or set OPENAI_API_KEY.");
+  const msgs = renderHistory(params.messages);
+  if (params.system) msgs.unshift({ role: "system", content: params.system });
+  const body = {
+    model: params.model,
+    stream: true,
+    messages: msgs,
+  };
+  if (params.tools && params.tools.length) body.tools = renderTools(params.tools);
+
+  let res;
+  try {
+    res = await fetch(`${cfg.openaiBaseUrl}/v1/chat/completions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${key}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: params.signal,
+    });
+  } catch (e) {
+    throw new ProviderError(`network error calling OpenAI: ${e.cause?.code || e.message}`);
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ProviderError(`OpenAI HTTP ${res.status}: ${text.slice(0, 400)}`);
+  }
+
+  let text = "";
+  let stopReason = null;
+  let usage = { input_tokens: 0, output_tokens: 0 };
+  const toolCalls = [];
+
+  const sse = createSSE((ev) => {
+    const d = ev.data;
+    if (d === "[DONE]") return;
+    if (typeof d !== "object" || !d) return;
+    if (d.usage) usage = { ...usage, ...d.usage };
+    const choice = (d.choices || [])[0];
+    if (!choice) return;
+    const delta = choice.delta || {};
+    if (choice.finish_reason) stopReason = choice.finish_reason;
+    if (typeof delta.content === "string" && delta.content) {
+      text += delta.content;
+      events.onText && events.onText(delta.content);
+    }
+    if (delta.tool_calls) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index ?? 0;
+        if (!toolCalls[idx]) toolCalls[idx] = { id: "", name: "", input: {}, _json: "" };
+        const rec = toolCalls[idx];
+        if (tc.id) {
+          if (!rec.id) events.onToolStart && events.onToolStart(tc.function?.name || "tool", tc.id);
+          rec.id = tc.id;
+        }
+        if (tc.function && tc.function.name) rec.name = tc.function.name;
+        if (tc.function && tc.function.arguments) rec._json += tc.function.arguments;
+      }
+    }
+  });
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    sse.push(decoder.decode(value, { stream: true }));
+  }
+  sse.end();
+
+  const finalCalls = toolCalls
+    .filter(Boolean)
+    .map((rec) => {
+      try {
+        rec.input = rec._json ? JSON.parse(rec._json) : {};
+      } catch {
+        rec.input = {};
+      }
+      delete rec._json;
+      return { id: rec.id, name: rec.name, input: rec.input };
+    });
+
+  const normReason = stopReason === "tool_calls" ? "tool_use" : stopReason === "stop" ? "end_turn" : stopReason;
+  return { text, toolCalls: finalCalls, stopReason: normReason, usage };
+}
+
+export function renderHistory(history) {
+  const msgs = [];
+  for (const item of history) {
+    if (item.role === "user") {
+      msgs.push({ role: "user", content: item.text });
+    } else if (item.role === "assistant") {
+      const msg = { role: "assistant", content: item.text || "" };
+      if (item.calls && item.calls.length) {
+        msg.tool_calls = item.calls.map((c) => ({
+          id: c.id,
+          type: "function",
+          function: { name: c.name, arguments: JSON.stringify(c.args || c.input || {}) },
+        }));
+      }
+      msgs.push(msg);
+    } else if (item.role === "tool") {
+      msgs.push({ role: "tool", tool_call_id: item.id, content: item.result });
+      // OpenAI has no image in tool messages — attach a follow-up user
+      // message with an image_url data URI when the tool returned an image.
+      if (item.image && item.image.base64) {
+        const uri = `data:${item.image.mediaType || "image/png"};base64,${item.image.base64}`;
+        msgs.push({
+          role: "user",
+          content: [
+            { type: "text", text: `Image captured by tool ${item.name} (rendered from the Studio viewport):` },
+            { type: "image_url", image_url: { url: uri } },
+          ],
+        });
+      }
+    }
+  }
+  return msgs;
+}
+
+export function renderTools(tools) {
+  return tools.map((t) => ({
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.inputSchema || t.input_schema,
+    },
+  }));
+}

package/src/providers/openrouter.js

@@ -0,0 +1,17 @@
+// OpenRouter — one key, hundreds of models. OpenAI-compatible chat
+// completions, so this reuses the OpenAI streaming client with
+// provider-specific key/base. Free models use the ":free" suffix
+// (request-per-day limits, no billing). The key goes directly to
+// openrouter.ai (or cfg.openrouterBaseUrl for mocks).
+import { chatStream as openaiChatStream } from "./openai.js";
+
+export function chatStream(cfg, params, events = {}) {
+  const mapped = {
+    ...cfg,
+    openaiKey: cfg.openrouterKey,
+    openaiBaseUrl: cfg.openrouterBaseUrl || "https://openrouter.ai/api",
+  };
+  return openaiChatStream(mapped, { ...params, model: params.model }, events);
+}
+
+export { renderHistory, renderTools } from "./openai.js";

package/src/session.js

@@ -0,0 +1,192 @@
+// Session: wires config + provider + tools + UI events into a working agent.
+// Used by both the interactive TUI and the one-shot `roforge chat` mode.
+import { buildTools } from "./tools/index.js";
+import { runAgent } from "./agent.js";
+import * as Anthropic from "./providers/anthropic.js";
+import * as OpenAI from "./providers/openai.js";
+import * as Gemini from "./providers/gemini.js";
+import * as Groq from "./providers/groq.js";
+import * as OpenRouter from "./providers/openrouter.js";
+import { modelFor, estimateCost, effectiveProvider, PROVIDERS } from "./config.js";
+
+const PROVIDER_MODULES = { anthropic: Anthropic, openai: OpenAI, gemini: Gemini, groq: Groq, openrouter: OpenRouter };
+
+export class Session {
+  constructor({ cfg, cwd, bridgeServer, luauAnalyzePath, ui }) {
+    this.cfg = cfg;
+    this.cwd = cwd;
+    this.bridgeServer = bridgeServer;
+    this.luauAnalyzePath = luauAnalyzePath;
+    this.ui = ui; // { onText, onToolStart, onToolEnd, onInfo, onWarn, onStatus, promptApproval }
+    this.history = [];
+    this.tools = [];
+    this.studioInfo = { mcp: false, bridge: false, mcpToolCount: 0 };
+    this.aborted = false;
+    this._controller = null;
+    this.turns = 0;
+    this.totalUsage = { input_tokens: 0, output_tokens: 0 };
+    this._alwaysApprove = new Set();
+  }
+
+  get providerName() {
+    return effectiveProvider(this.cfg) || this.cfg.provider || "auto";
+  }
+  get provider() {
+    return PROVIDER_MODULES[this.providerName] || Anthropic;
+  }
+  get model() {
+    return this.cfg._activeModel || modelFor(this.cfg);
+  }
+
+  async init() {
+    const info = await buildTools({
+      cfg: this.cfg,
+      cwd: this.cwd,
+      bridgeServer: this.bridgeServer,
+      luauAnalyzePath: this.luauAnalyzePath,
+    });
+    this.tools = info.tools;
+    this.studioInfo = { mcp: info.mcp, bridge: info.bridge, mcpToolCount: info.mcpToolCount, mcpCapture: info.mcpCapture || [] };
+    this.cfg._activeModel = this.model;
+    return this.studioInfo;
+  }
+
+  systemPrompt() {
+    const studio = [];
+    if (this.studioInfo.mcp) studio.push(`Studio's built-in MCP server is connected (${this.studioInfo.mcpToolCount} tools, prefix "studio_").`);
+    if (this.studioInfo.bridge) studio.push("The RoForge Bridge plugin is available (forge_* tools) — it connects when Studio is open and the bridge plugin is active.");
+    const caps = (this.studioInfo.mcpCapture || []).map((n) => `studio_${n}`).join(", ");
+    if (caps) studio.push(`Studio's MCP exposes vision tools (${caps}) — they return an image you can SEE; prefer them for visual checks.`);
+    if (!studio.length) studio.push("No Studio connection yet — forge_* tools will error until Studio is open with the RoForge Bridge plugin (or enable Studio's built-in MCP beta).");
+
+    return `You are RoForge, a local AI agent for Roblox development, running on the user's machine (Claude-Code-style). You work on two surfaces:
+
+1. PROJECT FILES (on disk): the user's Rojo project in ${this.cwd}. Edit .lua/.json/.md files with project_read / project_edit / project_write, discover with project_tree / project_search, and run builds/checks with project_run (e.g. "rojo build -o dist/RoForge.rbxm"). This is the primary workflow for real development.
+2. LIVE STUDIO (when connected): inspect and modify the open place with forge_* tools (tree, read/write scripts, run Luau, screenshot).
+
+Rules:
+- Prefer inspecting before changing: project_tree / project_read / forge_read first.
+- When editing code, read the current content, then write the COMPLETE new file (project_write) or use project_edit for precise, unique replacements.
+- After project_write / project_edit, verify: re-read the file or run the analyzer (luau_analyze) / build (project_run) when that makes sense.
+- If a tool returns ERROR, read the message and adapt. Never repeat the exact same failing call.
+- Roblox specifics: current Luau (task.*, string methods, continue), current Roblox APIs, ServerScriptService vs ReplicatedStorage scoping, Rojo conventions.
+- Be concise. Show code only when the user asks or right after you wrote it.
+- You are local: no telemetry, no backend. Only the model provider sees your prompts.
+
+Current state:
+- Model: ${this.model} (${this.providerName}${PROVIDERS[this.providerName] && PROVIDERS[this.providerName].hasFreeTier && this.cfg.freeFirst !== false ? ", free tier" : ""})
+- ${studio.join(" ")}
+- Tools: ${this.tools.map((t) => t.name).join(", ")}`;
+  }
+
+  async send(userText) {
+    this.turns++;
+    this.aborted = false;
+    this._controller = new AbortController();
+    this.history.push({ role: "user", text: userText });
+
+    const usageBefore = { ...this.totalUsage };
+    const out = await runAgent(
+      this.cfg,
+      this.provider,
+      this.history,
+      this.systemPrompt(),
+      this.tools,
+      {
+        onText: (d) => this.ui.onText && this.ui.onText(d),
+        onAssistantDone: (text) => this.ui.onAssistantDone && this.ui.onAssistantDone(text),
+        onToolStart: (tool, args) => this.ui.onToolStart && this.ui.onToolStart(tool, args),
+        onToolEnd: (tool, args, result) => this.ui.onToolEnd && this.ui.onToolEnd(tool, args, result),
+        onIter: (n, total) => this.ui.onStatus && this.ui.onStatus(`thinking… (step ${n}/${total})`),
+        onUsage: (u) => {
+          this.totalUsage = u;
+        },
+        onDone: () => this.ui.onStatus && this.ui.onStatus("done"),
+        onAborted: () => this.ui.onInfo && this.ui.onInfo("aborted"),
+        onError: (msg) => this.ui.onWarn && this.ui.onWarn(msg),
+        shouldAbort: () => this.aborted,
+        abortSignal: this._controller.signal,
+        approve: (name, args) => {
+          if (this.cfg.approve === "yolo" || this._alwaysApprove.has(name)) return Promise.resolve(true);
+          if (this.ui.promptApproval) {
+            return this.ui.promptApproval(name, args).then((ok) => {
+              if (ok === "always") this.alwaysApprove(name);
+              return ok === true || ok === "always";
+            });
+          }
+          return Promise.resolve(true); // non-interactive fallback
+        },
+      }
+    );
+
+    if (out.ok) {
+      const est = estimateCost(this.cfg, this.totalUsage);
+      if (this.ui.onStatus) {
+        const delta = `↑${(this.totalUsage.input_tokens - usageBefore.input_tokens).toLocaleString()} ↓${(this.totalUsage.output_tokens - usageBefore.output_tokens).toLocaleString()} tok`;
+        this.ui.onStatus(`${delta}${est && est.cost != null ? `  ≈ $${est.cost.toFixed(4)}` : ""}`);
+      }
+    }
+    this._controller = null;
+    return out;
+  }
+
+  abort() {
+    this.aborted = true;
+    if (this._controller) this._controller.abort();
+  }
+
+  clear() {
+    this.history = [];
+  }
+
+  // Render the conversation as a Markdown transcript (for /save).
+  transcript() {
+    const lines = [
+      "# RoForge session transcript",
+      "",
+      `- Model: ${this.model} (${this.providerName})`,
+      `- Project: ${this.cwd}`,
+      `- Date: ${new Date().toISOString()}`,
+      `- Turns: ${this.turns}`,
+      `- Tokens: ↑${this.totalUsage.input_tokens} ↓${this.totalUsage.output_tokens}`,
+      "",
+      "---",
+      "",
+    ];
+    for (const item of this.history) {
+      if (item.role === "user") {
+        lines.push("## You", "", item.text, "");
+      } else if (item.role === "assistant") {
+        if (item.text) lines.push("## RoForge", "", item.text, "");
+        if (item.calls && item.calls.length) {
+          lines.push("### Tool calls");
+          for (const c of item.calls) {
+            let args = "{}";
+            try {
+              args = JSON.stringify(c.args || c.input || {});
+            } catch {
+              /* keep "{}" */
+            }
+            lines.push(`- ${c.name} \`${args}\``);
+          }
+          lines.push("");
+        }
+      } else if (item.role === "tool") {
+        let result = String(item.result ?? "");
+        if (result.length > 4000) {
+          result = result.slice(0, 4000) + `\n… [truncated ${result.length - 4000} chars]`;
+        }
+        lines.push(`### Tool result — ${item.name}`);
+        if (item.image) {
+          lines.push(`[image: ${item.image.mediaType || "image/png"}, ${item.image.base64.length} base64 chars — not inlined]`);
+        }
+        lines.push("```", result, "```", "");
+      }
+    }
+    return lines.join("\n");
+  }
+
+  alwaysApprove(name) {
+    this._alwaysApprove.add(name);
+  }
+}