huddle-cli 0.0.0-stage → 0.1.0

package/dist/adapters/index.js

@@ -0,0 +1,135 @@
+// The adapter registry + detection/auth probing. This is what `huddle doctor`
+// uses to decide who's in the roster for a session. Because we only ever ask
+// "installed?" and "authed?", expiring subscriptions and account swaps are a
+// non-event: a failing probe just drops that agent, the session runs on.
+import { execFile, execFileSync } from "node:child_process";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { claudeAdapter } from "./claude.js";
+import { codexAdapter } from "./codex.js";
+import { geminiAdapter } from "./gemini.js";
+import { cursorAdapter } from "./cursor.js";
+import { antigravityAdapter } from "./antigravity.js";
+import { opencodeAdapter } from "./opencode.js";
+import { copilotAdapter } from "./copilot.js";
+import { ampAdapter } from "./amp.js";
+import { gooseAdapter } from "./goose.js";
+import { qwenAdapter } from "./qwen.js";
+import { droidAdapter } from "./droid.js";
+import { kiroAdapter } from "./kiro.js";
+import { loadAgentsFiles } from "./custom.js";
+export const ADAPTERS = [
+    claudeAdapter,
+    codexAdapter,
+    antigravityAdapter,
+    cursorAdapter,
+    geminiAdapter,
+    // Opt-in connectors: invisible until their CLI is installed (`optional`).
+    opencodeAdapter,
+    copilotAdapter,
+    ampAdapter,
+    gooseAdapter,
+    qwenAdapter,
+    droidAdapter,
+    kiroAdapter,
+];
+/**
+ * Only shown (and never offered for install) when already installed: legacy
+ * CLIs — Gemini CLI still works with an API key or a work account, but new
+ * personal users should use Antigravity — plus every `optional` connector, so
+ * a dozen CLIs you don't use never clutter the agents list.
+ */
+export const LEGACY = new Set(["gemini", ...ADAPTERS.filter((a) => a.optional).map((a) => a.id)]);
+/** Every built-in connector, before agents.json / env narrowing — for `huddle agents --all`. */
+export const BUILTIN_ADAPTERS = [...ADAPTERS];
+/** Problems found in ~/.huddle/agents.json or .huddle/agents.json — `huddle doctor` prints them. */
+export const AGENTS_FILE_ERRORS = [];
+// User-declared connectors (docs/ADAPTERS.md). HUDDLE_NO_AGENTS_FILE=1 skips
+// them, so a test run is never shaped by the machine's own files.
+if (!process.env.HUDDLE_NO_AGENTS_FILE) {
+    const r = loadAgentsFiles();
+    for (const a of r.adapters)
+        registerAdapter(a);
+    AGENTS_FILE_ERRORS.push(...r.errors);
+}
+/**
+ * Extra adapters, for tests and for trying out a new connector before it has
+ * a file here: HUDDLE_EXTRA_ADAPTERS is a comma-separated list of ES modules
+ * whose default export is an Adapter (or an array of them). Unset = nothing
+ * changes. In-process callers (tests) can use registerAdapter() instead.
+ */
+for (const mod of (process.env.HUDDLE_EXTRA_ADAPTERS ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
+    const m = await import(pathToFileURL(path.resolve(mod)).href);
+    for (const a of [m.default].flat())
+        registerAdapter(a);
+}
+// HUDDLE_ONLY_ADAPTERS=id,id narrows the roster to those ids — so a test run
+// of the real CLI can never wake (and bill) the real agents on this machine.
+const only = (process.env.HUDDLE_ONLY_ADAPTERS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+if (only.length)
+    ADAPTERS.splice(0, ADAPTERS.length, ...ADAPTERS.filter((a) => only.includes(a.id)));
+/** Add an adapter to the roster (same id = replaced). */
+export function registerAdapter(adapter) {
+    const i = ADAPTERS.findIndex((a) => a.id === adapter.id);
+    if (i >= 0)
+        ADAPTERS[i] = adapter;
+    else
+        ADAPTERS.push(adapter);
+    if (adapter.optional)
+        LEGACY.add(adapter.id);
+    else if (adapter.id !== "gemini")
+        LEGACY.delete(adapter.id);
+}
+function onPath(bin) {
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function run(cmd) {
+    try {
+        const stdout = execFileSync(cmd[0], cmd.slice(1), { encoding: "utf8", stdio: "pipe", timeout: 8000 });
+        return { code: 0, stdout, stderr: "" };
+    }
+    catch (e) {
+        return { code: e?.status ?? 1, stdout: e?.stdout?.toString() ?? "", stderr: e?.stderr?.toString() ?? "" };
+    }
+}
+/** Detect + auth-probe a single adapter. */
+export function probe(adapter) {
+    if (!onPath(adapter.bin)) {
+        return { adapter, state: "not_installed", detail: `'${adapter.bin}' not on PATH` };
+    }
+    const r = run(adapter.authProbe.cmd);
+    if (!adapter.authProbe.ok(r) || (adapter.authProbe.check && !adapter.authProbe.check())) {
+        return { adapter, state: "not_authed", detail: adapter.authProbe.fixHint };
+    }
+    return { adapter, state: "ready", detail: `${adapter.vendor} · ${adapter.accountNote ?? "ready"}` };
+}
+function runAsync(cmd) {
+    return new Promise((resolve) => {
+        execFile(cmd[0], cmd.slice(1), { encoding: "utf8", timeout: 8000 }, (err, stdout, stderr) => resolve({ code: err ? (typeof err.code === "number" ? err.code : 1) : 0, stdout, stderr }));
+    });
+}
+/** Non-blocking probe, so the welcome screen can animate while agents connect. */
+export async function probeAsync(adapter) {
+    if (!onPath(adapter.bin)) {
+        return { adapter, state: "not_installed", detail: `'${adapter.bin}' not on PATH` };
+    }
+    const r = await runAsync(adapter.authProbe.cmd);
+    if (!adapter.authProbe.ok(r) || (adapter.authProbe.check && !adapter.authProbe.check())) {
+        return { adapter, state: "not_authed", detail: adapter.authProbe.fixHint };
+    }
+    return { adapter, state: "ready", detail: `${adapter.vendor} · ${adapter.accountNote ?? "ready"}` };
+}
+/** Probe the whole roster. */
+export function probeAll() {
+    return ADAPTERS.map(probe);
+}
+export function getAdapter(id) {
+    return ADAPTERS.find((a) => a.id === id);
+}
+//# sourceMappingURL=index.js.map

package/dist/adapters/kiro.js

@@ -0,0 +1,41 @@
+// Kiro CLI (AWS) — headless via `kiro-cli chat --no-interactive`. Workspace
+// MCP servers come from .kiro/settings/mcp.json in the project root, so the
+// launcher writes the Plug into the worktree (kept out of commits). Auth is
+// Kiro's own (`kiro-cli login`: Builder ID, Identity Center, Google, GitHub);
+// `kiro-cli whoami` is the probe.
+//
+// Sources (checked 2026-10):
+//   https://kiro.dev/docs/cli/                   curl -fsSL https://cli.kiro.dev/install | bash
+//   https://kiro.dev/docs/reference/cli-commands/
+//     chat --no-interactive, --trust-all-tools, --trust-tools (exact internal ids), login, whoami
+//   https://kiro.dev/docs/cli/mcp/configuration/ <project-root>/.kiro/settings/mcp.json, mcpServers { command, args, env }
+// Approvals: a headless run can't approve anything, and --trust-tools needs
+// internal tool ids the docs don't list, so every mode trusts all tools; the
+// worktree is the fence. No model flag on `chat` in the reference, so none is
+// passed. No `ask`: no documented read-only headless mode. Not yet run live.
+export const kiroAdapter = {
+    id: "kiro",
+    vendor: "aws",
+    bin: "kiro-cli",
+    roles: ["worker"],
+    prefers: ["backend", "systems", "docs"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your Kiro login",
+    homepage: "https://kiro.dev/docs/cli/",
+    optional: true,
+    install: { cmd: "curl -fsSL https://cli.kiro.dev/install | bash", login: ["kiro-cli", "login"] },
+    authProbe: {
+        cmd: ["kiro-cli", "whoami"],
+        ok: (r) => r.code === 0 && !/not logged in/i.test(r.stdout + r.stderr),
+        fixHint: "run `kiro-cli login`",
+    },
+    plug: {
+        file: { path: ".kiro/settings/mcp.json", in: "worktree" },
+        entry: (plug) => ({ mcpServers: { huddle: plug } }),
+    },
+    launch: ({ worktree, prompt }) => ({
+        cmd: ["kiro-cli", "chat", "--no-interactive", "--trust-all-tools", prompt],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=kiro.js.map

package/dist/adapters/opencode.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// OpenCode (sst) — headless via `opencode run`. The Plug goes in a config file
+// in .huddle/run/ that OPENCODE_CONFIG points at; OpenCode MERGES config files,
+// so the user's own opencode.json (and their providers) still apply and nothing
+// lands in the worktree. Auth is OpenCode's own (`opencode auth login`, or a
+// provider API key in the environment).
+//
+// Sources (checked 2026-10):
+//   https://opencode.ai/docs/            install script, npm package opencode-ai
+//   https://opencode.ai/docs/cli/        run, -m provider/model, --agent, --auto, OPENCODE_PERMISSION, auth list
+//   https://opencode.ai/docs/config/     OPENCODE_CONFIG custom path, configs merge
+//   https://opencode.ai/docs/mcp-servers/  mcp.<name> { type: "local", command: [...], environment, enabled }
+//   https://opencode.ai/docs/permissions/  permission keys edit / bash / "*", values allow / ask / deny
+//   https://opencode.ai/docs/agents/     built-in "plan" agent is the restricted one
+// Not yet run live on this machine.
+// Headless: nobody can answer an "ask", so each mode decides up front.
+const PERMISSION = {
+    // edits yes, shell no — like Claude's acceptEdits
+    safe: JSON.stringify({ edit: "allow", bash: "deny", webfetch: "deny" }),
+    auto: null, // --auto: approve whatever isn't explicitly denied
+    yolo: JSON.stringify({ "*": "allow" }),
+};
+const authed = () => fs.existsSync(path.join(os.homedir(), ".local", "share", "opencode", "auth.json")) ||
+    ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY", "GROQ_API_KEY"].some((k) => !!process.env[k]);
+export const opencodeAdapter = {
+    id: "opencode",
+    vendor: "sst",
+    bin: "opencode",
+    roles: ["worker", "reviewer"],
+    prefers: ["backend", "refactor", "quickfix"],
+    // OpenCode wants provider/model; "" = whatever its owner configured.
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your OpenCode providers",
+    homepage: "https://opencode.ai/docs/",
+    optional: true,
+    install: { cmd: "curl -fsSL https://opencode.ai/install | bash", login: ["opencode", "auth", "login"] },
+    authProbe: {
+        cmd: ["opencode", "--version"],
+        ok: (r) => r.code === 0,
+        check: authed,
+        fixHint: "run `opencode auth login` (or set a provider API key)",
+    },
+    plug: {
+        file: { path: "opencode.json", in: "run-dir" },
+        entry: (plug) => ({
+            $schema: "https://opencode.ai/config.json",
+            mcp: { huddle: { type: "local", command: [plug.command, ...plug.args], environment: plug.env, enabled: true } },
+        }),
+    },
+    // The built-in "plan" agent is OpenCode's restricted, read-only one.
+    ask: ({ prompt, cwd, model }) => ({ cmd: ["opencode", "run", "--agent", "plan", ...(model ? ["-m", model] : []), prompt], cwd }),
+    launch: ({ worktree, prompt, model, mcpConfigPath, approvals }) => ({
+        cmd: ["opencode", "run", ...(model ? ["-m", model] : []), ...(approvals === "safe" ? [] : ["--auto"]), prompt],
+        cwd: worktree,
+        env: {
+            OPENCODE_CONFIG: mcpConfigPath,
+            ...(PERMISSION[approvals] ? { OPENCODE_PERMISSION: PERMISSION[approvals] } : {}),
+        },
+    }),
+};
+//# sourceMappingURL=opencode.js.map

package/dist/adapters/qwen.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { qwenUsage } from "./usage.js";
+// Qwen Code — headless via `qwen -p`. It reads MCP servers from
+// .qwen/settings.json in the project, so the launcher writes the Plug into the
+// worktree (the merge engine keeps it out of the commit). `trust: true` skips
+// Qwen's per-call confirmation for this one server, which a headless run
+// can't answer. Auth is Qwen's own (/auth inside `qwen`, or a provider key).
+//
+// Sources (checked 2026-10):
+//   https://qwenlm.github.io/qwen-code-docs/en/users/quickstart/         npm install -g @qwen-code/qwen-code@latest, /auth
+//   https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/  -p, -m/--model, --yolo,
+//     --approval-mode plan|default|auto-edit|auto|yolo, --output-format text|json|stream-json
+//   https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/       .qwen/settings.json mcpServers
+//     { command, args, env, trust }
+//   https://qwenlm.github.io/qwen-code-docs/en/users/configuration/trusted-folders/
+//     folder trust is OFF by default; if you turned it on, untrusted worktrees ignore .qwen/settings.json
+// Not yet run live on this machine.
+const authed = () => fs.existsSync(path.join(os.homedir(), ".qwen", "settings.json")) ||
+    ["DASHSCOPE_API_KEY", "OPENAI_API_KEY"].some((k) => !!process.env[k]);
+export const qwenAdapter = {
+    id: "qwen",
+    vendor: "alibaba",
+    bin: "qwen",
+    roles: ["worker", "reviewer"],
+    prefers: ["backend", "algorithms", "data"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your Qwen Code provider",
+    homepage: "https://qwenlm.github.io/qwen-code-docs/en/users/quickstart/",
+    optional: true,
+    install: {
+        cmd: "npm install -g @qwen-code/qwen-code@latest",
+        login: ["qwen"],
+        loginNote: "Qwen Code asks you to pick a provider on first run — once it's set, type /quit to come back to Huddle",
+    },
+    authProbe: {
+        cmd: ["qwen", "--version"],
+        ok: (r) => r.code === 0,
+        check: authed,
+        fixHint: "run `qwen` once and set up a provider with /auth",
+    },
+    plug: {
+        file: { path: ".qwen/settings.json", in: "worktree" },
+        entry: (plug) => ({ mcpServers: { huddle: { ...plug, trust: true } } }),
+    },
+    ask: ({ prompt, cwd, model }) => ({
+        cmd: ["qwen", "-p", prompt, "--approval-mode", "plan", ...(model ? ["-m", model] : [])],
+        cwd,
+    }),
+    usage: qwenUsage,
+    launch: ({ worktree, prompt, model, approvals }) => ({
+        cmd: [
+            "qwen",
+            ...(model ? ["-m", model] : []),
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json", // so Huddle can count tokens
+            ...(approvals === "safe" ? ["--approval-mode", "auto-edit"] : []),
+            ...(approvals === "auto" ? ["--approval-mode", "auto"] : []),
+            ...(approvals === "yolo" ? ["--yolo"] : []),
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=qwen.js.map

package/dist/adapters/types.js

@@ -0,0 +1,6 @@
+// An Adapter is the ENTIRE vendor-specific surface area of Huddle. It answers:
+// how do I detect you, how do I know you're logged in, how do I hand you the
+// Plug (MCP), and how do I launch you on a task. When a vendor changes a flag
+// or a new CLI appears, only a file like this changes — never the engine.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/usage.js

@@ -0,0 +1,141 @@
+// Token accounting. Every agent CLI can stream JSON events that include token
+// usage; each adapter maps one output line to a reading. Readings are either
+// a piece of usage (summed, deduped by `key`) or a final total (replaces the sum).
+//
+// "Tokens" = everything the provider reports processing: input (including
+// cached context) + output. It's what the run actually consumed.
+const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+function json(line) {
+    if (!line.startsWith("{"))
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+/** claude --output-format stream-json --verbose */
+export function claudeUsage(line) {
+    const e = json(line);
+    const u = e?.type === "result" ? e.usage : e?.type === "assistant" ? e.message?.usage : null;
+    if (!u)
+        return null;
+    const tokens = n(u.input_tokens) + n(u.cache_creation_input_tokens) + n(u.cache_read_input_tokens) + n(u.output_tokens);
+    const cached = n(u.cache_read_input_tokens);
+    return e.type === "result" ? { tokens, cached, total: true } : { tokens, cached, key: e.message?.id };
+}
+/** codex exec --json */
+export function codexUsage(line) {
+    const e = json(line);
+    if (e?.type !== "turn.completed" || !e.usage)
+        return null;
+    // input already includes cached
+    return { tokens: n(e.usage.input_tokens) + n(e.usage.output_tokens), cached: n(e.usage.cached_input_tokens) };
+}
+/** cursor-agent --output-format stream-json */
+export function cursorUsage(line) {
+    const e = json(line);
+    const u = e?.usage;
+    if (!u)
+        return null;
+    const tokens = n(u.inputTokens) + n(u.outputTokens) + n(u.cacheReadTokens) + n(u.cacheWriteTokens);
+    const cached = n(u.cacheReadTokens);
+    return e.type === "result" ? { tokens, cached, total: true } : { tokens, cached, key: e.request_id };
+}
+/** agy --output-format stream-json (also works for Gemini CLI's stream-json) */
+export function agyUsage(line) {
+    const e = json(line);
+    if (e?.event === "result" && e.result?.usage) {
+        const u = e.result.usage;
+        return { tokens: n(u.total_tokens) || n(u.input_tokens) + n(u.output_tokens), cached: n(u.cache_read_tokens), total: true };
+    }
+    if (e?.event === "step_update" && e.step_update?.usage && e.step_update.state === "DONE") {
+        const u = e.step_update.usage;
+        return {
+            tokens: n(u.total_tokens) || n(u.input_tokens) + n(u.output_tokens),
+            cached: n(u.cache_read_tokens),
+            key: String(e.step_update.step_index),
+        };
+    }
+    return null;
+}
+/**
+ * amp -x --stream-json — Claude-compatible messages, but per the Streaming JSON
+ * docs assistant messages carry no id and the final result has no usage, so
+ * each assistant turn's usage is summed.
+ */
+export function ampUsage(line) {
+    const e = json(line);
+    const u = e?.type === "assistant" ? e.message?.usage : null;
+    if (!u)
+        return null;
+    const tokens = n(u.input_tokens) + n(u.cache_creation_input_tokens) + n(u.cache_read_input_tokens) + n(u.output_tokens);
+    return { tokens, cached: n(u.cache_read_input_tokens) };
+}
+/**
+ * qwen -p --output-format stream-json — message shape matches Claude's
+ * (assistant messages with an id + usage, a final result with usage). The docs
+ * elide the usage fields, so both Anthropic- and OpenAI-style names are read.
+ * UNVERIFIED field names: no live run yet.
+ */
+export function qwenUsage(line) {
+    const e = json(line);
+    const u = e?.type === "result" ? e.usage : e?.type === "assistant" ? e.message?.usage : null;
+    if (!u)
+        return null;
+    const cached = n(u.cache_read_input_tokens) || n(u.cached_tokens) || n(u.cached_input_tokens);
+    const tokens = n(u.total_tokens) ||
+        n(u.input_tokens) + n(u.cache_creation_input_tokens) + n(u.cache_read_input_tokens) + n(u.output_tokens) ||
+        n(u.prompt_tokens) + n(u.completion_tokens);
+    if (!tokens)
+        return null;
+    return e.type === "result" ? { tokens, cached, total: true } : { tokens, cached, key: e.message?.id };
+}
+/** Accumulates readings into running totals. */
+export class UsageMeter {
+    byKey = new Map();
+    loose = { tokens: 0, cached: 0 };
+    final = null;
+    /** False until the agent has reported anything (some only report at the end). */
+    seen = false;
+    add(r) {
+        this.seen = true;
+        const p = { tokens: r.tokens, cached: r.cached ?? 0 };
+        if (r.total)
+            this.final = p;
+        else if (r.key)
+            this.byKey.set(r.key, p);
+        else
+            this.loose = { tokens: this.loose.tokens + p.tokens, cached: this.loose.cached + p.cached };
+    }
+    sum() {
+        if (this.final)
+            return this.final;
+        const s = { ...this.loose };
+        for (const v of this.byKey.values())
+            (s.tokens += v.tokens), (s.cached += v.cached);
+        return s;
+    }
+    get tokens() {
+        return this.sum().tokens;
+    }
+    get cached() {
+        return this.sum().cached;
+    }
+}
+export function fmtTokens(t) {
+    if (t < 1000)
+        return `${t}`;
+    if (t < 1_000_000)
+        return `${(t / 1000).toFixed(t < 10_000 ? 1 : 0)}k`;
+    return `${(t / 1_000_000).toFixed(1)}M`;
+}
+export function fmtDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    return m < 60 ? `${m}m${String(s % 60).padStart(2, "0")}s` : `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+//# sourceMappingURL=usage.js.map