@krmxd/onegpt 2.0.0-beta.1

package/src/agent.js

@@ -0,0 +1,763 @@
+"use strict";
+
+// Agent loop with small-model guardrails, in full parity with the Python
+// build: tool-call canonicalization, JSON-in-text extraction, repeat-loop
+// breaking, self-correction nudges and automatic "Done - ..." summaries.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { getConfig } = require("./config");
+const { getSharedProvider } = require("./ollama");
+const { ToolRegistry } = require("./tools");
+
+const TOOL_RE = /\x00TOOL:([^:]*):([^:]*):(.*?)\x00/g;
+const USAGE_RE = /\x00USAGE:(.*?)\x00/;
+
+// Identity rules appended to every system prompt so the assistant always
+// presents itself as the OGPT product/model - never as an underlying engine.
+const IDENTITY_BLOCK = [
+  "",
+  "",
+  "Identity (follow strictly):",
+  "- You are OGPT, an AI coding assistant created by KareemXD, and you are currently running as {name}.",
+  "- When asked who you are, what model you are, what you run on, or anything similar, answer briefly, naturally and confidently in one sentence, e.g. \"I'm using {name}.\"",
+  "- Never reveal, confirm, or discuss any underlying engine, provider, base model, framework, or company behind you. If pressed, simply and politely repeat that you are {name}.",
+  "- Never claim to be a different product and never deny being OGPT.",
+].join("\n");
+
+// Deterministic answers for identity questions. Small local models often
+// imitate stale (wrong) answers from restored history instead of following the
+// system prompt, so these questions are answered directly - instantly and
+// correctly - without a round-trip through the model.
+const IDENTITY_REPLIES = [
+  [/\bwho\s+(?:made|created|built|developed|trained)\s+you\b/i, "creator"],
+  [/\bare\s+you\s+(?:chatgpt|gpt[\s-]?\d*|openai'?s?|qwen|claude|gemini|llama|deepseek|mistral|grok|kimi|copilot)\b/i, "other"],
+  [/\b(?:what|which)\s+model\s+(?:are\s+you|do\s+you\s+(?:use|run)|are\s+you\s+using|runs?\s+you|powers?\s+you|is\s+(?:behind|under)\s+you)\b/i, "model"],
+  [/\bwhat\s+(?:are|is)\s+you\s+(?:running|using|built\s+on|trained\s+on|based\s+on)\b/i, "model"],
+  [/\b(?:what|which)(?:'s| is|'re| are)\s+your\s+(?:model|engine|llm|ai)\b/i, "model"],
+  [/\byour\s+(?:model|engine|llm)\b/i, "model"],
+  [/\bwho\s+are\s+you\b|\bwhat\s+are\s+you\b(?!\s*(?:doing|up\s+to|waiting|talking|typing))/i, "self"],
+];
+
+// Requests like "write a poem about who created you" are NOT identity questions.
+const CREATIVE_RE = /\b(?:poem|poems|story|stories|song|songs|essay|joke|jokes|lyrics|haiku|rap|fiction|character|script)\b/i;
+
+// Pure greetings get a deterministic friendly reply - tiny local models
+// otherwise over-apply the identity rules and answer plain "hi" with
+// "I'm using <model>".
+const GREETING_RE = /^\s*(?:hey+|hi+|hello+|yo|sup|howdy|hola|good\s+(?:morning|afternoon|evening)|what'?s?\s+up)\s*[!,.?~]*\s*$/i;
+
+function identityReply(userInput, name) {
+  if (GREETING_RE.test(userInput)) {
+    return `Hey! I'm ${name} - ready when you are. What are we working on?`;
+  }
+  if (CREATIVE_RE.test(userInput)) return null;
+  let kind = null;
+  for (const [rx, k] of IDENTITY_REPLIES) {
+    if (rx.test(userInput)) { kind = k; break; }
+  }
+  if (!kind) return null;
+  if (kind === "creator") return `I was created by KareemXD. I'm ${name}, OGPT's built-in coding assistant.`;
+  if (kind === "other") return `No - I'm ${name}, OGPT's own coding assistant, built by KareemXD.`;
+  if (kind === "self") return `I'm ${name}, the OGPT AI coding assistant. How can I help you today?`;
+  return `I'm using ${name}.`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool-use rules appended to every system prompt. Without them small local
+// models tend to describe or print code instead of actually creating files.
+const TOOL_GUIDANCE = (
+  "\n\nWorking style (follow strictly):\n" +
+  "- Your working directory is {cwd}. Create files THERE using RELATIVE paths " +
+  "(e.g. 'app.py' or 'src/app.py'). NEVER invent absolute locations like " +
+  "'/home/user/...' or '/Users/...' - they do not exist on this machine.\n" +
+  "- Tool arguments are REAL values: 'path': 'my_folder/app.py'. Never send the " +
+  "parameter schema ({'type': 'string'}) as a value, and never leave arguments empty.\n" +
+  "- To act, output plain JSON tool calls (never shell commands in code fences):\n" +
+  '{"name": "write_file", "arguments": {"path": "widgets/gadget.py", ' +
+  '"content": "print(\'hi\')"}}\n' +
+  "- When the user asks you to create, build, write, save or fix anything that lives in " +
+  "files, DO IT with your tools instead of only printing code.\n" +
+  "- Build EXACTLY what the user asked for: filenames and file types must match the " +
+  "request (an 'index.html' request means a file named index.html containing real HTML), " +
+  "and every file must be complete and working - never placeholders, never unrelated " +
+  "boilerplate, never code dumped only in chat.\n" +
+  "- write_file creates a file AND all missing parent folders automatically, so a separate " +
+  "make_dir call is usually unnecessary - just call write_file with the full path.\n" +
+  "- Complete EVERY part of the request before replying. If asked for a folder and files " +
+  "inside it, make all the tool calls in one turn: one write_file per file.\n" +
+  "- Never stop halfway: after each tool result, continue with the next step until the " +
+  "whole task is done. Never rewrite a file that already has the exact right content - " +
+  "when everything is written, reply with a short summary instead of calling tools again.\n" +
+  "- NEVER give the user instructions like 'you can use write_file', 'save this as...' or " +
+  "'run this command'. You are the one holding the tools - act immediately and silently " +
+  "execute the work yourself.\n" +
+  "- Use edit_file with the exact old text snippet when changing existing files.\n" +
+  "- Afterwards reply briefly with what you created or changed."
+);
+
+// Self-correction patterns: requests like "create a folder and a file" MUST end
+// in real file operations. Small local models love to answer with instructions
+// instead of acting; these detect both sides so the agent can give itself one
+// firm follow-up round and actually execute the task.
+const TASK_RE = new RegExp(
+  "\\b(create|make|build|write|add|generate|scaffold|implement|fix|update)\\b" +
+  "[^\\n]{0,120}?\\b(file|files|folder|folders|directory|dir|script|module|" +
+  "app|component|config|readme|tests?)\\b", "i");
+const QUESTION_RE = new RegExp(
+  "^\\s*(how|what|why|when|where|which|who|whom|can you (?:tell|explain)|" +
+  "explain|describe|list|is|are|does|do)\\b", "i");
+const SLOTH_RE = new RegExp(
+  "(you (?:can|could|may|might want to|might wanna|should) (?:\\w+ )?" +
+  "(?:use|create|make|run|write|save|place|put|execute)" +
+  "|here(?:'s| is) how|to (?:create|make|write)[^\\n]{0,60}(?:use|run|type)" +
+  "|use (?:the )?(?:provided )?\\w* ?tool" +
+  "|i (?:cannot|can't|won't) (?:create|write|make)" +
+  "|follow these steps|step \\d)", "i");
+
+const EXECUTE_NUDGE =
+  "[auto-correction] Your previous reply gave instructions instead of acting. " +
+  "You hold the tools and have permission - EXECUTE the original request yourself NOW: " +
+  "output bare JSON tool calls (NOT shell commands, NOT explanations). Exact shape:\n" +
+  '{"name": "write_file", "arguments": {"path": "<folder>/<file>.py", ' +
+  '"content": "<complete file text>"}}\n' +
+  "Do not tell the user to do anything.";
+
+function wantsAction(userInput) {
+  // True when the user asked for something to be built (not explained).
+  return TASK_RE.test(userInput) && !QUESTION_RE.test(userInput.trim());
+}
+
+function redirectMsg(task) {
+  // Loop-break redirect: push the model to the NEXT steps with a concrete
+  // call example (tiny models need shapes, not descriptions).
+  const example = '{"name": "write_file", "arguments": ' +
+    '{"path": "<folder>/<file>.py", "content": "<complete file text>"}}';
+  return "[auto-correction] That exact call already succeeded - do NOT repeat it. " +
+    `Continue the ORIGINAL request ("${task}") with the NEXT steps now: ` +
+    "write every still-missing file via write_file, one call per file, " +
+    "with real relative paths and the FULL content. Example of the exact shape:\n" +
+    `${example}\n` +
+    "When everything exists, reply briefly.";
+}
+
+function repliedWithoutActing(reply) {
+  // True when a reply looks like instructions/code instead of done work.
+  return SLOTH_RE.test(reply) || reply.includes("```");
+}
+
+// "Created the folder." style announcements. Harmless on their own, but a
+// red flag when the request named files that were never actually created
+// (e.g. 'a folder AND an index.html' - folder done, file skipped).
+const ANNOUNCE_RE = /^\s*(?:ok(?:ay)?|done|created|made|added|all\s+set|i'?ve?\s+(?:created|made|added))\b/i;
+
+const ARTIFACT_FILE_RE = /\b[\w./\\~-]*[\w.-]+\.(?:html?|css|jsx?|tsx?|py|json|md|txt|sh|ya?ml|csv)\b/gi;
+
+function namedFiles(userInput) {
+  const seen = new Map();
+  for (const m of userInput.matchAll(ARTIFACT_FILE_RE)) {
+    const name = m[0].replace(/[`"']/g, "").replace(/\\/g, "/");
+    if (name && !seen.has(name.toLowerCase())) seen.set(name.toLowerCase(), name);
+  }
+  return [...seen.values()];
+}
+
+function artifactExists(name) {
+  // Does the requested file exist (cwd-relative, case-insensitive fallback)?
+  try {
+    const p = expandHome(name);
+    if (fs.existsSync(p)) return true;
+    const dir = path.dirname(p);
+    if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+      return fs.readdirSync(dir).some((f) => f.toLowerCase() === path.basename(p).toLowerCase());
+    }
+  } catch {}
+  return false;
+}
+
+function stalledHalfway(reply, userInput, doneOutputs) {
+  // A named file counts as done when the exact path exists OR the completed
+  // tool outputs already produced that file name (covers requests like
+  // 'a folder and an index.html inside it' where write_file made the full
+  // path in one step).
+  const t = reply.trim();
+  if (!t || t.length > 160 || t.includes("```")) return false;
+  if (!ANNOUNCE_RE.test(t)) return false;
+  const bits = (doneOutputs || []).join(" ").toLowerCase();
+  return namedFiles(userInput).some((n) => {
+    const base = path.basename(n).toLowerCase();
+    if (base && bits.includes(base)) return false;
+    return !artifactExists(n);
+  });
+}
+
+function expandHome(p) {
+  return String(p).replace(/^~(?=$|\/)/, os.homedir());
+}
+
+// Intent-level signature of a tool-call batch (repeat-loop detection).
+// Paths are resolved to absolute form so 'make_dir widgets' and
+// 'make_dir /cwd/widgets' count as the SAME action - tiny models switch
+// path styles instead of moving on to the next step.
+function callSig(calls) {
+  const out = [];
+  for (const tc of calls) {
+    const args = tc.arguments || {};
+    const norm = Object.keys(args).sort().map((k) => {
+      let v = args[k];
+      if (k === "path" && typeof v === "string" && !v.includes("\n")) {
+        // Python's os.path.realpath resolves nonexistent paths lexically;
+        // fs.realpathSync throws - so resolve lexically first, then refine
+        // symlinks via the (almost always existing) parent directory.
+        const abs = path.resolve(expandHome(v.trim()));
+        try {
+          v = fs.realpathSync(path.dirname(abs)) + path.sep + path.basename(abs);
+        } catch {
+          v = abs;
+        }
+      }
+      return [k, String(v)];
+    });
+    out.push(`${tc.name}(${norm.map((kv) => kv.join("=")).join(",")})`);
+  }
+  return out.sort().join(";;");
+}
+
+// Catch tool calls the model printed as bare JSON text instead of using the
+// native tool_calls channel (very common with tiny models).
+function extractJsonTools(text) {
+  const calls = [];
+  const spans = [];
+  if (!text || text.indexOf('"arguments"') === -1) return { clean: text || "", calls };
+  let i = 0;
+  while ((i = text.indexOf("{", i)) !== -1 && calls.length < 8) {
+    let depth = 0, inStr = false, esc = false;
+    for (let j = i; j < text.length && j < i + 20000; j++) {
+      const c = text[j];
+      if (inStr) {
+        if (esc) esc = false;
+        else if (c === "\\") esc = true;
+        else if (c === '"') inStr = false;
+        continue;
+      }
+      if (c === '"') inStr = true;
+      else if (c === "{") depth++;
+      else if (c === "}") {
+        depth--;
+        if (depth === 0) {
+          try {
+            const obj = JSON.parse(text.slice(i, j + 1));
+            if (obj && typeof obj.name === "string"
+                && obj.arguments && typeof obj.arguments === "object"
+                && !Array.isArray(obj.arguments)) {
+              spans.push([i, j + 1]);
+              calls.push({
+                id: `tc_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                name: obj.name,
+                arguments: obj.arguments,
+              });
+            }
+          } catch {}
+          i = j;
+          break;
+        }
+      }
+    }
+    i++;
+  }
+  let clean = "";
+  let pos = 0;
+  for (const [s, e] of spans) {
+    clean += text.slice(pos, s);
+    pos = e;
+  }
+  clean += text.slice(pos);
+  return { clean, calls };
+}
+
+// ---------------------------------------------------------------------------
+// Code blocks in chat: after every successful write/edit, surface the written
+// file as a fenced code block right inside the conversation.
+const MAX_PREVIEW_CHARS = 3000;
+
+const LANG_BY_EXT = {
+  py: "python", js: "javascript", mjs: "javascript", cjs: "javascript",
+  ts: "typescript", tsx: "typescript", jsx: "javascript", html: "html",
+  htm: "html", css: "css", json: "json", md: "markdown", sh: "bash",
+  bash: "bash", zsh: "bash", yml: "yaml", yaml: "yaml", c: "c", cpp: "cpp",
+  h: "cpp", java: "java", go: "go", rs: "rust", rb: "ruby", php: "php",
+  sql: "sql", xml: "xml", toml: "toml",
+};
+
+function detectLang(filePath) {
+  const ext = path.extname(String(filePath)).slice(1).toLowerCase();
+  return LANG_BY_EXT[ext] || "";
+}
+
+function snapshot(tc) {
+  // Read the target file before a write/edit ("" = did not exist).
+  const p = String(tc.arguments?.path || "").trim();
+  if (!p || !["write_file", "edit_file"].includes(tc.name)) return null;
+  try {
+    const fp = expandHome(p);
+    return fs.existsSync(fp) ? fs.readFileSync(fp, "utf-8") : "";
+  } catch {
+    return null;
+  }
+}
+
+function codeEvent(tc, pre) {
+  // Build an opencode-style code event after a successful write/edit.
+  if (pre === null) return null;
+  const p = String(tc.arguments?.path || "").trim();
+  if (!p) return null;
+  if (tc.name === "write_file") {
+    const content = String(tc.arguments?.content ?? "");
+    if (content.length > MAX_PREVIEW_CHARS || pre.length > MAX_PREVIEW_CHARS) return null;
+    return { path: p, content, action: pre ? "UPDATED" : "CREATED" };
+  }
+  if (tc.name === "edit_file") {
+    try {
+      const fp = expandHome(p);
+      const post = fs.existsSync(fp) ? fs.readFileSync(fp, "utf-8") : "";
+      if (post.length > MAX_PREVIEW_CHARS || pre.length > MAX_PREVIEW_CHARS) return null;
+      return { path: p, content: post, old_content: pre, action: "EDITED" };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// Minimal unified diff (-/+ lines) good enough for chat previews.
+function diffLines(oldStr, newStr) {
+  const a = oldStr.split("\n"), b = newStr.split("\n");
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length, endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) { endA--; endB--; }
+  const out = ["@@ -" + (start + 1) + " +" + (start + 1) + " @@"];
+  for (let i = start; i < endA; i++) out.push("-" + a[i]);
+  for (let i = start; i < endB; i++) out.push("+" + b[i]);
+  return out;
+}
+
+function codeMarkdown(ev) {
+  if (ev.action === "EDITED" && ev.old_content !== undefined) {
+    return "```diff\n" + diffLines(ev.old_content, ev.content).join("\n") + "\n```";
+  }
+  const lang = detectLang(ev.path);
+  return "```" + lang + "\n" + ev.content + "\n```";
+}
+
+class Agent {
+  constructor(options = {}) {
+    this.cfg = options.config || getConfig();
+    this.tools = options.tools || new ToolRegistry();
+    this.host = options.host || this.cfg.get("ollama.host", "http://localhost:11434");
+    this.history = [];
+    this.maxRounds = this.cfg.get("agent.max_rounds", 25);
+    this.temperature = this.cfg.get("agent.temperature", 0.7);
+    this.maxTokens = this.cfg.get("agent.max_tokens", 4096);
+    this.usage = { prompt: 0, completion: 0, total: 0 };
+    this._cancelled = false;
+    this.lastRun = {};
+  }
+
+  _systemPrompt() {
+    // The base prompt may contain an {ogpt_model} placeholder that is replaced
+    // with the active model's oGPT display name (e.g. oGPT-1a). The identity
+    // block is always appended so the assistant never exposes the underlying
+    // engine, even if an older prompt is set in the user's config.
+    const base =
+      this.cfg.get("agent.system_prompt", "") ||
+      "You are OGPT, an expert AI coding assistant running as {ogpt_model}.";
+    let name = "OGPT";
+    try {
+      name = this.cfg.displayName() || "OGPT";
+    } catch {}
+    const cwd = process.cwd();
+    return (
+      base.split("{ogpt_model}").join(name)
+      + IDENTITY_BLOCK.split("{name}").join(name)
+      + TOOL_GUIDANCE.split("{cwd}").join(cwd)
+    );
+  }
+
+  get provider() {
+    if (this._provider) return this._provider;
+    const { getSharedProvider } = require("./ollama");
+    return getSharedProvider(this.host);
+  }
+
+  set provider(p) {
+    this._provider = p;
+  }
+
+  _autoCompact() {
+    if (!this.cfg.get("agent.auto_compact", true)) return;
+    const keep = parseInt(this.cfg.get("agent.auto_compact_keep", 8), 10);
+    const threshold = parseInt(this.cfg.get("agent.auto_compact_after", 24), 10);
+    if (this.history.length < threshold) return;
+    const old = this.history.slice(0, -keep);
+    const recent = this.history.slice(-keep);
+    const summary = old
+      .filter((m) => m.role !== "tool" && m.content)
+      .map((m) => `${m.role}: ${m.content.slice(0, 200)}`)
+      .join("\n");
+    if (!summary) return;
+    this.history = [{ role: "user", content: `[Conversation summary]\n${summary}` }, ...recent];
+  }
+
+  _identityName() {
+    try {
+      return this.cfg.displayName() || "OGPT";
+    } catch {
+      return "OGPT";
+    }
+  }
+
+  _maybeIdentity(userInput) {
+    return identityReply(userInput, this._identityName());
+  }
+
+  async run(userInput) {
+    this._cancelled = false;
+    this._autoCompact();
+    const canned = this._maybeIdentity(userInput);
+    if (canned !== null) {
+      this.history.push({ role: "user", content: userInput, ts: Date.now() / 1000 });
+      this.history.push({ role: "assistant", content: canned, ts: Date.now() / 1000 });
+      return canned;
+    }
+    this.history.push({ role: "user", content: userInput, ts: Date.now() / 1000 });
+    let full = "";
+    let rounds = 0;
+    let nudges = 0;
+    let lastSig = null;
+    let loopBreaks = 0;
+    const doneBits = [];
+
+    while (rounds < this.maxRounds && !this._cancelled) {
+      rounds++;
+      const model = this.cfg.activeModel();
+      const resp = await this.provider.chat(this.history, model, {
+        tools: this.tools.definitions(),
+        system: this._systemPrompt(),
+        temperature: this.temperature,
+        maxTokens: this.maxTokens,
+      });
+      this.usage.prompt += resp.usage.prompt;
+      this.usage.completion += resp.usage.completion;
+      this.usage.total += resp.usage.total;
+
+      // catch tool calls the model printed as JSON text
+      const extracted = extractJsonTools(resp.content);
+      const cleanContent = extracted.clean;
+      const allCalls = [...(resp.toolCalls || []), ...extracted.calls];
+      for (const tc of allCalls) this.tools.prepareCall(tc);
+
+      if (allCalls.length) {
+        const sig = callSig(allCalls);
+        if (lastSig !== null && sig === lastSig) {
+          // Degenerate repeat-loop: first time, redirect it forward;
+          // second time, close the run out.
+          this.history.push({ role: "assistant", content: cleanContent.trim(), ts: Date.now() / 1000 });
+          if (loopBreaks < 1) {
+            loopBreaks++;
+            full += "\n· continuing the task after a repeated step…\n";
+            this.history.push({ role: "user", content: redirectMsg(userInput) });
+            continue;
+          }
+          full += "\n· same action repeated - finishing up\n";
+          break;
+        }
+        lastSig = sig;
+        this.history.push({ role: "assistant", content: cleanContent, toolCalls: allCalls, ts: Date.now() / 1000 });
+        if (cleanContent.trim()) full += cleanContent;
+        const seenRound = new Set();
+        for (const tc of allCalls) {
+          const s = callSig([tc]);
+          if (seenRound.has(s)) {
+            // identical call twice in ONE turn - execute once only
+            this.history.push({
+              role: "tool",
+              content: "Skipped - the exact same call was already made in this turn.",
+              toolCallId: tc.id,
+            });
+            continue;
+          }
+          seenRound.add(s);
+          const pre = snapshot(tc);
+          const result = await this.tools.execute(tc);
+          this.history.push({ role: "tool", content: result.content, toolCallId: tc.id });
+          if (!result.success) {
+            full += `\n[Error: ${result.error}]\n`;
+          } else {
+            doneBits.push(result.output.split("\n")[0].slice(0, 90));
+            const ev = codeEvent(tc, pre);
+            if (ev) full += (full.trim() ? "\n\n" : "") + codeMarkdown(ev);
+          }
+        }
+      } else {
+        lastSig = null;
+        full += resp.content;
+        this.history.push({ role: "assistant", content: resp.content, ts: Date.now() / 1000 });
+        // Self-correction: instructions/code instead of done work gets one
+        // firm push to act - on ANY round, not just the first (tiny models
+        // relapse into how-to mode mid-task). An EMPTY reply after partial
+        // work means it stalled - push it too.
+        const replyLazy = repliedWithoutActing(resp.content);
+        const wentSilent = !resp.content.trim() && (rounds > 1 || doneBits.length > 0);
+        if (nudges < 3 && !this._cancelled
+            && wantsAction(userInput) && (replyLazy || wentSilent || stalledHalfway(resp.content, userInput, doneBits))) {
+          nudges++;
+          this.history.push({ role: "user", content: redirectMsg(userInput) });
+          continue;
+        }
+        break;
+      }
+    }
+
+    // Models that only emit tool JSON never write a closing line - make sure
+    // the user still sees what happened.
+    if (doneBits.length && !full.trim()) {
+      const summary = "Done - " + [...new Set(doneBits)].join(" · ");
+      full += summary;
+      this.history.push({ role: "assistant", content: summary, ts: Date.now() / 1000 });
+    }
+
+    return full;
+  }
+
+  async *runStream(userInput) {
+    this._cancelled = false;
+    this._autoCompact();
+    const canned = this._maybeIdentity(userInput);
+    if (canned !== null) {
+      this.history.push({ role: "user", content: userInput, ts: Date.now() / 1000 });
+      this.history.push({ role: "assistant", content: canned, ts: Date.now() / 1000 });
+      yield canned;
+      return;
+    }
+    this.history.push({ role: "user", content: userInput, ts: Date.now() / 1000 });
+    let rounds = 0;
+    let nudges = 0;
+    const tStart = Date.now();
+    let ttft = 0;
+    let nTokens = 0;
+    this.lastRun = {};
+    let lastSig = null;
+    let loopBreaks = 0;
+    const doneBits = [];
+    let sawText = false;
+    let lastUsage = { prompt: 0, completion: 0, total: 0 };
+
+    while (rounds < this.maxRounds && !this._cancelled) {
+      rounds++;
+      const model = this.cfg.activeModel();
+      const contentParts = [];
+      const toolCalls = [];
+      let usage = { prompt: 0, completion: 0, total: 0 };
+
+      try {
+        for await (const chunk of this.provider.stream(this.history, model, {
+          tools: this.tools.definitions(),
+          system: this._systemPrompt(),
+          temperature: this.temperature,
+          maxTokens: this.maxTokens,
+        })) {
+          if (chunk.type === "text") {
+            contentParts.push(chunk.text);
+            if (!ttft) ttft = Date.now() - tStart;
+            nTokens++;
+            sawText = true;
+            yield chunk.text;
+          } else if (chunk.type === "tool") {
+            toolCalls.push(chunk);
+          } else if (chunk.type === "usage") {
+            usage = chunk.usage;
+          } else if (chunk.type === "error") {
+            yield `\n[Error: ${chunk.error}]\n`;
+            return;
+          }
+        }
+      } catch (e) {
+        yield `\n[Error: ${e.message}]\n`;
+        return;
+      }
+
+      const full = contentParts.join("");
+      this.usage.prompt += usage.prompt;
+      this.usage.completion += usage.completion;
+      this.usage.total += usage.total;
+      lastUsage = usage;
+
+      // catch tool calls the model printed as JSON text
+      const extracted = extractJsonTools(full);
+      const allCalls = [...toolCalls, ...extracted.calls];
+      for (const tc of allCalls) this.tools.prepareCall(tc);
+
+      if (allCalls.length) {
+        const sig = callSig(allCalls);
+        if (lastSig !== null && sig === lastSig) {
+          // Degenerate repeat-loop: first time, redirect it forward;
+          // second time, close the run out.
+          this.history.push({ role: "assistant", content: extracted.clean.trim(), toolCalls: allCalls });
+          if (loopBreaks < 1) {
+            loopBreaks++;
+            yield "\n· continuing the task after a repeated step…\n";
+            this.history.push({ role: "user", content: redirectMsg(userInput) });
+            continue;
+          }
+          yield "\n· same action repeated - finishing up\n";
+          break;
+        }
+        lastSig = sig;
+        this.history.push({ role: "assistant", content: extracted.clean, toolCalls: allCalls });
+        const seenRound = new Set();
+        for (const tc of allCalls) {
+          const s = callSig([tc]);
+          if (seenRound.has(s)) {
+            // identical call twice in ONE turn - execute once only
+            this.history.push({
+              role: "tool",
+              content: "Skipped - the exact same call was already made in this turn.",
+              toolCallId: tc.id,
+            });
+            continue;
+          }
+          seenRound.add(s);
+          yield `\n[Tool: ${tc.name}]\n`;
+          const pre = snapshot(tc);
+          const result = await this.tools.execute(tc);
+          this.history.push({ role: "tool", content: result.content, toolCallId: tc.id });
+          if (!result.success) {
+            yield `[Error: ${result.error}]\n`;
+          } else {
+            const firstLine = result.output.split("\n")[0];
+            doneBits.push(firstLine.slice(0, 90));
+            // File writes surface their result line (path + lines + size).
+            if (tc.name === "write_file" || tc.name === "edit_file") {
+              yield `\n\u2713 ${firstLine}\n`;
+            }
+            const ev = codeEvent(tc, pre);
+            if (ev) yield "\n" + codeMarkdown(ev) + "\n";
+          }
+        }
+      } else {
+        lastSig = null;
+        this.history.push({ role: "assistant", content: full, ts: Date.now() / 1000 });
+        // Self-correction: instructions/code instead of done work gets one
+        // firm push to act - on ANY round, not just the first (tiny models
+        // relapse into how-to mode mid-task). An EMPTY reply after partial
+        // work means it stalled - push it too.
+        const replyLazy = repliedWithoutActing(full);
+        const wentSilent = !full.trim() && (rounds > 1 || doneBits.length > 0);
+        if (nudges < 3 && !this._cancelled
+            && wantsAction(userInput) && (replyLazy || wentSilent || stalledHalfway(full, userInput, doneBits))) {
+          nudges++;
+          yield "\n";
+          this.history.push({ role: "user", content: redirectMsg(userInput) });
+          continue;
+        }
+        break;
+      }
+    }
+
+    // Models that only emit tool JSON never write a closing line - make sure
+    // the user still sees what happened.
+    if (doneBits.length && !sawText) {
+      const summary = "Done - " + [...new Set(doneBits)].join(" · ");
+      yield summary;
+      this.history.push({ role: "assistant", content: summary, ts: Date.now() / 1000 });
+    }
+
+    const duration = (Date.now() - tStart) / 1000;
+    const tokens = lastUsage && lastUsage.completion ? lastUsage.completion : nTokens;
+    this.lastRun = {
+      rounds,
+      ttft: Math.round(ttft / 100) / 10,
+      duration: Math.round(duration * 100) / 100,
+      tokens,
+      tps: duration > 0 && tokens ? Math.round((tokens / duration) * 10) / 10 : 0,
+      promptTokens: lastUsage ? lastUsage.prompt : 0,
+    };
+  }
+
+  finalizeInterrupted(partial) {
+    partial = (partial || "").trim();
+    if (partial) this.history.push({ role: "assistant", content: partial, ts: Date.now() / 1000 });
+  }
+
+  undo() {
+    if (!this.history.length) return false;
+    while (this.history.length && this.history[this.history.length - 1].role === "tool") {
+      this.history.pop();
+    }
+    if (this.history.length && this.history[this.history.length - 1].role === "assistant") {
+      this.history.pop();
+    }
+    if (this.history.length && this.history[this.history.length - 1].role === "user") {
+      this.history.pop();
+    }
+    return true;
+  }
+
+  retry() {
+    if (!this.history.length) return null;
+    while (this.history.length && this.history[this.history.length - 1].role === "tool") {
+      this.history.pop();
+    }
+    if (this.history.length && this.history[this.history.length - 1].role === "assistant") {
+      this.history.pop();
+    }
+    let lastUser = null;
+    for (let i = this.history.length - 1; i >= 0; i--) {
+      const m = this.history[i];
+      if (m.role === "user" && !m.content.startsWith("[Conversation summary]") && !m.content.startsWith("[auto-correction]")) {
+        lastUser = m.content;
+        break;
+      }
+    }
+    if (lastUser === null) return null;
+    while (this.history.length) {
+      const m = this.history.pop();
+      if (m.role === "user" && m.content === lastUser) break;
+    }
+    return lastUser;
+  }
+
+  cancel() {
+    this._cancelled = true;
+  }
+
+  clear() {
+    this.history = [];
+    this.usage = { prompt: 0, completion: 0, total: 0 };
+  }
+
+  compact(keep = 4) {
+    if (this.history.length <= keep) return 0;
+    const old = this.history.slice(0, -keep);
+    const recent = this.history.slice(-keep);
+    const summary = old
+      .filter((m) => m.role !== "tool" && m.content)
+      .map((m) => `${m.role}: ${m.content.slice(0, 200)}`)
+      .join("\n");
+    this.history = [{ role: "user", content: `[Conversation summary]\n${summary}` }, ...recent];
+    return old.length;
+  }
+
+  stats() {
+    return {
+      messages: this.history.length,
+      totalTokens: this.usage.total,
+      promptTokens: this.usage.prompt,
+      completionTokens: this.usage.completion,
+    };
+  }
+}
+
+module.exports = { Agent };