huddle-cli 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// huddle — the multiplayer layer for AI coding agents.
+//
+//   huddle                      open Huddle (welcome, connect agents, prompt)
+//   huddle join "<goal>"        plan a goal and run your agents on it
+//   huddle join "<goal>" --plan dry run: show the plan, create/spawn nothing
+//     --approvals=safe|auto|yolo  what agents may do without asking (default auto)
+//     --agents=claude,codex       only these agents work on this run
+//     --council / --no-council    every agent brainstorms the design first (default: big goals)
+//     --qa / --no-qa              a QA round after the build (default: on for big goals)
+//   huddle doctor               is this machine ready: node, git, room db, your agents
+//   huddle --version            print the version
+//   huddle agents --all         every connector (built in + agents.json) and how to get it
+//   huddle agents install <id>  install one connector's CLI, after asking
+//   huddle board                print the board + shared memory
+//   huddle view [repo]          the live view (ctrl-t) from another terminal, read-only
+//   huddle story [--html f]     replay the latest run: who said what to whom, reviews, merges
+//   huddle init                 set up .huddle/ in this repo (automatic on first run)
+//   huddle up | down            attach mode: start/stop this repo's live room
+//   huddle connect | disconnect wire your own claude/codex/cursor sessions into it
+//   huddle peers                who's live in this repo and which files they hold
+//   huddle attach <agent>       open an agent in its own worktree, connected
+//   huddle land [branch]        tests -> rebase -> merge an attach session's branch
+//   huddle plug                 (internal) the MCP server each agent talks to
+//   huddle guard                (internal) Claude's pre-edit hook in attach mode
+import { packageInfo } from "./preflight.js"; // first: refuses old Node before anything else loads
+import { runPlug } from "./mcp/server.js";
+import { C } from "./ui/term.js";
+import { connectAgents, ensureInit, huddleDir, printBoard, runApp, runGoal } from "./ui/app.js";
+import { INVITE_CODE, joinRoom } from "./ui/remote.js";
+import { startRelay } from "./relay/server.js";
+import { runDoctor } from "./ui/doctor.js";
+import { SqliteUnavailableError } from "./room/sqlite.js";
+import { installConnector, printCatalog } from "./ui/catalog.js";
+const USAGE = `${C.violet("huddle")} — your agents, in the same room
+
+  ${C.bold("huddle")}                      open Huddle
+  ${C.bold('huddle join "<goal>"')}        plan the goal and run your agents
+  ${C.bold('huddle join "<goal>" --plan')} dry run — show who'd do what
+  ${C.bold("  --approvals=safe|auto|yolo")}  what agents may do without asking (default auto)
+  ${C.bold("  --agents=claude,codex")}       only these agents work on this run
+  ${C.bold("  --council | --no-council")}    every agent brainstorms the design first ${C.faint("(default: big goals only)")}
+  ${C.bold("  --qa")} ${C.faint("/")} ${C.bold("--no-qa")}             agents re-check the build and fix what they find ${C.faint("(default: big goals)")}
+  ${C.bold("huddle join <address> <CODE>")} join someone's room from an invite
+  ${C.bold("huddle doctor")}               check this machine: node, git, your agents
+  ${C.bold("huddle agents --all")}         every connector Huddle knows, installed or not
+  ${C.bold("huddle agents install <id>")}  install one (asks first)
+  ${C.bold("huddle relay")} ${C.faint("[--port 8080]")}  run a relay so rooms work across networks
+  ${C.bold("huddle board")}                print the board
+  ${C.bold("huddle view")} ${C.faint("[repo]")}          watch a run live from another terminal ${C.faint("(read-only)")}
+  ${C.bold("huddle story")} ${C.faint("[--html f]")}     replay the last run: messages, reviews, merges ${C.faint("(--list, --run n)")}
+  ${C.bold("huddle --version")}            print the version
+
+  ${C.faint("run claude, codex and cursor yourself — in one repo, safely:")}
+  ${C.bold("huddle connect")}              wire your agents into this repo's live room ${C.faint("(asks first)")}
+  ${C.bold("huddle peers")}                who's live, what they're doing, which files they hold
+  ${C.bold("huddle attach <agent>")}       open an agent in its own worktree branch
+  ${C.bold("huddle land")} ${C.faint("[branch]")}         test + merge that session's work
+  ${C.bold("huddle up")} ${C.faint("/")} ${C.bold("down")} ${C.faint("/")} ${C.bold("disconnect")}  start · stop the live room · unwire
+`;
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case undefined:
+            if (!process.stdin.isTTY)
+                return void console.log(USAGE);
+            return runApp();
+        case "plug":
+            return runPlug();
+        case "init":
+            if (!ensureInit()) {
+                console.log(C.red("✗ Not a git repo.") + " Huddle sandboxes are git worktrees — run `git init` first.");
+                process.exit(1);
+            }
+            return void console.log(`${C.green("✓")} Huddle initialized in ${C.faint(huddleDir())}`);
+        case "doctor":
+        case "agents":
+            if (rest[0] === "install" && rest[1])
+                return void (await installConnector(rest[1]));
+            if (rest.includes("--all"))
+                return printCatalog();
+            process.exitCode = await runDoctor();
+            return;
+        case "join": {
+            // `huddle join <address> <CODE>` joins someone's room; anything else is a goal.
+            if (rest.length === 2 && INVITE_CODE.test(rest[1]))
+                return joinRoom(rest[0], rest[1]);
+            const goal = rest.filter((a) => !a.startsWith("--")).join(" ");
+            if (!goal) {
+                console.log(C.red("✗ Give a goal:") + ' huddle join "build the login page"');
+                process.exit(1);
+            }
+            const flag = rest.find((a) => a.startsWith("--approvals="))?.split("=")[1];
+            const approvals = (["safe", "auto", "yolo"].includes(flag ?? "") ? flag : "auto");
+            const probed = await connectAgents();
+            let results = probed;
+            // --agents=claude,codex: run with just these (the rest sit this one out).
+            const pick = rest.find((a) => a.startsWith("--agents="))?.split("=")[1];
+            if (pick !== undefined) {
+                const ids = pick.split(",").map((s) => s.trim()).filter(Boolean);
+                const unknown = ids.filter((id) => !results.some((r) => r.adapter.id === id));
+                if (!ids.length || unknown.length) {
+                    console.log(C.red(`✗ --agents: no agent called ${unknown.join(", ") || "(empty)"}.`) + ` Known: ${results.map((r) => r.adapter.id).join(", ")}`);
+                    process.exit(1);
+                }
+                const notReady = results.filter((r) => ids.includes(r.adapter.id) && r.state !== "ready").map((r) => r.adapter.id);
+                if (notReady.length)
+                    console.log(C.yellow(`! not ready, skipped: ${notReady.join(", ")}`));
+                results = results.filter((r) => ids.includes(r.adapter.id));
+            }
+            // Non-interactive: nobody to ask, so it's plan (--plan) or auto.
+            // --council: every agent brainstorms the design first; --no-council: the brain plans alone.
+            const council = rest.includes("--no-council") ? false : rest.includes("--council") ? true : undefined;
+            const qa = rest.includes("--no-qa") ? false : rest.includes("--qa") ? true : undefined;
+            return runGoal(goal, { results, probed, mode: rest.includes("--plan") ? "plan" : "auto", approvals, council, qa });
+        }
+        case "board":
+            return printBoard();
+        case "view":
+        case "watch":
+            return (await import("./ui/watch.js")).runView(rest);
+        case "story":
+            return (await import("./ui/story.js")).runStory(rest);
+        case "up":
+            return (await import("./attach/session.js")).runUp(rest);
+        case "down":
+            return (await import("./attach/session.js")).runDown();
+        case "peers":
+            return (await import("./attach/session.js")).runPeers();
+        case "attach":
+            return (await import("./attach/session.js")).runAttach(rest);
+        case "land":
+            return (await import("./attach/session.js")).runLand(rest);
+        case "connect":
+            return (await import("./attach/connect.js")).runConnect(rest);
+        case "disconnect":
+            return (await import("./attach/connect.js")).runDisconnect();
+        case "guard":
+            return (await import("./attach/guard.js")).runGuard();
+        case "relay": {
+            // Run a relay so rooms work across networks. Host it anywhere Node runs.
+            const i = rest.indexOf("--port");
+            const port = Number(i >= 0 ? rest[i + 1] : process.env.PORT ?? 8080);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                console.log(C.red("✗ --port needs a number from 0 to 65535,") + " e.g. huddle relay --port 8080");
+                process.exit(1);
+            }
+            const r = await startRelay(port, (l) => console.log(C.faint(new Date().toISOString().slice(11, 19) + " " + l)));
+            console.log(`${C.violet("huddle relay")} listening on :${r.port} ${C.faint("· people use it with: relay ws://<this-host>:" + r.port)}`);
+            return;
+        }
+        case "--version":
+        case "-v":
+        case "-V":
+        case "version":
+            return void console.log(packageInfo().version);
+        case "help":
+        case "--help":
+        case "-h":
+            return void console.log(USAGE);
+        default:
+            console.log(C.red(`✗ unknown command: ${cmd}\n`) + USAGE);
+            process.exit(1);
+    }
+}
+main().catch((e) => {
+    // A message for the user, not a stack trace. HUDDLE_DEBUG=1 shows the stack.
+    if (e instanceof SqliteUnavailableError)
+        console.error(C.red("✗ ") + e.message);
+    else
+        console.error(C.red("huddle error:"), e?.message ?? e);
+    if (process.env.HUDDLE_DEBUG && e?.stack)
+        console.error(C.faint(e.stack));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/mcp/server.js

@@ -0,0 +1,240 @@
+// The Plug: one MCP server, spoken identically by every agent (Claude, Codex,
+// Gemini, Cursor). It is launched per-agent as `huddle plug` and talks to the
+// Room over HTTP, so the agent process stays stateless — the Room owns truth.
+//
+// The agent's identity is passed in via HUDDLE_AGENT_ID (set by the launcher),
+// so each agent's calls are attributed correctly without the model having to
+// remember who it is.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const ROOM = process.env.HUDDLE_ROOM_URL ?? "http://localhost:4737";
+const AGENT = process.env.HUDDLE_AGENT_ID ?? "unknown-agent";
+// Proves to the Room that this call comes from one of this session's own agents.
+const SECRET = process.env.HUDDLE_SECRET ?? "";
+async function room(path, method, body) {
+    const res = await fetch(`${ROOM}${path}`, {
+        method,
+        headers: { "content-type": "application/json", "x-huddle-secret": SECRET, "x-huddle-agent": AGENT },
+        body: method === "POST" ? JSON.stringify({ agent_id: AGENT, ...body }) : undefined,
+    });
+    return res.json();
+}
+const TOOLS = [
+    {
+        name: "huddle_board",
+        description: "See the whole shared task board: the goal, every agent, who claimed what, and live progress. Call this BEFORE you start work and whenever you finish a step.",
+        inputSchema: { type: "object", properties: {} },
+        handler: () => room("/board", "GET"),
+    },
+    {
+        name: "huddle_peers",
+        description: "See what every other agent is doing RIGHT NOW (status + current task). Use this to avoid duplicating work and to know if a teammate is close to done.",
+        inputSchema: { type: "object", properties: {} },
+        handler: () => room("/peers", "GET"),
+    },
+    {
+        name: "huddle_claim",
+        description: "Atomically claim a backlog task so it's yours. Fails if someone already took it or its dependencies aren't merged yet. Always claim before coding.",
+        inputSchema: {
+            type: "object",
+            properties: { task_id: { type: "string" } },
+            required: ["task_id"],
+        },
+        handler: (a) => room("/claim", "POST", { task_id: a.task_id }),
+    },
+    {
+        name: "huddle_check_overlap",
+        description: "Before you edit files/symbols, check whether any teammate has already claimed them. Pass entries as 'path' or 'path::symbol'. Returns anyone you'd collide with.",
+        inputSchema: {
+            type: "object",
+            properties: { touches: { type: "array", items: { type: "string" } } },
+            required: ["touches"],
+        },
+        handler: (a) => room("/check_overlap", "POST", { touches: a.touches }),
+    },
+    {
+        name: "huddle_announce_plan",
+        description: "Announce what you're about to change BEFORE writing code: your intent + the files/symbols you'll touch ('path' or 'path::symbol'). Takes soft leases and flags collisions early.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task_id: { type: "string" },
+                intent: { type: "string" },
+                touches: { type: "array", items: { type: "string" } },
+            },
+            required: ["task_id", "intent", "touches"],
+        },
+        handler: (a) => room("/announce_plan", "POST", { task_id: a.task_id, intent: a.intent, touches: a.touches }),
+    },
+    {
+        name: "huddle_progress",
+        description: "Post live progress on your task (0-100) with a short note. Fans out instantly to the dashboard and to any teammate waiting on you.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task_id: { type: "string" },
+                pct: { type: "number" },
+                note: { type: "string" },
+            },
+            required: ["task_id", "pct"],
+        },
+        handler: (a) => room("/progress", "POST", { task_id: a.task_id, pct: a.pct, note: a.note ?? "" }),
+    },
+    {
+        name: "huddle_split",
+        description: "Your task is big and a teammate is free (you'll see a help offer in huddle_inbox)? Hand a separable PART of it to the room as a new task — ideally one in files you won't keep editing. Huddle gives it to a free agent and merges it separately; you keep the rest and must not do that part yourself. after_mine=true makes the part wait until your task merges.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task_id: { type: "string", description: "your task" },
+                title: { type: "string", description: "short title of the part you hand off" },
+                spec: { type: "string", description: "exactly what the part must do, incl. names/contracts it must match" },
+                files: { type: "array", items: { type: "string" }, description: "files the part owns" },
+                after_mine: { type: "boolean" },
+            },
+            required: ["task_id", "title", "spec"],
+        },
+        handler: (a) => room("/split", "POST", { task_id: a.task_id, title: a.title, spec: a.spec, files: a.files ?? [], after_mine: !!a.after_mine }),
+    },
+    {
+        name: "huddle_offer_help",
+        description: "You're done (or nearly) and could take more: tell every teammate who is mid-task that you can take part of their work. Returns what's in flight (owner, status, progress, last note, age). They decide whether to huddle_split.",
+        inputSchema: { type: "object", properties: {} },
+        handler: () => room("/offer_help", "POST", {}),
+    },
+    {
+        name: "huddle_remember",
+        description: "Write to SHARED MEMORY so other agents learn from you. kind = decision | fact | gotcha. Always include 'why' — teammates need the reasoning, not just the what.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: { type: "string", enum: ["decision", "fact", "gotcha"] },
+                body: { type: "string" },
+                why: { type: "string" },
+            },
+            required: ["kind", "body"],
+        },
+        handler: (a) => room("/remember", "POST", { kind: a.kind, body: a.body, why: a.why ?? "" }),
+    },
+    {
+        name: "huddle_recall",
+        description: "Read shared memory — the decisions, facts, and gotchas other agents have recorded. Call this at the start of any task to inherit context instead of re-deriving it.",
+        inputSchema: {
+            type: "object",
+            properties: { query: { type: "string" } },
+        },
+        handler: (a) => room(`/recall${a.query ? `?q=${encodeURIComponent(a.query)}` : ""}`, "GET"),
+    },
+    {
+        name: "huddle_ask",
+        description: "Ask a question another agent (on any teammate's machine) may know — e.g. 'what shape is the Order type?'. With `to` = a teammate agent that's working right now, it goes to THEIR inbox and waits a short while for their reply; otherwise (or if they're slow) it's answered from shared memory, and their late reply arrives in your huddle_inbox. Use it before guessing at a contract someone else owns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                question: { type: "string" },
+                to: { type: "string", description: "optional: the agent who owns it, e.g. 'codex' or 'harsh/codex' (see huddle_peers)" },
+            },
+            required: ["question"],
+        },
+        handler: (a) => room("/ask", "POST", { question: a.question, to: a.to }),
+    },
+    {
+        name: "huddle_send",
+        description: "Message a teammate agent directly: a heads-up ('I renamed X to Y'), an interface you're exposing, or an answer to their question (pass reply_to = the question's id). `to` = an agent id from huddle_peers, a task id, or \"all\" for everyone working now. They see it the next time they call any huddle tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "agent id (e.g. 'codex', 'claude#2', 'harsh/codex'), a task id, or 'all'" },
+                message: { type: "string" },
+                reply_to: { type: "string", description: "optional: id of the message/question you're answering" },
+            },
+            required: ["message"],
+        },
+        handler: (a) => room("/send", "POST", { to: a.to, message: a.message, reply_to: a.reply_to }),
+    },
+    {
+        name: "huddle_inbox",
+        description: "Read messages and questions teammates sent you (marks them read). Any huddle tool result that says 'unread_messages' means: call this now. Answer questions with huddle_send(reply_to=…).",
+        inputSchema: { type: "object", properties: {} },
+        handler: () => room("/inbox", "GET"),
+    },
+    {
+        name: "huddle_report_bug",
+        description: "QA: file ONE concrete, reproducible bug you found in the team's merged work. It becomes a fix task on the board, routed to the agent that wrote those files. Exact steps or a command in `repro`; `files` = where the defect is. When sensible, add a regression test that fails today: write it in your worktree and pass its path as `test_file` (or its content as `test_code`). Duplicates are merged automatically. Not for style nits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "short: what is broken" },
+                repro: { type: "string", description: "exact command(s) or steps that show it" },
+                expected: { type: "string" },
+                actual: { type: "string" },
+                files: { type: "array", items: { type: "string" }, description: "files the defect is in" },
+                test_file: { type: "string", description: "optional: path of a regression test you wrote (fails now, passes once fixed)" },
+                test_code: { type: "string", description: "optional: that test's full content, if you didn't write the file" },
+            },
+            required: ["title", "repro", "expected", "actual"],
+        },
+        handler: (a) => room("/report_bug", "POST", {
+            title: a.title,
+            repro: a.repro,
+            expected: a.expected,
+            actual: a.actual,
+            files: a.files ?? [],
+            test_file: a.test_file,
+            test_code: a.test_code,
+        }),
+    },
+    {
+        name: "huddle_take_backlog",
+        description: "You're free. Ask the Room for the highest-value unblocked backlog task that fits your strengths, and claim it automatically. This is how idle agents remove bottlenecks.",
+        inputSchema: {
+            type: "object",
+            properties: { prefers: { type: "array", items: { type: "string" } } },
+        },
+        handler: (a) => room("/take_backlog", "POST", { prefers: a.prefers ?? [] }),
+    },
+    {
+        name: "huddle_done",
+        description: "Mark your task ready. This triggers the test-gate and, if green, the merge into main. Include a short summary of what you did.",
+        inputSchema: {
+            type: "object",
+            properties: { task_id: { type: "string" }, summary: { type: "string" } },
+            required: ["task_id", "summary"],
+        },
+        handler: (a) => room("/done", "POST", { task_id: a.task_id, summary: a.summary }),
+    },
+];
+/**
+ * What an MCP host shows the model about the Plug as a whole: the verbs by
+ * phase of a task, so every vendor's agent learns the same team habits. Every
+ * tool in TOOLS is named here (test/team-run.test.ts checks).
+ */
+export const PLUG_INSTRUCTIONS = `Huddle: you are one of several AI coding agents working on one repo at once, each in its own git worktree. These tools are how the team talks.
+- Start: huddle_board (the plan and who is doing what), huddle_recall (shared memory: decisions, contracts, the design council's notes: huddle_recall "council"), huddle_peers, huddle_inbox.
+- Before editing: huddle_announce_plan (what you will touch), huddle_check_overlap (is someone else in that file).
+- While working: huddle_progress (a short note; the reply shows the team's in-flight work), huddle_remember (a decision or contract others need), huddle_send (message one teammate), huddle_ask (ask a teammate or the brain a question), huddle_inbox (read replies).
+- Sharing work: when huddle_offer_help reaches you, huddle_split hands part of your task to a free agent; huddle_take_backlog picks up the next task; huddle_claim takes a specific one.
+- QA rounds: huddle_report_bug files one reproducible bug in the merged build; it becomes a fix task for the file's author.
+- Finish: huddle_done with a short summary. Huddle tests and merges it.`;
+/** The Plug's verb names, in the order listed to agents. */
+export const PLUG_VERBS = TOOLS.map((t) => t.name);
+export async function runPlug() {
+    // Attach mode (`huddle connect`): a session you started yourself, no scheduler.
+    if (process.env.HUDDLE_LIVE)
+        return (await import("../attach/plug.js")).runLivePlug();
+    const server = new Server({ name: "huddle", version: "0.1.0" }, { capabilities: { tools: {} }, instructions: PLUG_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = TOOLS.find((t) => t.name === req.params.name);
+        if (!tool)
+            throw new Error(`unknown tool: ${req.params.name}`);
+        const result = await tool.handler((req.params.arguments ?? {}));
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/orchestrator/ask.js

@@ -0,0 +1,51 @@
+// One-shot, read-only questions to an agent: answering "where are we with
+// this project?" and planning a goal. Runs in the repo itself (no worktree),
+// with each vendor's read-only / plan mode, so nothing can be edited.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Preference order for who answers questions and plans. */
+const ASK_ORDER = ["claude", "codex", "antigravity", "cursor", "gemini"];
+export function pickAsker(ready) {
+    return [...ready].filter((a) => a.ask).sort((a, b) => ASK_ORDER.indexOf(a.id) - ASK_ORDER.indexOf(b.id))[0];
+}
+export function askAgent(adapter, prompt, cwd, opts = {}) {
+    // Unique per call: the design council asks several agents in the same millisecond.
+    const outFile = path.join(os.tmpdir(), `huddle-ask-${process.pid}-${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
+    const spec = adapter.ask({ prompt, cwd, outFile, model: opts.model, noTools: opts.noTools, quick: opts.quick });
+    return new Promise((resolve) => {
+        const child = spawn(spec.cmd[0], spec.cmd.slice(1), { cwd: spec.cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", (d) => (err += d));
+        // SIGKILL after a grace period: a stalled CLI can ignore SIGTERM (seen live with cursor-agent).
+        const stop = () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill("SIGTERM");
+            setTimeout(() => child.exitCode === null && child.signalCode === null && child.kill("SIGKILL"), 5000).unref();
+        };
+        const timer = setTimeout(stop, opts.timeoutMs ?? 5 * 60_000);
+        opts.signal?.addEventListener("abort", stop);
+        const finish = (code) => {
+            clearTimeout(timer);
+            let text = out;
+            if (spec.usesOutFile) {
+                try {
+                    text = fs.readFileSync(outFile, "utf8");
+                    fs.unlinkSync(outFile);
+                }
+                catch {
+                    /* fall back to stdout */
+                }
+            }
+            resolve({ ok: code === 0 && text.trim().length > 0, text: text.trim() || err.trim() });
+        };
+        child.on("exit", finish);
+        child.on("error", () => finish(-1));
+    });
+}
+//# sourceMappingURL=ask.js.map

package/dist/orchestrator/brain.js

@@ -0,0 +1,164 @@
+// The brain: the model Huddle itself thinks with — planning goals, reviewing
+// diffs, writing the "what you got" report. It's separate from the agents that
+// write code, so it can be something small and cheap:
+//
+//   ollama:<model>   a local model (e.g. Qwen2.5-Coder) — free, private, offline
+//   cursor:<model>   a cheap hosted model through Cursor (e.g. grok-4.7-low-fast)
+//   claude:<model>   Claude at a given size (claude:haiku, claude:opus)
+//   codex / antigravity[:model]
+//
+// Agent-backed brains can read the repo themselves. A local model can't, so
+// every prompt carries a compact repo snapshot (see repoContext) — which also
+// makes agent brains faster, since they don't have to explore first.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ADAPTERS } from "../adapters/index.js";
+import { askAgent } from "./ask.js";
+const OLLAMA = process.env.OLLAMA_HOST?.replace(/\/$/, "") || "http://127.0.0.1:11434";
+/** Models a local Ollama has pulled, or [] if Ollama isn't running. */
+export async function ollamaModels() {
+    try {
+        const r = await fetch(`${OLLAMA}/api/tags`, { signal: AbortSignal.timeout(1500) });
+        const j = await r.json();
+        return (j.models ?? []).map((m) => String(m.name).replace(/:latest$/, ""));
+    }
+    catch {
+        return [];
+    }
+}
+function ollamaBrain(model) {
+    return {
+        spec: `ollama:${model}`,
+        label: `${model} (local, free)`,
+        readsRepo: false,
+        async think(prompt, _cwd, opts = {}) {
+            const t0 = Date.now();
+            try {
+                const signals = [AbortSignal.timeout(opts.timeoutMs ?? 5 * 60_000), ...(opts.signal ? [opts.signal] : [])];
+                const r = await fetch(`${OLLAMA}/api/chat`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    signal: AbortSignal.any(signals),
+                    body: JSON.stringify({
+                        model,
+                        stream: false,
+                        ...(opts.json ? { format: "json" } : {}),
+                        options: { temperature: 0.2, num_ctx: 16384 },
+                        messages: [{ role: "user", content: prompt }],
+                    }),
+                });
+                const j = await r.json();
+                const text = String(j?.message?.content ?? "").trim();
+                return { ok: r.ok && !!text, text: text || String(j?.error ?? ""), tokens: (j.prompt_eval_count ?? 0) + (j.eval_count ?? 0), ms: Date.now() - t0 };
+            }
+            catch (e) {
+                return { ok: false, text: String(e?.message ?? e), ms: Date.now() - t0 };
+            }
+        },
+    };
+}
+function agentBrain(adapterId, model) {
+    const adapter = ADAPTERS.find((a) => a.id === adapterId);
+    if (!adapter?.ask)
+        return null;
+    return {
+        spec: model ? `${adapterId}:${model}` : adapterId,
+        label: model ? `${adapterId} · ${model}` : adapterId,
+        readsRepo: true,
+        async think(prompt, cwd, opts = {}) {
+            const t0 = Date.now();
+            const r = await askAgent(adapter, prompt, cwd, {
+                signal: opts.signal,
+                timeoutMs: opts.timeoutMs,
+                model,
+                noTools: opts.selfContained,
+            });
+            return { ...r, ms: Date.now() - t0 };
+        },
+    };
+}
+/** Parse a brain spec like "ollama:qwencoder" or "cursor:grok-4.7-low-fast". */
+export function brainFrom(spec) {
+    const [kind, ...rest] = spec.split(":");
+    const model = rest.join(":") || undefined;
+    if (kind === "ollama")
+        return model ? ollamaBrain(model) : null;
+    return agentBrain(kind, model);
+}
+/** The default when nothing's configured: the strongest agent you have ready. */
+export const DEFAULT_BRAIN = "claude";
+/** Suggestions for the `brain` command, cheapest first. */
+export async function brainOptions(readyAgents) {
+    const out = [];
+    for (const m of await ollamaModels()) {
+        if (/llava|vision|embed/i.test(m))
+            continue; // not text planners
+        out.push({ spec: `ollama:${m}`, note: "local · free · private · speed depends on your RAM" });
+    }
+    if (readyAgents.includes("cursor"))
+        out.push({ spec: "cursor:grok-4.7-low-fast", note: "cheap + fast, via your Cursor plan" });
+    if (readyAgents.includes("claude")) {
+        out.push({ spec: "claude:haiku", note: "smallest Claude — cheapest hosted option" });
+        out.push({ spec: "claude:sonnet", note: "default — plans in ~15s, a fraction of Opus's tokens" });
+        out.push({ spec: "claude", note: "Opus — strongest plans, most tokens" });
+    }
+    if (readyAgents.includes("codex"))
+        out.push({ spec: "codex", note: "your Codex default model" });
+    return out;
+}
+/**
+ * A compact snapshot of the repo for the brain: file list, README head,
+ * manifest. ~a few thousand tokens; lets even a local model plan sensibly.
+ */
+export function repoContext(cwd, maxFiles = 250) {
+    const files = (spawnSync("git", ["ls-files"], { cwd, encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean);
+    const head = (f, lines) => {
+        try {
+            return fs.readFileSync(path.join(cwd, f), "utf8").split("\n").slice(0, lines).join("\n");
+        }
+        catch {
+            return null;
+        }
+    };
+    const parts = [`FILES (${files.length}${files.length > maxFiles ? `, first ${maxFiles}` : ""}):\n${files.slice(0, maxFiles).join("\n") || "(empty repo)"}`];
+    for (const f of ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
+        const h = head(f, 40);
+        if (h)
+            parts.push(`${f}:\n${h}`);
+    }
+    const readme = files.find((f) => /^readme(\.md)?$/i.test(f));
+    if (readme) {
+        const h = head(readme, 40);
+        if (h)
+            parts.push(`${readme} (first 40 lines):\n${h}`);
+    }
+    // Small repo: show the source itself. A tool-less planner that only sees
+    // file names tries to "cat" them anyway (seen live: Sonnet replied with a
+    // fake bash call instead of a plan, Opus hung) and misses rules that live
+    // in code, like a test requiring every module in an index.
+    if (files.length <= 80) {
+        const rank = (f) => (/(^|\/)(index|main|app|registry|routes?)\.[a-z]+$/i.test(f) ? 0 : /(^|\/)(test|tests|__tests__)\/|\.(test|spec)\./i.test(f) ? 1 : 2);
+        const skip = /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|readme(\.md)?|package\.json)$|\.(png|jpe?g|gif|ico|pdf|zip|gz|woff2?|mp[34]|lock)$/i;
+        let budget = 24_000;
+        for (const f of [...files].sort((a, b) => rank(a) - rank(b))) {
+            if (skip.test(f))
+                continue;
+            let body;
+            try {
+                if (fs.statSync(path.join(cwd, f)).size > 4000)
+                    continue;
+                body = fs.readFileSync(path.join(cwd, f), "utf8");
+            }
+            catch {
+                continue;
+            }
+            if (body.includes("\u0000") || body.length > budget)
+                continue;
+            budget -= body.length;
+            parts.push(`${f}:\n${body.trimEnd()}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=brain.js.map