huddle-cli 0.0.0-stage → 0.1.1

package/dist/adapters/claude.js

@@ -0,0 +1,86 @@
+import { claudeUsage } from "./usage.js";
+// Claude Code — launched headless with `-p`. The Plug is handed over with
+// --mcp-config pointing at a file in .huddle/run/, so nothing lands in the
+// agent's worktree. Auth is Claude's own (OAuth or ANTHROPIC_API_KEY); Huddle
+// never touches it.
+const PERMISSIONS = {
+    safe: ["--permission-mode", "acceptEdits", "--allowedTools", "mcp__huddle"],
+    // Claude's own auto mode: a safety check approves routine actions.
+    auto: ["--permission-mode", "auto", "--allowedTools", "mcp__huddle"],
+    yolo: ["--dangerously-skip-permissions"],
+};
+export const claudeAdapter = {
+    id: "claude",
+    vendor: "anthropic",
+    bin: "claude",
+    roles: ["orchestrator", "worker", "reviewer"],
+    prefers: ["frontend", "design", "product", "refactor"],
+    // CLI aliases, not dated ids — Claude Code resolves them to the latest model.
+    models: { orchestrator: "opus", worker: "opus", fast: "haiku", reviewer: "opus" },
+    accountNote: "personal Anthropic",
+    // https://code.claude.com/docs/en/setup · sign-in: https://code.claude.com/docs/en/cli-reference
+    install: {
+        cmd: "curl -fsSL https://claude.ai/install.sh | bash",
+        win: "irm https://claude.ai/install.ps1 | iex",
+        login: ["claude", "auth", "login"],
+    },
+    authProbe: {
+        // `claude auth status` (JSON by default, verified on 2.1.300): exit 0 +
+        // "loggedIn": true when signed in (OAuth or ANTHROPIC_API_KEY), exit 1 +
+        // "loggedIn": false when not. `--version` used to be the probe, which showed
+        // a signed-out Claude as ready.
+        cmd: ["claude", "auth", "status"],
+        ok: (r) => r.code === 0 && !/"loggedIn"\s*:\s*false/.test(r.stdout),
+        fixHint: "run `claude auth login` (or set ANTHROPIC_API_KEY)",
+    },
+    plug: {
+        file: { path: "claude-mcp.json", in: "run-dir" },
+        entry: (plug) => ({ mcpServers: { huddle: { type: "stdio", ...plug } } }),
+    },
+    // Read-only questions never need your personal MCP servers (Gmail, Drive, …).
+    // Self-contained prompts go further: safe mode + no tools ≈ 15k tokens of
+    // context instead of ~38k (or 200k+ on Haiku, which loads every tool eagerly).
+    ask: ({ prompt, cwd, model, noTools }) => ({
+        cmd: [
+            "claude",
+            "-p",
+            prompt,
+            "--model",
+            model || "opus",
+            ...(noTools ? ["--safe-mode", "--tools", ""] : ["--permission-mode", "plan", "--strict-mcp-config"]),
+        ],
+        cwd,
+    }),
+    // `claude -p` with no prompt argument reads it from stdin.
+    stdinPrompt: "",
+    usage: claudeUsage,
+    // A PostToolUse hook, loaded with --settings (a file in .huddle/run/, never
+    // the user's settings): after any tool call, `huddle mail --hook` prints
+    // {hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext}} when
+    // a teammate wrote, and nothing otherwise. Schema per
+    // https://code.claude.com/docs/en/hooks; --settings per `claude --help` (2.1.300).
+    mailHook: (command) => ({ hooks: { PostToolUse: [{ matcher: "*", hooks: [{ type: "command", command, timeout: 5 }] }] } }),
+    launch: ({ worktree, prompt, model, mcpConfigPath, approvals, context, hookSettingsPath }) => ({
+        cmd: [
+            "claude",
+            "-p",
+            prompt,
+            // The shared screen lives outside the worktree; Read opens its images and PDFs.
+            ...(context ? ["--add-dir", context.dir] : []),
+            ...(model ? ["--model", model] : []),
+            ...PERMISSIONS[approvals],
+            "--mcp-config",
+            mcpConfigPath,
+            // Only Huddle's Plug — not your personal MCP servers. Smaller context
+            // every turn, and a headless agent can't reach your Gmail/Drive/etc.
+            "--strict-mcp-config",
+            ...(hookSettingsPath ? ["--settings", hookSettingsPath] : []),
+            // JSON events so Huddle can count tokens live (logs stay in .huddle/logs)
+            "--output-format",
+            "stream-json",
+            "--verbose",
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=claude.js.map

package/dist/adapters/codex.js

@@ -0,0 +1,64 @@
+import { codexUsage } from "./usage.js";
+// OpenAI Codex CLI — runs non-interactively via `codex exec`. The Plug is
+// passed as `-c mcp_servers.huddle.*` overrides, so neither ~/.codex/config.toml
+// nor the worktree is touched. Auth is `codex login` (ChatGPT) or OPENAI_API_KEY.
+const toml = (v) => JSON.stringify(v); // strings/arrays are valid TOML as JSON
+const tomlTable = (o) => `{${Object.entries(o).map(([k, v]) => `${k}=${toml(v)}`).join(",")}}`;
+export const codexAdapter = {
+    id: "codex",
+    vendor: "openai",
+    bin: "codex",
+    roles: ["worker", "reviewer"],
+    prefers: ["systems", "algorithms", "refactor", "backend"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "personal OpenAI",
+    install: { cmd: "npm install -g @openai/codex", login: ["codex", "login"] },
+    authProbe: {
+        // `codex login status` exits non-zero when not authenticated.
+        cmd: ["codex", "login", "status"],
+        ok: (r) => r.code === 0,
+        fixHint: "run `codex login` (or set OPENAI_API_KEY)",
+    },
+    plug: {},
+    // exec streams its work to stdout; -o captures just the final answer.
+    ask: ({ prompt, cwd, outFile, model }) => ({
+        cmd: ["codex", "exec", "--sandbox", "read-only", ...(model ? ["-m", model] : []), "-o", outFile, prompt],
+        cwd,
+        usesOutFile: true,
+    }),
+    // `codex exec -`: "instructions are read from stdin".
+    stdinPrompt: "-",
+    usage: codexUsage,
+    launch: ({ worktree, prompt, model, plug, approvals, context }) => ({
+        cmd: [
+            "codex",
+            "exec",
+            // `codex exec -i/--image <FILE>`: screenshots the planner linked to this task, attached to the prompt.
+            // One flag per file, before the other flags, so the list never swallows the prompt.
+            ...(context?.images ?? []).flatMap((f) => ["--image", f]),
+            "--json", // JSON events so Huddle can count tokens live
+            ...(model ? ["--model", model] : []),
+            "-c",
+            `mcp_servers.huddle.command=${toml(plug.command)}`,
+            "-c",
+            `mcp_servers.huddle.args=${toml(plug.args)}`,
+            "-c",
+            `mcp_servers.huddle.env=${tomlTable(plug.env)}`,
+            // Headless: nobody can click "allow", and Codex refuses unapproved MCP
+            // calls under exec. The Plug is Huddle's own server, so pre-approve it.
+            "-c",
+            `mcp_servers.huddle.default_tools_approval_mode="approve"`,
+            // `codex exec` never stops to ask; its sandbox confines commands to the
+            // worktree. Without network, the sandbox also refuses to listen on
+            // localhost: seen live on the capstone, Codex couldn't run its own HTTP
+            // API tests ("26 HTTP tests blocked by sandbox listen EPERM"). `auto`
+            // runs commands freely, so it gets network; `safe` stays offline.
+            ...(approvals === "yolo"
+                ? ["--dangerously-bypass-approvals-and-sandbox"]
+                : ["--sandbox", "workspace-write", ...(approvals === "auto" ? ["-c", "sandbox_workspace_write.network_access=true"] : [])]),
+            prompt,
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=codex.js.map

package/dist/adapters/copilot.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// GitHub Copilot CLI — headless via `copilot -p`. The Plug goes in a file in
+// .huddle/run/ handed over with --additional-mcp-config=@<file>, which adds a
+// server "for this session only": ~/.copilot/mcp-config.json is never touched.
+// Auth is Copilot's own (`copilot login`, or COPILOT_GITHUB_TOKEN / GH_TOKEN).
+//
+// Sources (checked 2026-10):
+//   https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli
+//     npm install -g @github/copilot · brew install --cask copilot-cli · curl -fsSL https://gh.io/copilot-install | bash
+//   https://docs.github.com/en/copilot/reference/cli-command-reference
+//     -p/--prompt, --model=MODEL, --allow-tool=TOOL (comma list), --deny-tool, --allow-all-tools,
+//     --allow-all, --no-ask-user, --disable-builtin-mcps, -s/--silent,
+//     --additional-mcp-config=JSON or @file, local server fields { type, command, args, env, tools },
+//     permission patterns: SERVER-NAME (all of that server's tools), write, read, shell(git push)
+// Not yet run live on this machine. The reference says --allow-all-tools is
+// "required when using the CLI programmatically"; safe mode instead pre-allows
+// just the Plug + file edits, so if Copilot refuses it, use auto.
+const PERMISSIONS = {
+    safe: ["--allow-tool=huddle,write,read"],
+    auto: ["--allow-all-tools", "--deny-tool=shell(git push)"],
+    yolo: ["--allow-all"],
+};
+const authed = () => ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"].some((k) => !!process.env[k]) ||
+    fs.existsSync(process.env.COPILOT_HOME ?? path.join(os.homedir(), ".copilot"));
+export const copilotAdapter = {
+    id: "copilot",
+    vendor: "github",
+    bin: "copilot",
+    roles: ["worker", "reviewer"],
+    prefers: ["frontend", "backend", "quickfix"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your GitHub Copilot plan",
+    homepage: "https://docs.github.com/en/copilot/how-tos/copilot-cli",
+    optional: true,
+    install: { cmd: "npm install -g @github/copilot", login: ["copilot", "login"] },
+    authProbe: {
+        cmd: ["copilot", "--version"],
+        ok: (r) => r.code === 0,
+        // Copilot has no "login status" command; a token or its config dir is the best cheap signal.
+        check: authed,
+        fixHint: "run `copilot login` (or set COPILOT_GITHUB_TOKEN)",
+    },
+    plug: {
+        file: { path: "copilot-mcp.json", in: "run-dir" },
+        entry: (plug) => ({ mcpServers: { huddle: { type: "local", ...plug, tools: ["*"] } } }),
+    },
+    ask: ({ prompt, cwd, model }) => ({
+        cmd: ["copilot", "-p", prompt, "-s", "--no-ask-user", "--deny-tool=write", "--deny-tool=shell", ...(model ? [`--model=${model}`] : [])],
+        cwd,
+    }),
+    launch: ({ worktree, prompt, model, mcpConfigPath, approvals }) => ({
+        cmd: [
+            "copilot",
+            "-p",
+            prompt,
+            ...(model ? [`--model=${model}`] : []),
+            `--additional-mcp-config=@${mcpConfigPath}`,
+            // Only Huddle's Plug on top of yours — not the built-in GitHub server,
+            // so a headless agent can't open issues/PRs on your account.
+            "--disable-builtin-mcps",
+            "--no-ask-user", // nobody is there to answer
+            ...PERMISSIONS[approvals],
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=copilot.js.map

package/dist/adapters/cursor.js

@@ -0,0 +1,92 @@
+import { spawnToolSync } from "../platform.js";
+import { cursorUsage } from "./usage.js";
+/**
+ * The model for quick prompt-only answers (council turns, cross-reviews), or
+ * undefined = cursor-agent's default (Auto). Found live (capstone, both
+ * rounds): Cursor's council critique timed out at 2 min. Probed with the same
+ * prompt and no tools used: Auto spent 126s thinking (12k chars) before a
+ * 120-word answer; composer-2.5 answered as well in 21s. Model ids depend on
+ * the account, so this picks only from what `cursor-agent --list-models`
+ * lists here (a "composer-<version>" id, Cursor's own fast model), once per
+ * process. HUDDLE_CURSOR_FAST_MODEL=<id> chooses one; =auto keeps the default.
+ */
+let fastPick;
+export function cursorFastModel(list = listCursorModels) {
+    const env = process.env.HUDDLE_CURSOR_FAST_MODEL?.trim();
+    if (env)
+        return env === "auto" ? undefined : env;
+    if (fastPick)
+        return fastPick.model;
+    let out = "";
+    try {
+        out = list();
+    }
+    catch {
+        /* not installed / signed out: keep the default */
+    }
+    const ids = out.split(/\r?\n/).map((l) => /^\s*([\w.-]+)\s+-\s/.exec(l)?.[1]).filter((x) => !!x);
+    fastPick = { model: ids.find((id) => /^composer-[\d.]+$/.test(id)) };
+    return fastPick.model;
+}
+/** For tests: forget the cached pick. */
+export function resetCursorFastModel() {
+    fastPick = undefined;
+}
+function listCursorModels() {
+    const r = spawnToolSync(["cursor-agent", "--list-models"], { encoding: "utf8", timeout: 15_000 });
+    return r.status === 0 ? r.stdout : "";
+}
+// Cursor CLI (cursor-agent) — headless coding agent. Personal, team or SSO
+// account: Huddle doesn't care. `cursor-agent` owns its own login (SSO
+// included); Huddle only checks that the login succeeded, then shells out to it.
+export const cursorAdapter = {
+    id: "cursor",
+    vendor: "cursor",
+    bin: "cursor-agent",
+    roles: ["worker"],
+    prefers: ["in-editor-edits", "frontend", "quickfix"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your Cursor account (SSO handled by cursor-agent itself)",
+    // https://cursor.com/docs/cli/installation (native Windows: PowerShell)
+    install: {
+        cmd: "curl https://cursor.com/install -fsS | bash",
+        win: "irm 'https://cursor.com/install?win32=true' | iex",
+        login: ["cursor-agent", "login"],
+    },
+    authProbe: {
+        cmd: ["cursor-agent", "status"],
+        ok: (r) => r.code === 0 && !/not logged in/i.test(r.stdout + r.stderr),
+        fixHint: "run `cursor-agent login` (SSO works too — Huddle never sees it)",
+    },
+    plug: {
+        // cursor-agent reads project MCP from .cursor/mcp.json in its cwd.
+        file: { path: ".cursor/mcp.json", in: "worktree" },
+        entry: (plug) => ({ mcpServers: { huddle: plug } }),
+    },
+    ask: ({ prompt, cwd, model, quick }) => {
+        // Quick asks (council turns, reviews) get the fast model when the account has one; the brain keeps its own.
+        const m = model || (quick ? cursorFastModel() : undefined);
+        return { cmd: ["cursor-agent", "-p", prompt, "--mode", "ask", "--trust", ...(m ? ["--model", m] : [])], cwd };
+    },
+    usage: cursorUsage,
+    launch: ({ worktree, prompt, model, approvals, context }) => ({
+        cmd: [
+            "cursor-agent",
+            "-p",
+            prompt,
+            // No image flag on cursor-agent: the shared screen's folder, so its tools can open items by path.
+            ...(context ? ["--add-dir", context.dir] : []),
+            ...(model ? ["--model", model] : []),
+            // headless: trust the worktree and the Plug without prompting
+            "--trust",
+            "--approve-mcps",
+            "--output-format",
+            "stream-json", // so Huddle can count tokens
+            ...(approvals === "safe" ? ["--sandbox", "enabled"] : []),
+            ...(approvals === "auto" ? ["--force", "--sandbox", "enabled"] : []),
+            ...(approvals === "yolo" ? ["--force", "--sandbox", "disabled"] : []),
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=cursor.js.map

package/dist/adapters/custom.js

@@ -0,0 +1,342 @@
+// User-defined connectors: any agent CLI that can run headless and speak MCP
+// can join Huddle by being DECLARED, no code and no release needed.
+//
+//   ~/.huddle/agents.json        yours, on this machine (HUDDLE_HOME moves it)
+//   <repo>/.huddle/agents.json   this repo only (must not be committed — see below)
+//
+// A file is { "agents": [ <spec>, … ] } (a bare array works too). Each spec
+// becomes a normal Adapter; the same id as a built-in replaces it, which is
+// how you work around a vendor renaming a flag before Huddle ships a fix.
+// Templates use {placeholders}; see docs/ADAPTERS.md for the full reference
+// and a worked example.
+//
+// Safety: a spec names a program Huddle will run, so a repo's own file is
+// only honored while it is untracked. A cloned repo can't smuggle in an agent.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { agyUsage, ampUsage, claudeUsage, codexUsage, cursorUsage, qwenUsage } from "./usage.js";
+/** Token parsers a spec can reuse by name (`"usage": "claude"`). */
+export const USAGE_PARSERS = {
+    claude: claudeUsage, // also any CLI that emits Claude-style stream-json
+    codex: codexUsage,
+    cursor: cursorUsage,
+    agy: agyUsage,
+    gemini: agyUsage,
+    amp: ampUsage,
+    qwen: qwenUsage,
+};
+const SPEC_KEYS = new Set([
+    "id", "bin", "launch", "vendor", "approvals", "ask", "askOutFile", "plug", "env", "install", "installWin", "login", "loginNote",
+    "auth", "usage", "roles", "prefers", "models", "accountNote", "homepage", "optional", "$comment",
+]);
+const ROLES = new Set(["orchestrator", "worker", "reviewer", "fast"]);
+/** Placeholders that expand to several tokens when they are a whole token. */
+const SPREAD = new Set(["approvals", "plug.args", "plug.argv"]);
+const LAUNCH_VARS = new Set(["prompt", "worktree", "model", "mcpConfigPath", "plug.command", "plug.json", "plug.server", ...SPREAD]);
+const ASK_VARS = new Set(["prompt", "cwd", "model", "outFile"]);
+/** Placeholders that hand over the Plug (so the agent actually gets huddle_* tools). */
+const PLUG_VARS = ["mcpConfigPath", "plug.command", "plug.json", "plug.server", "plug.args", "plug.argv"];
+// {name}; {{name}} is left alone, so another tool's own templates pass through.
+const PH = /(?<!\{)\{([a-zA-Z][\w.]*)\}(?!\})/g;
+const placeholders = (s) => [...s.matchAll(PH)].map((m) => m[1]);
+const flatStrings = (t) => t.flatMap((a) => (Array.isArray(a) ? a : [a]));
+const isStrArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+/** Check one spec; returns problems (empty = valid). */
+export function validateSpec(raw) {
+    const errs = [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return ["must be an object"];
+    const s = raw;
+    for (const k of Object.keys(s))
+        if (!SPEC_KEYS.has(k))
+            errs.push(`unknown field "${k}"`);
+    if (typeof s.id !== "string" || !/^[a-z0-9][a-z0-9_-]*$/.test(s.id))
+        errs.push(`"id" must be lowercase letters, digits, - or _`);
+    if (typeof s.bin !== "string" || !s.bin.trim())
+        errs.push(`"bin" must name the executable`);
+    const checkTemplate = (field, t, allowed) => {
+        if (!Array.isArray(t) || !t.length || !t.every((a) => typeof a === "string" || isStrArray(a))) {
+            errs.push(`"${field}" must be a non-empty array of strings (or [string, …] groups)`);
+            return;
+        }
+        const strs = flatStrings(t);
+        for (const v of strs.flatMap(placeholders))
+            if (!allowed.has(v))
+                errs.push(`"${field}" uses unknown placeholder {${v}}`);
+        for (const str of strs)
+            for (const v of placeholders(str))
+                if (SPREAD.has(v) && str !== `{${v}}`)
+                    errs.push(`{${v}} must be a whole token in "${field}"`);
+        if (!strs.some((x) => placeholders(x).includes("prompt")))
+            errs.push(`"${field}" must include {prompt}`);
+    };
+    checkTemplate("launch", s.launch, LAUNCH_VARS);
+    if (s.ask !== undefined)
+        checkTemplate("ask", s.ask, ASK_VARS);
+    if (s.approvals !== undefined) {
+        const a = s.approvals;
+        if (!a || typeof a !== "object" || Array.isArray(a))
+            errs.push(`"approvals" must be {safe?, auto?, yolo?}`);
+        else
+            for (const [k, v] of Object.entries(a)) {
+                if (!["safe", "auto", "yolo"].includes(k))
+                    errs.push(`"approvals.${k}": modes are safe, auto, yolo`);
+                else if (!isStrArray(v))
+                    errs.push(`"approvals.${k}" must be an array of strings`);
+            }
+    }
+    let hasFile = false;
+    if (s.plug !== undefined) {
+        const p = s.plug;
+        if (!p || typeof p !== "object" || typeof p.file !== "string" || !p.file)
+            errs.push(`"plug.file" must be a path`);
+        else {
+            hasFile = true;
+            if (path.isAbsolute(p.file) || p.file.split(/[\\/]/).includes(".."))
+                errs.push(`"plug.file" must be relative, inside the worktree or run dir`);
+            if (p.in !== undefined && p.in !== "worktree" && p.in !== "run-dir")
+                errs.push(`"plug.in" is "worktree" or "run-dir"`);
+            for (const k of Object.keys(p))
+                if (!["file", "in", "entry"].includes(k))
+                    errs.push(`unknown field "plug.${k}"`);
+        }
+    }
+    if (s.env !== undefined) {
+        const e = s.env;
+        if (!e || typeof e !== "object" || Array.isArray(e) || !Object.values(e).every((v) => typeof v === "string"))
+            errs.push(`"env" must map names to strings`);
+        else
+            for (const v of Object.values(e).flatMap(placeholders))
+                if (!LAUNCH_VARS.has(v) || SPREAD.has(v))
+                    errs.push(`"env" uses unknown placeholder {${v}}`);
+    }
+    // The whole point is the Plug: refuse a spec that would join without huddle_* tools.
+    const used = [...(Array.isArray(s.launch) ? flatStrings(s.launch) : []), ...Object.values(s.env ?? {})]
+        .filter((x) => typeof x === "string")
+        .flatMap(placeholders);
+    if (!hasFile && used.includes("mcpConfigPath"))
+        errs.push(`{mcpConfigPath} needs "plug.file"`);
+    if (!hasFile && !used.some((v) => PLUG_VARS.includes(v)))
+        errs.push(`no way to hand it the Plug: set "plug.file", or use {plug.json} / {plug.command} {plug.args} in "launch"`);
+    if (s.login !== undefined && !isStrArray(s.login))
+        errs.push(`"login" must be an array of strings`);
+    if (s.install !== undefined && typeof s.install !== "string")
+        errs.push(`"install" must be a shell command string`);
+    if (s.installWin !== undefined && typeof s.installWin !== "string")
+        errs.push(`"installWin" must be a PowerShell command string`);
+    if (s.auth !== undefined) {
+        const a = s.auth;
+        if (!a || typeof a !== "object")
+            errs.push(`"auth" must be an object`);
+        else {
+            if (a.cmd !== undefined && (!isStrArray(a.cmd) || !a.cmd.length))
+                errs.push(`"auth.cmd" must be a non-empty array of strings`);
+            if (a.failPattern !== undefined) {
+                try {
+                    new RegExp(String(a.failPattern), "i");
+                }
+                catch {
+                    errs.push(`"auth.failPattern" is not a valid regex`);
+                }
+            }
+        }
+    }
+    if (s.usage !== undefined && !(typeof s.usage === "string" && s.usage in USAGE_PARSERS))
+        errs.push(`"usage" is one of: ${Object.keys(USAGE_PARSERS).join(", ")}`);
+    if (s.roles !== undefined && !(isStrArray(s.roles) && s.roles.every((r) => ROLES.has(r))))
+        errs.push(`"roles" are orchestrator, worker, reviewer, fast`);
+    if (s.prefers !== undefined && !isStrArray(s.prefers))
+        errs.push(`"prefers" must be an array of strings`);
+    if (s.models !== undefined) {
+        const m = s.models;
+        if (!m || typeof m !== "object" || !Object.entries(m).every(([k, v]) => ROLES.has(k) && typeof v === "string"))
+            errs.push(`"models" maps orchestrator/worker/fast/reviewer to model names`);
+    }
+    return errs;
+}
+/**
+ * Fill a command template. A whole-token {approvals}/{plug.args}/{plug.argv}
+ * spreads into several tokens; a token or [group] whose placeholders are all
+ * empty (e.g. no model configured) is dropped instead of passing "".
+ */
+export function renderTemplate(t, vars) {
+    // `empty`: some placeholder in the token had no value — "--model={model}" with no model.
+    const one = (s) => {
+        const whole = s.match(/^\{([\w.]+)\}$/);
+        if (whole && Array.isArray(vars[whole[1]])) {
+            const arr = vars[whole[1]];
+            return { out: arr, empty: !arr.length };
+        }
+        let empty = false;
+        const out = s.replace(PH, (_, k) => {
+            const v = vars[k];
+            const str = Array.isArray(v) ? v.join(" ") : (v ?? "");
+            if (!str)
+                empty = true;
+            return str;
+        });
+        return { out: [out], empty };
+    };
+    const cmd = [];
+    for (const a of t) {
+        const parts = (Array.isArray(a) ? a : [a]).map(one);
+        if (parts.some((p) => p.empty))
+            continue;
+        cmd.push(...parts.flatMap((p) => p.out));
+    }
+    return cmd;
+}
+/** Fill a JSON template: "{plug.args}"/"{plug.argv}"/"{plug.env}" as whole strings become real arrays/objects. */
+function renderJson(v, plug) {
+    if (typeof v === "string") {
+        if (v === "{plug.args}")
+            return plug.args;
+        if (v === "{plug.argv}")
+            return [plug.command, ...plug.args];
+        if (v === "{plug.env}")
+            return plug.env;
+        return v.replace(/\{plug\.command\}/g, plug.command);
+    }
+    if (Array.isArray(v))
+        return v.map((x) => renderJson(x, plug));
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, renderJson(x, plug)]));
+    return v;
+}
+/** Turn a validated spec into an Adapter. */
+export function specToAdapter(spec, source) {
+    const authCmd = spec.auth?.cmd ?? [spec.bin, "--version"];
+    const fail = spec.auth?.failPattern ? new RegExp(spec.auth.failPattern, "i") : null;
+    const plugFile = spec.plug?.file;
+    const server = (plug) => ({ command: plug.command, args: plug.args, env: plug.env });
+    return {
+        id: spec.id,
+        vendor: spec.vendor ?? spec.id,
+        bin: spec.bin,
+        roles: spec.roles ?? (spec.ask ? ["worker", "reviewer"] : ["worker"]),
+        prefers: spec.prefers ?? [],
+        models: { orchestrator: "", worker: "", fast: "", reviewer: "", ...spec.models },
+        install: { cmd: spec.install ?? "", ...(spec.installWin !== undefined ? { win: spec.installWin } : {}), login: spec.login, loginNote: spec.loginNote },
+        authProbe: {
+            cmd: authCmd,
+            ok: (r) => r.code === 0 && !(fail && fail.test(r.stdout + r.stderr)),
+            fixHint: spec.auth?.fixHint ?? `sign in to ${spec.bin} the way its docs say`,
+        },
+        plug: plugFile
+            ? {
+                file: { path: plugFile, in: spec.plug.in ?? "run-dir" },
+                entry: (plug) => (spec.plug.entry !== undefined ? renderJson(spec.plug.entry, plug) : { mcpServers: { huddle: server(plug) } }),
+            }
+            : {},
+        launch: (ctx) => {
+            const vars = {
+                prompt: ctx.prompt,
+                worktree: ctx.worktree,
+                model: ctx.model,
+                mcpConfigPath: ctx.mcpConfigPath ?? "",
+                approvals: spec.approvals?.[ctx.approvals] ?? [],
+                "plug.command": ctx.plug.command,
+                "plug.args": ctx.plug.args,
+                "plug.argv": [ctx.plug.command, ...ctx.plug.args],
+                "plug.json": JSON.stringify({ huddle: server(ctx.plug) }),
+                "plug.server": JSON.stringify(server(ctx.plug)),
+            };
+            const env = spec.env
+                ? Object.fromEntries(Object.entries(spec.env).map(([k, v]) => [k, renderTemplate([v], vars)[0] ?? ""]))
+                : undefined;
+            return { cmd: [spec.bin, ...renderTemplate(spec.launch, vars)], cwd: ctx.worktree, env };
+        },
+        ask: spec.ask
+            ? ({ prompt, cwd, outFile, model }) => ({
+                cmd: [spec.bin, ...renderTemplate(spec.ask, { prompt, cwd, outFile, model: model ?? "" })],
+                cwd,
+                usesOutFile: spec.askOutFile,
+            })
+            : undefined,
+        usage: spec.usage ? USAGE_PARSERS[spec.usage] : undefined,
+        accountNote: spec.accountNote ?? (source ? `from ${tildify(source)}` : undefined),
+        homepage: spec.homepage,
+        optional: spec.optional,
+        source,
+    };
+}
+/** Parse one agents.json's text. Invalid specs are skipped (and reported); valid ones still load. */
+export function parseAgentsJson(text, source) {
+    const where = tildify(source);
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (e) {
+        return { adapters: [], errors: [`${where}: not valid JSON (${e?.message ?? e})`] };
+    }
+    const list = Array.isArray(doc) ? doc : doc?.agents;
+    if (!Array.isArray(list))
+        return { adapters: [], errors: [`${where}: expected { "agents": [ … ] }`] };
+    const out = { adapters: [], errors: [] };
+    const seen = new Set();
+    list.forEach((raw, i) => {
+        const name = typeof raw?.id === "string" ? raw.id : `#${i + 1}`;
+        const errs = validateSpec(raw);
+        if (!errs.length && seen.has(name))
+            errs.push(`id "${name}" is declared twice`);
+        if (errs.length)
+            return void out.errors.push(...errs.map((e) => `${where} · ${name}: ${e}`));
+        seen.add(name);
+        out.adapters.push(specToAdapter(raw, source));
+    });
+    return out;
+}
+/** The two places agents.json lives, for this machine and (optionally) this repo. */
+export function agentsFiles(repoRoot) {
+    const home = process.env.HUDDLE_HOME ?? path.join(os.homedir(), ".huddle");
+    return { user: path.join(home, "agents.json"), repo: repoRoot ? path.join(repoRoot, ".huddle", "agents.json") : null };
+}
+function tracked(repoRoot, file) {
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", path.relative(repoRoot, file)], { cwd: repoRoot, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function gitRoot(cwd) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: "pipe" }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Load user then repo agents.json (repo wins on the same id). Missing files are fine. */
+export function loadAgentsFiles(opts = {}) {
+    const repoRoot = opts.repoRoot !== undefined ? opts.repoRoot : gitRoot(opts.cwd ?? process.cwd());
+    const files = agentsFiles(repoRoot);
+    const out = { adapters: [], errors: [] };
+    for (const file of [files.user, files.repo]) {
+        if (!file || !fs.existsSync(file))
+            continue;
+        if (file === files.repo && repoRoot && tracked(repoRoot, file)) {
+            out.errors.push(`${tildify(file)}: ignored — it is committed to git, and a repo can't add agents to your machine. Move it to ${tildify(files.user)}.`);
+            continue;
+        }
+        const r = parseAgentsJson(fs.readFileSync(file, "utf8"), file);
+        for (const a of r.adapters) {
+            const i = out.adapters.findIndex((x) => x.id === a.id);
+            if (i >= 0)
+                out.adapters[i] = a;
+            else
+                out.adapters.push(a);
+        }
+        out.errors.push(...r.errors);
+    }
+    return out;
+}
+function tildify(p) {
+    const home = os.homedir();
+    return p.startsWith(home + path.sep) ? "~" + p.slice(home.length) : p;
+}
+//# sourceMappingURL=custom.js.map