agent-from-zero 0.5.0 → 0.27.0

package/dist/loop.js

@@ -3,11 +3,14 @@ import ora from "ora"; // the "thinking..." spinner while waiting for the first
 import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
+import { previewChange } from "./diff.js"; // show the diff before a write so approval is informed
 import { estimateHistoryTokens, compactHistory, COMPACT_AT, MAX_COMPACTIONS_PER_QUERY, MAX_COMPACT_FAILURES } from "./context.js"; // context management
 import { SUB_AGENT_PROMPT } from "./prompt.js"; // the sub-agent's own constitution
 import { emit } from "./telemetry.js"; // local-only event log (no-op unless the CLI armed it)
 import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop)
-export const MAX_ROUNDS = 15; // model→tool round cap per query
+import { recordUsage } from "./cost.js"; // meter token usage from the stream
+import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
+import { printToolSummary } from "./tui.js"; // collapsible tool output
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
 export const MAX_RATE_LIMIT_RETRIES = 3; // 429s get their own, much smaller budget
 export const MAX_CONSECUTIVE_FAILURES = 3; // the circuit breaker
@@ -20,7 +23,6 @@ const STALL_WARN_MS = 30_000; // events arriving slowly → log only. Slow is no
 export var TerminateReason;
 (function (TerminateReason) {
     TerminateReason["Done"] = "done";
-    TerminateReason["RoundCap"] = "round_cap";
     TerminateReason["CircuitBreaker"] = "circuit_breaker";
     TerminateReason["RetryBudgetExhausted"] = "retry_budget_exhausted";
     TerminateReason["RateLimitBudgetExhausted"] = "rate_limit_budget_exhausted";
@@ -29,6 +31,12 @@ export var TerminateReason;
     TerminateReason["FatalApiError"] = "fatal_api_error";
     TerminateReason["UserInterrupt"] = "user_interrupt";
 })(TerminateReason || (TerminateReason = {}));
+// Which model should a delegated sub-agent run on? The configured sub-agent
+// model if set and non-blank, otherwise the same model as the orchestrator.
+// Pulled out as a pure function so the tiering rule is testable on its own.
+export function subAgentModelFor(opts) {
+    return opts.subAgentModel?.trim() || opts.model;
+}
 // The task tool: the parent's handle on sub-agents. Defined here (not in
 // tools.ts) because running it needs the loop itself — it IS a loop.
 const taskTool = {
@@ -49,19 +57,53 @@ On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a
         },
     },
 };
+// The ask_user tool: the model's handle on the user. When it needs the human to
+// choose between options, it calls this instead of asking in prose — and gets
+// back clean, structured selections rather than a free-text paragraph to parse.
+const askUserTool = {
+    type: "function",
+    function: {
+        name: "ask_user",
+        description: `Ask the user one or more multiple-choice questions and get back their selections. Use this WHENEVER you need the user to make a decision between options (which approach, which file, yes/no/which) — it is easier for them to pick than to type, and the answers come back unambiguous.
+Provide each question with 2–4 concrete options. Do NOT use it for open-ended input that has no clear options; ask in prose for that.
+If the user cancels, you'll be told — then proceed with your best judgment or ask again.`,
+        parameters: {
+            type: "object",
+            properties: {
+                questions: {
+                    type: "array",
+                    description: "The questions to ask, each with a list of options",
+                    items: {
+                        type: "object",
+                        properties: {
+                            question: { type: "string", description: "The question text" },
+                            options: { type: "array", items: { type: "string" }, description: "2–4 concrete choices" },
+                        },
+                        required: ["question", "options"],
+                    },
+                },
+            },
+            required: ["questions"],
+        },
+    },
+};
 // Run one sub-agent: a fresh conversation, same tools minus task, same
 // permission gate, and the parent's file read-state protected by a snapshot.
 async function runSubAgent(description, opts) {
     emit("agent_subagent_spawn"); // delegation is worth counting
+    const subModel = subAgentModelFor(opts); // the tier this delegated work runs on
+    // Show the delegation, and the model when it differs from the orchestrator's —
+    // the tiering should be visible, not a silent surprise on the bill.
     if (!opts.quiet)
-        console.log(chalk.blue(`  ⎿ sub-agent started: ${description.slice(0, 100)}`)); // show the delegation
+        console.log(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
+    await runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // lifecycle hook (observational)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
     try {
         const subMessages = [
             { role: "system", content: SUB_AGENT_PROMPT }, // its own, smaller constitution
             { role: "user", content: description }, // the task is its entire world
         ];
-        const result = await runLoop(subMessages, { ...opts, subAgent: true }); // recurse, flagged as sub-agent
+        const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel }); // recurse as a sub-agent, on its own tier
         if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
             // The framing matters: the parent must treat this as material to verify,
             // not as conclusions to copy — the most common multi-agent failure mode.
@@ -71,8 +113,9 @@ async function runSubAgent(description, opts) {
     }
     finally {
         restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
+        await runHooks("SubagentStop", { description: description.slice(0, 200) }); // lifecycle hook (observational)
         if (!opts.quiet)
-            console.log(chalk.blue("  ⎿ sub-agent done")); // close the bracket
+            console.log(mark.subAgentDone); // close the bracket
     }
 }
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
@@ -89,21 +132,28 @@ async function interruptibleSleep(ms, isInterrupted) {
         await new Promise((r) => setTimeout(r, Math.min(SLICE, ms - waited))); // sleep one slice (or the remainder)
     }
 }
+let modelCallSeq = 0; // increments per model call — seeds the rotating spinner word
 // One streaming model call: prints text as it arrives, assembles tool calls
 // from their deltas, and guards the stream with a two-level watchdog.
 async function streamModelCall(messages, // the full history to send
 opts) {
     const idleAbort = new AbortController(); // the watchdog's own kill switch
     const signal = AbortSignal.any([opts.signal, idleAbort.signal]); // either the user or the watchdog can abort
+    const word = thinkingWord(modelCallSeq++); // a rotating "thinking" word for this call
+    const startedAt = Date.now(); // for the spinner's live elapsed counter
+    let streamedChars = 0; // bytes of content+reasoning streamed this call → a live token estimate
     const spinner = opts.quiet
         ? null // the eval harness wants silence
-        : ora({ text: opts.subAgent ? "sub-agent working..." : "thinking...", discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+        : ora({ text: spinnerText(word, 0, !!opts.subAgent, opts.model), discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
     let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
     let stallWarned = false; // only warn once per quiet stretch
     // The two-level watchdog, checked once per second:
     // - idle (nothing at all for 90s) → cut the stream, let the retry layer handle it
     // - stall (slow but alive for 30s) → log it and keep waiting
+    // It also ticks the spinner: elapsed seconds + a live token estimate (~chars/4).
     const watchdog = setInterval(() => {
+        if (spinner?.isSpinning)
+            spinner.text = spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4));
         const quietMs = Date.now() - lastEvent; // ms since the last event
         if (quietMs > IDLE_TIMEOUT_MS) {
             emit("agent_watchdog_idle"); // record the cut — these should be rare
@@ -120,29 +170,54 @@ opts) {
         const stream = await opts.client.chat.completions.create(
         // Sub-agents do NOT get the task tool: one level of delegation only.
         // Nested spawning means orphan processes and debugging hell.
-        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions : [...toolDefinitions, taskTool], stream: true }, { signal });
+        // include_usage adds a final chunk carrying token counts — that is how we
+        // meter cost without a second (counting) request.
+        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions() : [...toolDefinitions(), taskTool, askUserTool], stream: true, stream_options: { include_usage: true } }, { signal });
         let content = ""; // accumulated answer text
-        let printedPrefix = false; // have we printed the 🤖 prefix yet?
+        let printedPrefix = false; // have we printed the answer prefix yet?
+        let printedThinking = false; // have we started printing the reasoning trace yet?
         const calls = []; // tool calls under assembly, indexed by delta.index
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
             stallWarned = false; // the stream spoke — reset the stall warning
+            if (chunk.usage)
+                recordUsage(chunk.usage); // the final usage chunk — meter it
             const delta = chunk.choices[0]?.delta; // this chunk's increment
             if (!delta)
                 continue; // keep-alive or usage chunk — nothing to do
+            // Reasoning models (e.g. deepseek-reasoner / R1) stream their thinking in a
+            // separate `reasoning_content` field BEFORE the answer. Show it dimly so a
+            // switch to a reasoning model is visibly different — but do NOT keep it:
+            // the reasoning is not the answer and must not be replayed in later turns.
+            const reasoning = delta.reasoning_content;
+            if (reasoning) {
+                streamedChars += reasoning.length; // count reasoning toward the live token estimate
+                if (spinner?.isSpinning)
+                    spinner.stop();
+                if (!opts.quiet && !opts.subAgent) {
+                    if (!printedThinking) {
+                        process.stdout.write("\n" + chalk.dim("💭 thinking: ")); // label the trace once
+                        printedThinking = true;
+                    }
+                    process.stdout.write(chalk.dim(reasoning)); // stream the thinking, dimmed
+                }
+            }
             if (delta.content) {
+                streamedChars += delta.content.length; // count the answer toward the live token estimate
                 if (spinner?.isSpinning)
                     spinner.stop(); // first token: replace the spinner with real output
                 if (!opts.quiet && !opts.subAgent) {
                     // Only the top-level agent streams to the screen — a sub-agent's
                     // inner monologue would be mistaken for the answer.
+                    if (printedThinking && !printedPrefix)
+                        process.stdout.write("\n"); // end the thinking block before the answer
                     if (!printedPrefix) {
-                        process.stdout.write("\n🤖 "); // prefix once, then stream raw
+                        process.stdout.write("\n" + mark.answer); // prefix once (⏺), then stream raw
                         printedPrefix = true;
                     }
                     process.stdout.write(delta.content); // print the token immediately — this IS the streaming UX
                 }
-                content += delta.content; // always keep it for the history
+                content += delta.content; // always keep it for the history (the answer only, never the reasoning)
             }
             for (const tc of delta.tool_calls ?? []) {
                 if (spinner?.isSpinning)
@@ -172,24 +247,52 @@ opts) {
 // Promise.all batch; calls that can prompt must be awaited one at a time.
 async function runOneCall(call, opts) {
     const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
-    if (!opts.quiet)
-        console.log(indent + chalk.cyan(`🔧 ${call.name}`) + chalk.dim(` ${call.args.slice(0, 120)}`)); // show what the model wants to do
+    if (!opts.quiet) {
+        // Compact one-line summary — long args are hidden behind Tab.
+        const summary = indent + mark.tool(call.name, call.args.length > 60 ? call.args.slice(0, 57) + "..." : call.args);
+        const full = `tool: ${call.name}\nargs: ${call.args}`;
+        printToolSummary(summary, full);
+    }
     // The permission gate sits between the model's intent and execution.
     const v = checkPermission(call.name, call.args);
     emit("agent_tool_call", { tool: call.name }); // every attempt, allowed or not
+    // For file-changing tools, show the diff BEFORE the gate decides. A filename
+    // ("edit_file: cart.js") is not enough to approve safely; the actual +/- lines
+    // are. Skipped for a hard deny (nothing will run) and in quiet sub-agent runs.
+    if (!opts.quiet && v.decision !== "deny" && (call.name === "write_file" || call.name === "edit_file")) {
+        const preview = previewChange(call.name, call.args);
+        if (preview)
+            console.log(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
+    }
     let content; // what goes back to the model as the tool result
     if (v.decision === "deny") {
         emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
         if (!opts.quiet)
-            console.log(chalk.red(`  ⛔ denied: ${v.reason}`)); // tell the user we blocked it
+            console.log(mark.denied(v.reason)); // tell the user we blocked it
         content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
     }
     else if (v.decision === "ask") {
-        const ok = await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`); // pause and ask the human
+        // Optional LLM judge: for a run_bash command the rules couldn't classify,
+        // ask the judge first. It can only DOWNGRADE ask→allow for the clearly
+        // safe; anything else still goes to the human. The judge never sees a deny.
+        let autoAllowed = false;
+        if (opts.judge && call.name === "run_bash") {
+            let cmd = "";
+            try {
+                cmd = JSON.parse(call.args).command ?? "";
+            }
+            catch { /* leave empty → judge will ask */ }
+            if (cmd && (await opts.judge.classify(cmd)) === "allow") {
+                autoAllowed = true;
+                if (!opts.quiet)
+                    console.log(mark.judge); // visible — the user can see the judge worked
+            }
+        }
+        const ok = autoAllowed || (await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`, call.name)); // judge-allowed, or pause and ask the human
         if (!ok)
             emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
         if (!ok && !opts.quiet)
-            console.log(chalk.yellow("  ✋ declined")); // make the refusal visible
+            console.log(mark.declined); // make the refusal visible
         content = ok
             ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
             : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
@@ -213,9 +316,23 @@ async function runWithHooks(call, opts) {
     if (pre.block) {
         emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
         if (!opts.quiet)
-            console.log(chalk.red(`  ⛔ blocked by PreToolUse hook`)); // make it visible
+            console.log(mark.hookBlock("PreToolUse")); // make it visible
         return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
     }
+    // A PreToolUse hook may REWRITE the arguments (e.g. add a commit trailer). The
+    // permission gate already ran on the original args; the rewrite only narrows or
+    // annotates, never escalates past a deny. Validate it's parseable, then use it.
+    if (pre.rewrite) {
+        try {
+            JSON.parse(pre.rewrite); // must be valid JSON args
+            if (!opts.quiet)
+                console.log(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
+            call = { ...call, args: pre.rewrite };
+        }
+        catch {
+            /* malformed rewrite — ignore, run the original args */
+        }
+    }
     const result = await execute(call, opts); // the actual work
     const post = await runHooks("PostToolUse", { tool: call.name, args: call.args, result }); // after
     if (post.block) {
@@ -228,6 +345,10 @@ async function runWithHooks(call, opts) {
 // Execute one approved tool call. The task tool is special — it is not in the
 // registry because running it needs the loop itself (it IS a loop).
 async function execute(call, opts) {
+    // ask_user is special like task: running it needs the CLI's prompt, not the
+    // tool registry. It presents a form and feeds the selections back to the model.
+    if (call.name === "ask_user")
+        return runAskUser(call, opts);
     if (call.name !== "task")
         return dispatch(call.name, call.args, opts.signal); // ordinary tools go through the registry (signal lets Ctrl+C kill run_bash)
     if (opts.subAgent)
@@ -243,6 +364,29 @@ async function execute(call, opts) {
         return "[error] task requires a non-empty description argument.";
     return runSubAgent(description, opts); // spawn the worker
 }
+// Present the ask_user form and turn the selections into a tool result. The
+// model called this to get a decision; we give it clean question→answer pairs.
+async function runAskUser(call, opts) {
+    if (opts.subAgent)
+        return "[error] Sub-agents cannot ask the user. Decide yourself, or report back to the parent."; // only the top-level agent talks to the human
+    if (!opts.askUser)
+        return "[error] No interactive prompt is available in this session — ask in plain text instead.";
+    let questions = [];
+    try {
+        questions = JSON.parse(call.args).questions ?? [];
+    }
+    catch {
+        /* fall through */
+    }
+    // Keep only well-formed questions (text + at least two options).
+    questions = (questions ?? []).filter((q) => q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length >= 2);
+    if (!questions.length)
+        return "[error] ask_user needs at least one question with two or more options.";
+    const answers = await opts.askUser(questions);
+    if (!answers)
+        return "The user dismissed the question form without answering. Proceed with your best judgment, or ask again if you truly need their input."; // cancelled / non-interactive
+    return `The user answered:\n${answers.map((a) => `- ${a.question} → ${a.answer}`).join("\n")}`; // organized, unambiguous
+}
 // Run one compaction attempt and keep score. Returns true on success.
 // Every automatic behavior keeps a failure count — that is what lets the
 // caller stop a hot failure loop instead of compacting forever.
@@ -250,10 +394,14 @@ async function tryCompact(messages, // history to compact (mutated in place)
 opts, // for client/model/signal
 compaction) {
     try {
+        if (!opts.subAgent)
+            await runHooks("PreCompact", {}); // lifecycle hook (top-level only; hooks are the human's project policy)
         await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
         emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
+        if (!opts.subAgent)
+            await runHooks("PostCompact", {}); // observational
         return true;
     }
     catch {
@@ -269,7 +417,7 @@ opts) {
     // The loop's mutable state: budgets and counters, rewritten every iteration.
     const attempts = { total: 0, rateLimited: 0, consecutive: 0 };
     const compaction = { count: 0, failures: 0 }; // compaction score card for this query
-    for (let round = 1; round <= MAX_ROUNDS; round++) {
+    for (let round = 1;; round++) {
         // One round = one successful model call + its tool results.
         // The inner loop retries the model call until it succeeds or a budget dies.
         while (true) {
@@ -357,7 +505,7 @@ opts) {
                         if (!opts.quiet)
                             console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
                         messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
-                        break; // exit the inner while → advance the round counter (so a stubborn Stop hook is still bounded by MAX_ROUNDS)
+                        break; // exit the inner while → advance the round counter
                     }
                 }
                 return { reason: TerminateReason.Done, finalText: out.content }; // no tool calls = final answer (already streamed to the screen)
@@ -387,5 +535,5 @@ opts) {
             break; // round complete, move to the next one
         }
     }
-    return { reason: TerminateReason.RoundCap }; // ran out of rounds before a final answer
+    // loop is unbounded — other safeguards (circuit breaker, retry budget, compaction guard) still apply
 }

package/dist/mcp.js

@@ -0,0 +1,237 @@
+import { spawn } from "node:child_process"; // stdio servers are subprocesses
+import chalk from "chalk"; // status lines
+import { CONFIG } from "./config.js"; // configured servers
+import { registerExternalTool } from "./tools.js"; // expose discovered tools
+import { emit } from "./telemetry.js"; // observability
+// MCP (Model Context Protocol) lets the agent borrow tools from external
+// servers — a filesystem server, a GitHub server, a database server, anything.
+// The wire protocol is JSON-RPC 2.0. We do the initialize handshake, ask for the
+// server's tools, and register each one so it flows through the SAME dispatch and
+// the SAME permission gate as a built-in. There is one execution path, period.
+//
+// Since Day 24 there are TWO ways to reach a server: spawn it and talk over
+// stdio (local), or POST to a URL (remote, "Streamable HTTP"). The protocol is
+// identical; only the pipe differs. That difference lives behind a Transport
+// interface, so McpClient — handshake, ids, tool flattening — never has to care.
+//
+// Discovered tools are named mcp__<server>__<tool> so they never collide with
+// built-ins and the user can see (and gate) exactly where each came from.
+const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
+const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
+// ---- stdio transport: one JSON object per line, to a subprocess --------------
+class StdioTransport {
+    child;
+    pending = new Map(); // id → resolver (responses arrive async on one stream)
+    buffer = ""; // partial stdout, reassembled into whole lines
+    constructor(def) {
+        this.child = spawn(def.command, def.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"], // we own stdin/stdout; stderr is the server's log
+            env: { ...process.env, ...def.env }, // pass through + extras
+        });
+        // Reassemble newline-delimited JSON from the stdout stream.
+        this.child.stdout.on("data", (chunk) => {
+            this.buffer += chunk.toString();
+            let nl;
+            while ((nl = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, nl).trim(); // one complete message
+                this.buffer = this.buffer.slice(nl + 1); // keep the remainder
+                if (line)
+                    this.onMessage(line);
+            }
+        });
+        this.child.stderr.on("data", () => { }); // the server's stderr is its own logging — never our stdout
+    }
+    onMessage(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return; // ignore anything that isn't valid JSON-RPC
+        }
+        const resolver = this.pending.get(msg.id);
+        if (resolver) {
+            this.pending.delete(msg.id);
+            resolver(msg);
+        }
+    }
+    request(payload, timeoutMs) {
+        const { id } = payload;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(r);
+            };
+            const timer = setTimeout(() => finish({ id, error: { message: `MCP request '${payload.method}' timed out` } }), timeoutMs);
+            this.pending.set(id, finish);
+            this.child.stdin.write(JSON.stringify(payload) + "\n"); // one line, newline-terminated
+        });
+    }
+    notify(method, params) {
+        this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    }
+    close() {
+        this.child.kill(); // best-effort cleanup
+    }
+}
+// Pull JSON-RPC messages out of a Server-Sent-Events body. SSE frames are
+// separated by blank lines; the payload lives on one or more `data:` lines.
+// Exported because parsing is the fiddly part worth testing on its own.
+export function parseSseData(body) {
+    const out = [];
+    for (const frame of body.split(/\r?\n\r?\n/)) {
+        const data = frame
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim()) // strip "data:" and surrounding space
+            .join("\n");
+        if (data)
+            out.push(data);
+    }
+    return out;
+}
+// ---- HTTP transport: POST to a URL, read JSON or SSE back --------------------
+class HttpTransport {
+    url;
+    headers;
+    sessionId; // assigned by the server on initialize, echoed on every later request
+    constructor(def) {
+        this.url = def.url;
+        this.headers = { ...def.headers };
+    }
+    // The response to a POST may come back as a single JSON object OR as an SSE
+    // stream carrying it. Either way we want the JSON-RPC message matching our id.
+    async post(body, timeoutMs, isRequest) {
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream", // we accept either shape
+                ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+                ...this.headers,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const sid = res.headers.get("mcp-session-id"); // initialize hands us a session to keep
+        if (sid)
+            this.sessionId = sid;
+        if (!isRequest)
+            return null; // a notification expects no body (202 Accepted)
+        const raw = await res.text();
+        const payloads = res.headers.get("content-type")?.includes("text/event-stream") ? parseSseData(raw) : [raw];
+        for (const p of payloads) {
+            try {
+                const msg = JSON.parse(p);
+                if (msg && (msg.result !== undefined || msg.error !== undefined))
+                    return msg; // the response we came for
+            }
+            catch {
+                /* skip non-JSON frames (SSE comments, keep-alives) */
+            }
+        }
+        return null;
+    }
+    async request(payload, timeoutMs) {
+        try {
+            const msg = await this.post(payload, timeoutMs, true);
+            return msg ?? { id: payload.id, error: { message: `MCP request '${payload.method}' returned no response` } };
+        }
+        catch (err) {
+            return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
+        }
+    }
+    notify(method, params) {
+        // Fire-and-forget; errors on a notification are not worth surfacing.
+        void this.post({ jsonrpc: "2.0", method, params }, INIT_TIMEOUT_MS, false).catch(() => { });
+    }
+    close() {
+        // Best-effort: tell the server to drop the session. No await, no error care.
+        if (this.sessionId) {
+            void fetch(this.url, { method: "DELETE", headers: { "mcp-session-id": this.sessionId, ...this.headers } }).catch(() => { });
+        }
+    }
+}
+// Choose the pipe from the config: a url means HTTP, otherwise spawn over stdio.
+function makeTransport(def) {
+    return def.url ? new HttpTransport(def) : new StdioTransport(def);
+}
+// The protocol layer: handshake, request ids, tool flattening. It talks to a
+// Transport and is blind to whether that's a subprocess or an HTTP endpoint.
+class McpClient {
+    transport;
+    nextId = 1; // JSON-RPC request id counter
+    constructor(def) {
+        this.transport = makeTransport(def);
+    }
+    request(method, params, timeoutMs) {
+        return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
+    }
+    // The MCP startup dance: initialize → initialized → list tools.
+    async start() {
+        const init = await this.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mini-agent", version: "0" } }, INIT_TIMEOUT_MS);
+        if (init.error)
+            throw new Error(init.error.message); // server refused to initialize
+        this.transport.notify("notifications/initialized", {}); // tell the server we're ready
+        const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS); // ask what it offers
+        if (list.error)
+            throw new Error(list.error.message);
+        return list.result?.tools ?? [];
+    }
+    // Invoke one tool and flatten its content into plain text for the model.
+    async callTool(name, args) {
+        const res = await this.request("tools/call", { name, arguments: args }, CALL_TIMEOUT_MS);
+        if (res.error)
+            return `[error] MCP tool failed: ${res.error.message}`; // surface, don't throw
+        const text = (res.result?.content ?? []).map((c) => c.text ?? `[${c.type} content]`).join("\n"); // flatten parts
+        const body = text || "(no output)";
+        return res.result?.isError ? `[error] ${body}` : body; // MCP can flag a logical error in a successful response
+    }
+    kill() {
+        this.transport.close();
+    }
+}
+// Connect to every configured MCP server, register their tools, and return a
+// cleanup function. Failures are isolated: a server that won't start is logged
+// and skipped — it never stops the agent or the other servers.
+export async function connectMcpServers() {
+    const entries = Object.entries(CONFIG.mcpServers); // [name, def] pairs
+    if (!entries.length)
+        return () => { }; // the common case: nothing configured
+    const clients = []; // for cleanup
+    for (const [serverName, def] of entries) {
+        const client = new McpClient(def);
+        try {
+            const specs = await client.start(); // handshake + discover
+            clients.push(client);
+            for (const spec of specs) {
+                const toolName = `mcp__${serverName}__${spec.name}`; // namespaced, collision-proof
+                const tool = {
+                    definition: {
+                        type: "function",
+                        function: {
+                            name: toolName,
+                            description: `[MCP:${serverName}] ${spec.description ?? spec.name}`, // mark the origin in the manual
+                            parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
+                        },
+                    },
+                    run: async (args) => client.callTool(spec.name, args), // dispatch routes here; the permission gate ran first
+                };
+                registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
+            }
+            emit("agent_mcp_connected", { server: serverName, tools: specs.length, transport: def.url ? "http" : "stdio" });
+            console.log(chalk.dim(`(mcp: ${serverName} — ${specs.length} tools${def.url ? " over http" : ""})`)); // visible at startup
+        }
+        catch (err) {
+            client.kill(); // don't leak the process/session
+            emit("agent_mcp_failed", { server: serverName });
+            console.error(chalk.yellow(`  [mcp] ${serverName} failed to start (skipped): ${err.message}`)); // loud, but not fatal
+        }
+    }
+    return () => clients.forEach((c) => c.kill()); // the caller calls this on exit
+}