huddle-cli 0.1.1 → 0.1.5

package/dist/cli.js

@@ -8,17 +8,22 @@
 //     --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)
+//     --budget=5M                 tokens this run may use: new work stops at 90%, agents at 120%
 //     --with <file|dir|glob>      put files on the shared screen first (repeatable); piped stdin too
 //   huddle setup                install + sign in to the agents you pick (asks first)
 //   huddle doctor               is this machine ready: node, git, room db, your agents
 //   huddle agents               your agents: ready / not signed in / not installed, used or skipped
 //   huddle agents use|skip <ids>  choose who works with you (remembered)
 //   huddle --version            print the version
-//   huddle agents --all         every connector (built in + agents.json) and how to get it
+//   huddle update               install the newest huddle-cli from npm (--update too)
+//   huddle agents --all         every agent (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 built on whose idea, who said what to whom, merges
+//   huddle brief [--run n]      the hand-off brief a solo agent reads after a run (off|on: the CLAUDE.md/AGENTS.md pointer)
+//   huddle runs                 every run in this repo: goal, agents, result, cost
+//   huddle export [run]         a run as summary / chat / full transcript (md, html, json)
 //   huddle lessons              what Huddle learned across runs (--forget <id>, --clear)
 //   huddle init                 set up .huddle/ in this repo (automatic on first run)
 //   huddle up | down            attach mode: start/stop this repo's live room
@@ -33,6 +38,7 @@
 //   huddle mail --hook          (internal) Claude's post-tool hook: teammates' new messages
 import { packageInfo } from "./preflight.js"; // first: refuses old Node before anything else loads
 import { C, useAsciiOutput } from "./ui/term.js";
+import { asGoal } from "./args.js";
 import { SqliteUnavailableError } from "./room/sqlite.js";
 // Everything heavier loads per command: `huddle mail --hook` runs after every
 // one of Claude's tool calls and has to start in well under 300ms.
@@ -49,14 +55,26 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
     ${B("--approvals=safe|auto|yolo")} what agents may do unasked ${F("(default auto)")}
     ${B("--council")} ${F("/")} ${B("--no-council")}   design council first ${F("(default: big goals)")}
     ${B("--qa")} ${F("/")} ${B("--no-qa")}             agents re-check the build ${F("(default: big goals)")}
+    ${B("--budget=5M")}                tokens it may use ${F("(stops new work at 90%)")}
     ${B("--with <file>")}              put a file, folder or glob on the shared screen
                                ${F("(repeatable; or pipe: cat log | huddle join …)")}
+  ${B("huddle fix issue 12")}          GitHub issue 12 is the goal ${F("(also: fix #12)")}
+  ${B("huddle app")}                   the dashboard: live run, history, talk to agents
+    ${B("--phone")}                    on your phone too: scan the QR code it prints
+                               ${F("(--anywhere: off your Wi-Fi, needs cloudflared)")}
   ${B("huddle join <address> <CODE>")} join someone's room from an invite
 
   ${F("watch and replay")}
   ${B("huddle view")} ${F("[repo]")}           watch a run live, read-only, from a 2nd terminal
   ${B("huddle story")} ${F("[--html f]")}      replay the last run: ideas, contract, merges
                                ${F("(--list, --run n)")}
+  ${B("huddle brief")} ${F("[--run n]")}       what the last run left for your next solo agent
+                               ${F("(off / on: its pointer in CLAUDE.md, AGENTS.md)")}
+  ${B("huddle runs")}                  every run here: goal, agents, result, cost
+  ${B("huddle export")} ${F("[run]")}         a run as a chat you can read or share
+                               ${F("(--level summary|chat|full, --out <path>,")}
+                               ${F(" --format md|html|json, --no-redact)")}
+  ${B("huddle undo")} ${F("[--run n]")}        take back what a run merged ${F("(one revert commit)")}
   ${B("huddle board")}                 print the board
   ${B("huddle lessons")} ${F("[--forget id]")} what earlier runs taught your agents ${F("(--clear)")}
 
@@ -65,10 +83,12 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
   ${B("huddle doctor")}                check this machine: node, git, your agents
   ${B("huddle agents")}                your agents: ready or not, used or skipped
   ${B("huddle agents use|skip <ids>")} choose who works with you ${F("(e.g. skip cursor)")}
-  ${B("huddle agents --all")}          every connector Huddle knows, installed or not
+  ${B("huddle agents --all")}          every agent Huddle knows, installed or not
   ${B("huddle agents install <id>")}   install one ${F("(asks first)")}
+  ${B("huddle connectors")}            GitHub, Jira, Linear… for every agent
   ${B("huddle relay")} ${F("[--port 8080]")}   run a relay so rooms work across networks
   ${B("huddle --version")}             print the version
+  ${B("huddle update")}                get the newest Huddle from npm
 
   ${F("run claude, codex and cursor yourself — in one repo, safely")}
   ${B("huddle connect")}               wire your agents into this repo's live room
@@ -81,7 +101,8 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
   ${B("huddle up")} ${F("/")} ${B("down")} ${F("/")} ${B("disconnect")} start · stop the live room · unwire
 `;
 async function main() {
-    const [cmd, ...rest] = process.argv.slice(2);
+    const argv = process.argv.slice(2);
+    const [cmd, ...rest] = asGoal(argv) ?? argv;
     // Legacy Windows consoles get ASCII glyphs. Not for the machine-read channels: the Plug's JSON-RPC and Claude's hooks.
     if (!["plug", "guard", "mail"].includes(cmd ?? ""))
         useAsciiOutput();
@@ -167,8 +188,12 @@ async function main() {
             // --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 });
+            const budget = rest.find((a) => a.startsWith("--budget="))?.split("=")[1];
+            return runGoal(goal, { results, probed, mode: rest.includes("--plan") ? "plan" : "auto", approvals, council, qa, budget });
         }
+        case "app":
+        case "dashboard":
+            return (await import("./app/server.js")).runApp(rest);
         case "board":
             return (await app()).printBoard();
         case "view":
@@ -176,6 +201,12 @@ async function main() {
             return (await import("./ui/watch.js")).runView(rest);
         case "story":
             return (await import("./ui/story.js")).runStory(rest);
+        case "brief":
+            return (await import("./ui/brief.js")).runBrief(rest);
+        case "runs":
+            return (await import("./ui/export.js")).runRuns(rest);
+        case "export":
+            return (await import("./ui/export.js")).runExport(rest);
         case "lessons":
             return (await import("./ui/lessons.js")).runLessons(rest);
         case "up":
@@ -217,6 +248,17 @@ async function main() {
             console.log(`${C.violet("huddle relay")} listening on :${r.port} ${C.faint("· people use it with: relay ws://<this-host>:" + r.port)}`);
             return;
         }
+        case "undo":
+            return void (process.exitCode = await (await import("./ui/undo.js")).runUndo(rest));
+        case "connectors":
+        case "connector": {
+            const { repoRoot } = await app();
+            return void (process.exitCode = await (await import("./connectors/cli.js")).runConnectors(rest, repoRoot()));
+        }
+        case "update":
+        case "upgrade":
+        case "--update":
+            return void process.exit((await import("./update.js")).runUpdate());
         case "--version":
         case "-v":
         case "-V":

package/dist/connectors/cli.js

@@ -0,0 +1,121 @@
+// `huddle connectors`: which outside tools your agents get, and adding more.
+//
+//   huddle connectors                       what's on, with each one's tool count
+//   huddle connectors add atlassian         Jira + Confluence (signs in in your browser, once)
+//   huddle connectors add <name> <https-url>        any remote MCP server
+//   huddle connectors add <name> -- <command…>      any local MCP server
+//   huddle connectors add … --write         let agents use the tools that post or change things
+//   huddle connectors remove <name>
+//   huddle connectors github on|off|write|read
+import { C } from "../ui/term.js";
+import { configFile, PRESETS, presetName, readConfig, remoteCommand, startHub, statusLine, writeConfig } from "./hub.js";
+const USAGE = `${C.bold("huddle connectors")}                     what your agents can reach, and how many tools each gives
+${C.bold("huddle connectors add")} ${C.faint("<service>")}       a service your team uses:
+${Object.entries(PRESETS)
+    .map(([n, p]) => `    ${n.padEnd(34)}${C.faint(p.what)}`)
+    .join("\n")}
+${C.bold("huddle connectors add")} ${C.faint("<name> <url>")}    any remote MCP server (signs in through mcp-remote)
+${C.bold("huddle connectors add")} ${C.faint("<name> -- <cmd…>")} any local MCP server
+                                      ${C.faint("add --write to let agents use the tools that post or change things")}
+${C.bold("huddle connectors remove")} ${C.faint("<name>")}
+${C.bold("huddle connectors github")} ${C.faint("on|off|write|read")}
+                                      ${C.faint("GitHub (through the gh CLI) is on by default, read-only")}`;
+async function check(root, cfg, only) {
+    const one = only
+        ? only === "github"
+            ? { github: cfg.github }
+            : { github: { off: true }, connectors: { [only]: cfg.connectors[only] } }
+        : cfg;
+    if (only && only !== "github")
+        console.log(C.faint(`  connecting to ${only}… (the first time, it may open your browser to sign in)`));
+    const hub = startHub({ root, config: one, connectMs: 180_000 });
+    await hub.ready;
+    let ok = true;
+    for (const s of hub.status()) {
+        ok &&= s.ok;
+        console.log(`  ${s.ok ? C.green("✓") : C.red("✗")} ${statusLine(s)}`);
+    }
+    if (!hub.status().length)
+        console.log(C.faint("  (none on)"));
+    hub.close();
+    return ok;
+}
+export async function runConnectors(args, root) {
+    const [sub, ...rest] = args;
+    const cfg = readConfig();
+    cfg.connectors ??= {};
+    // --write is Huddle's flag only before `--`; after it, everything is the server's command.
+    const cut = rest.indexOf("--");
+    const own = cut < 0 ? rest : rest.slice(0, cut);
+    const write = own.includes("--write");
+    const words = [...own.filter((a) => a !== "--write"), ...(cut < 0 ? [] : rest.slice(cut))];
+    if (!sub || sub === "list" || sub === "status") {
+        console.log(C.bold("Connectors") + C.faint(` · every agent in a run gets these tools · ${configFile()}`));
+        await check(root, cfg);
+        console.log();
+        console.log(USAGE);
+        return 0;
+    }
+    if (sub === "help" || sub === "--help")
+        return void console.log(USAGE), 0;
+    if (sub === "github") {
+        const how = words[0];
+        if (!how)
+            return (await check(root, cfg, "github")) ? 0 : 1;
+        if (!["on", "off", "write", "read"].includes(how)) {
+            console.log(C.red("✗ ") + "huddle connectors github on|off|write|read");
+            return 1;
+        }
+        cfg.github = how === "off" ? { ...cfg.github, off: true } : { off: false, write: how === "write" ? true : how === "read" ? false : !!cfg.github?.write };
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} github ${how === "off" ? "off" : cfg.github.write ? "on — agents may comment and open issues, as you" : "on, read-only"}`);
+        return how === "off" ? 0 : (await check(root, cfg, "github")) ? 0 : 1;
+    }
+    if (sub === "add") {
+        const dash = words.indexOf("--");
+        const name = presetName(words[0] ?? "");
+        if (!/^[a-z][a-z0-9-]{0,30}$/.test(name) || name === "github") {
+            console.log(C.red("✗ ") + (name === "github" ? "GitHub is built in: huddle connectors github on" : "give it a short name (letters, digits, -): huddle connectors add jira"));
+            return 1;
+        }
+        let command;
+        if (dash >= 0)
+            command = words.slice(dash + 1);
+        else if (words[1] && /^https?:\/\//.test(words[1]))
+            command = remoteCommand(words[1]);
+        else if (PRESETS[name])
+            command = remoteCommand(PRESETS[name].url);
+        else {
+            console.log(C.red(`✗ no known service called "${name}".`) + ` Give its MCP URL (huddle connectors add ${name} https://…) or a command (huddle connectors add ${name} -- npx -y some-mcp-server).`);
+            return 1;
+        }
+        if (!command.length) {
+            console.log(C.red("✗ ") + "nothing after --");
+            return 1;
+        }
+        cfg.connectors[name] = { command, ...(write ? { write: true } : {}) };
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} added ${C.bold(name)}${PRESETS[name] ? C.faint(` (${PRESETS[name].what})`) : ""}: ${C.faint(command.join(" "))}`);
+        const ok = await check(root, cfg, name);
+        if (!ok)
+            console.log(C.faint(`  it stays saved; fix it and check with: huddle connectors · or: huddle connectors remove ${name}`));
+        else if (!write)
+            console.log(C.faint(`  read-only: agents see the tools that read. To let them post or change things: huddle connectors add --write ${words.join(" ")}`));
+        return ok ? 0 : 1;
+    }
+    if (sub === "remove" || sub === "rm") {
+        const name = presetName(words[0] ?? "");
+        if (!cfg.connectors[name]) {
+            console.log(C.red(`✗ no connector "${name}".`) + ` On: ${Object.keys(cfg.connectors).join(", ") || "(none added)"}`);
+            return 1;
+        }
+        delete cfg.connectors[name];
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} removed ${name}`);
+        return 0;
+    }
+    console.log(C.red(`✗ unknown: connectors ${sub}`));
+    console.log(USAGE);
+    return 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/connectors/github.js

@@ -0,0 +1,162 @@
+// The GitHub connector: issues, pull requests and CI for the repo you're in,
+// through the `gh` CLI you already signed in to. Huddle holds no GitHub token;
+// `gh` does, the same way each agent CLI holds its own login.
+//
+// Read tools are on whenever `gh` is signed in and the repo has a GitHub
+// remote. The two that write (a comment, a new issue) post as you, so they
+// show only after `huddle connectors github write`.
+import { spawnTool } from "../platform.js";
+const MAX_OUT = 60_000;
+/** Runs a command to completion, without blocking the Room's event loop. */
+export function runAsync(cmd, opts) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        let child;
+        try {
+            child = spawnTool(cmd, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, GH_PROMPT_DISABLED: "1", NO_COLOR: "1" } });
+        }
+        catch (e) {
+            return resolve({ code: 127, stdout: "", stderr: String(e?.message ?? e) });
+        }
+        const timer = setTimeout(() => {
+            child.kill();
+            finish({ code: 124, stdout, stderr: stderr + `\n(timed out after ${Math.round((opts.timeoutMs ?? 30_000) / 1000)}s)` });
+        }, opts.timeoutMs ?? 30_000);
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (e) => finish({ code: 127, stdout, stderr: String(e.message) }));
+        child.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
+        child.stdin.on("error", () => { }); // it may exit before reading it all
+        child.stdin.end(opts.input ?? "");
+    });
+}
+export const clipOut = (s, n = MAX_OUT) => (s.length > n ? s.slice(0, n) + `\n… (cut at ${n} characters)` : s);
+const num = (v) => {
+    const n = Number(String(v ?? "").replace(/^#/, ""));
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`not an issue or PR number: ${JSON.stringify(v)}`);
+    return String(n);
+};
+const limit = (v, def = 20) => String(Math.min(100, Math.max(1, Number(v) || def)));
+const state = (v) => (["open", "closed", "merged", "all"].includes(String(v)) ? String(v) : "open");
+/** One tool's result: gh's JSON (or text) when it worked, its error when not. */
+async function out(r) {
+    const x = await r;
+    if (x.code !== 0)
+        return { error: (x.stderr || x.stdout).trim().slice(0, 2000) || `gh exited ${x.code}` };
+    const t = x.stdout.trim();
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return clipOut(t);
+    }
+}
+export function githubTools(gh, opts) {
+    const tools = [
+        {
+            name: "github_issues",
+            description: "List this repo's GitHub issues (number, title, state, labels, author). Filter with state, label or a search query.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    state: { type: "string", enum: ["open", "closed", "all"] },
+                    label: { type: "string" },
+                    search: { type: "string", description: "GitHub search syntax, e.g. 'login in:title'" },
+                    limit: { type: "number" },
+                },
+            },
+            call: (a) => out(gh([
+                "issue", "list", "--state", state(a.state), "--limit", limit(a.limit),
+                ...(a.label ? ["--label", String(a.label)] : []),
+                ...(a.search ? ["--search", String(a.search)] : []),
+                "--json", "number,title,state,labels,author,updatedAt",
+            ])),
+        },
+        {
+            name: "github_issue",
+            description: "Read one GitHub issue in full: its body, labels and every comment.",
+            inputSchema: { type: "object", properties: { number: { type: "number" } }, required: ["number"] },
+            call: (a) => out(gh(["issue", "view", num(a.number), "--json", "number,title,body,state,labels,author,comments,url"])),
+        },
+        {
+            name: "github_prs",
+            description: "List this repo's pull requests (number, title, branch, author, state).",
+            inputSchema: { type: "object", properties: { state: { type: "string", enum: ["open", "closed", "merged", "all"] }, limit: { type: "number" } } },
+            call: (a) => out(gh(["pr", "list", "--state", state(a.state), "--limit", limit(a.limit), "--json", "number,title,state,headRefName,author,url"])),
+        },
+        {
+            name: "github_pr",
+            description: "Read one pull request: description, changed files, comments and reviews. Pass diff: true for the diff too (cut at 60k characters).",
+            inputSchema: { type: "object", properties: { number: { type: "number" }, diff: { type: "boolean" } }, required: ["number"] },
+            call: async (a) => {
+                const n = num(a.number);
+                const view = await out(gh(["pr", "view", n, "--json", "number,title,body,state,headRefName,baseRefName,files,comments,reviews,url"]));
+                if (!a.diff)
+                    return view;
+                const d = await gh(["pr", "diff", n]);
+                return { pr: view, diff: d.code === 0 ? clipOut(d.stdout) : `(no diff: ${d.stderr.trim().slice(0, 300)})` };
+            },
+        },
+        {
+            name: "github_ci",
+            description: "The latest GitHub Actions runs (workflow, branch, status, conclusion), so you can see whether CI is green or what broke.",
+            inputSchema: { type: "object", properties: { branch: { type: "string" }, limit: { type: "number" } } },
+            call: (a) => out(gh(["run", "list", "--limit", limit(a.limit, 8), ...(a.branch ? ["--branch", String(a.branch)] : []), "--json", "databaseId,workflowName,headBranch,status,conclusion,createdAt,url"])),
+        },
+    ];
+    const writes = !opts.write ? [] : [
+        {
+            name: "github_comment",
+            description: "Post a comment on a GitHub issue or pull request, as the person running Huddle. Use it for what they'd want posted (a fix summary, a question), not chatter.",
+            inputSchema: { type: "object", properties: { number: { type: "number" }, body: { type: "string" } }, required: ["number", "body"] },
+            write: true,
+            call: (a, agent) => out(gh(["issue", "comment", num(a.number), "--body-file", "-"], `${String(a.body ?? "").trim()}\n\n${opts.signature(agent)}`)),
+        },
+        {
+            name: "github_new_issue",
+            description: "Open a new GitHub issue, as the person running Huddle: for a real bug or follow-up found while working that this run won't fix.",
+            inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" } }, required: ["title", "body"] },
+            write: true,
+            call: (a, agent) => out(gh(["issue", "create", "--title", String(a.title ?? "").slice(0, 250), "--body-file", "-"], `${String(a.body ?? "").trim()}\n\n${opts.signature(agent)}`)),
+        },
+    ];
+    // A bad argument rejects (never throws mid-call), like every other tool.
+    return [...tools, ...writes].map((t) => ({ ...t, call: async (a, agent) => t.call(a, agent) }));
+}
+/** "#12", "issue 12", "fix #12", "github issue #12": the issue number, else null. */
+export function issueRef(goal) {
+    const m = /^\s*(?:(?:fix|close|solve|do|work on|build)\s+)?(?:(?:github|gh)\s+)?(?:issue\s*)?#(\d+)\s*$/i.exec(goal) ?? /^\s*(?:(?:fix|close|solve)\s+)?(?:github\s+)?issue\s+(\d+)\s*$/i.exec(goal);
+    return m ? Number(m[1]) : null;
+}
+/** The goal a run gets for a GitHub issue: its title, body and comments, verbatim. */
+export function issueGoal(issue) {
+    const comments = (issue.comments ?? [])
+        .slice(-8)
+        .map((c) => `- ${c.author?.login ?? "someone"}: ${String(c.body ?? "").trim().slice(0, 800)}`)
+        .join("\n");
+    return [
+        `Resolve GitHub issue #${issue.number}: ${issue.title}`,
+        issue.url ? `(${issue.url})` : "",
+        "",
+        String(issue.body ?? "").trim().slice(0, 6000) || "(the issue has no description)",
+        comments ? `\nComments on the issue:\n${comments}` : "",
+    ]
+        .filter((l, i) => l || i === 2)
+        .join("\n")
+        .trim();
+}
+/** Issues a longer goal mentions ("fix #12 and add a test"): up to 3 numbers. */
+export function issueMentions(goal) {
+    return [...new Set([...goal.matchAll(/(?:^|[\s(])#(\d{1,6})\b/g)].map((m) => Number(m[1])))].slice(0, 3);
+}
+//# sourceMappingURL=github.js.map

package/dist/connectors/hub.js

@@ -0,0 +1,234 @@
+// Connectors: the outside tools a team works with — GitHub, Jira, Confluence,
+// Linear, Notion, Miro… — given once to every agent in a run, whichever CLI it is.
+//
+// The Room runs them, not each agent: one process per connector per run, one
+// sign-in, and every call goes through the Plug (huddle plug), so Claude,
+// Codex, Cursor and the rest see the same tools without 14 vendor configs.
+//
+//   ~/.huddle/connectors.json   yours, on this machine (HUDDLE_HOME moves it)
+//   {
+//     "github": { "off": false, "write": false },
+//     "connectors": {
+//       "atlassian": { "command": ["npx", "-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"] },
+//       "mine":      { "command": ["node", "/path/server.js"], "write": true, "env": { "X": "1" } }
+//     }
+//   }
+//
+// Any MCP server over stdio is a connector. Remote ones (an https URL) run
+// through mcp-remote, which does the service's OAuth itself and keeps the
+// token: Huddle holds none. Until you allow writes (`write: true`), agents
+// see only the tools that read.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { githubTools, runAsync } from "./github.js";
+/** Known services: `huddle connectors add atlassian`. Each is its vendor's own remote MCP server. */
+export const PRESETS = {
+    atlassian: { url: "https://mcp.atlassian.com/v1/mcp", what: "Jira and Confluence" },
+    linear: { url: "https://mcp.linear.app/mcp", what: "Linear issues and projects" },
+    notion: { url: "https://mcp.notion.com/mcp", what: "Notion pages and databases" },
+    miro: { url: "https://mcp.miro.com/", what: "Miro boards" },
+    sentry: { url: "https://mcp.sentry.dev/mcp", what: "Sentry errors" },
+};
+const ALIASES = { jira: "atlassian", confluence: "atlassian" };
+export const presetName = (n) => ALIASES[n.toLowerCase()] ?? n.toLowerCase();
+export const remoteCommand = (url) => ["npx", "-y", "mcp-remote", url];
+const home = () => process.env.HUDDLE_HOME ?? path.join(os.homedir(), ".huddle");
+export const configFile = () => path.join(home(), "connectors.json");
+export function readConfig() {
+    try {
+        const c = JSON.parse(fs.readFileSync(configFile(), "utf8"));
+        return c && typeof c === "object" ? c : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(c) {
+    fs.mkdirSync(path.dirname(configFile()), { recursive: true });
+    fs.writeFileSync(configFile(), JSON.stringify(c, null, 2) + "\n");
+}
+/** A connector's tool names start with its name: [a-z0-9_-], at most 64 characters (what every CLI accepts). */
+export const toolName = (connector, tool) => `${connector}_${tool}`.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+const READ_VERB = /^(get|list|search|read|fetch|view|find|query|lookup|describe|show|retrieve|count|whoami|atlassianUserInfo|getAccessible)/i;
+/**
+ * Whether a tool only reads. The server's own annotations decide when it
+ * gives them; otherwise its name does (getJiraIssue, search_issues, list_…).
+ */
+export function readsOnly(t) {
+    if (t.annotations?.readOnlyHint === true)
+        return true;
+    if (t.annotations?.readOnlyHint === false || t.annotations?.destructiveHint === true)
+        return false;
+    return READ_VERB.test(t.name.replace(/^[a-z]+_/, "")) || READ_VERB.test(t.name);
+}
+const MAX_RESULT = 60_000;
+/** An MCP tool result as plain text an agent can read (images and the like become a note). */
+function flatten(r) {
+    const parts = Array.isArray(r?.content) ? r.content : [];
+    const text = parts
+        .map((p) => (p?.type === "text" ? String(p.text ?? "") : p?.type === "resource" ? String(p.resource?.text ?? p.resource?.uri ?? "") : `(${p?.type ?? "item"} not shown)`))
+        .join("\n");
+    const out = text.length > MAX_RESULT ? text.slice(0, MAX_RESULT) + `\n… (cut at ${MAX_RESULT} characters)` : text;
+    return r?.isError ? { error: out || "the connector reported an error" } : out || r?.structuredContent || "(empty result)";
+}
+function withTimeout(p, ms, what) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`${what}: no answer in ${Math.round(ms / 1000)}s`)), ms);
+        p.then((v) => (clearTimeout(t), resolve(v)), (e) => (clearTimeout(t), reject(e)));
+    });
+}
+export async function githubReady(root) {
+    const r = await runAsync(["gh", "repo", "view", "--json", "nameWithOwner"], { cwd: root, timeoutMs: 15_000 });
+    if (r.code === 127)
+        return { ok: false, note: "the GitHub CLI isn't installed (https://cli.github.com)" };
+    if (r.code !== 0) {
+        const e = (r.stderr || r.stdout).toLowerCase();
+        if (/auth|log ?in|token/.test(e))
+            return { ok: false, note: "gh isn't signed in: gh auth login" };
+        if (/no git remote|not a git|none of the git remotes|could not determine/.test(e))
+            return { ok: false, note: "this repo has no GitHub remote" };
+        return { ok: false, note: (r.stderr || r.stdout).trim().split("\n")[0].slice(0, 160) || "gh failed" };
+    }
+    try {
+        return { ok: true, note: JSON.parse(r.stdout).nameWithOwner };
+    }
+    catch {
+        return { ok: true, note: "" };
+    }
+}
+/** Starts this machine's connectors for a run in `root`. Never throws: a connector that fails is left out, with a note. */
+export function startHub(opts) {
+    const cfg = opts.config ?? readConfig();
+    const tools = [];
+    const statuses = [];
+    const open = [];
+    let closed = false;
+    const sig = opts.signature ?? ((agent) => `<sub>— ${agent}, via Huddle</sub>`);
+    const github = async () => {
+        if (cfg.github?.off)
+            return;
+        const g = await (opts.githubReady ?? (() => githubReady(opts.root)))();
+        if (!g.ok)
+            return void statuses.push({ name: "github", ok: false, tools: 0, hidden: 0, note: g.note });
+        const gh = (args, input) => runAsync(["gh", ...args], { cwd: opts.root, input, timeoutMs: 45_000 });
+        const all = githubTools(gh, { write: true, signature: sig });
+        const mine = githubTools(gh, { write: !!cfg.github?.write, signature: sig });
+        tools.push(...mine);
+        statuses.push({ name: "github", ok: true, tools: mine.length, hidden: all.length - mine.length, note: g.note });
+    };
+    const mcp = async (name, c) => {
+        if (c.off)
+            return;
+        if (!Array.isArray(c.command) || !c.command.length)
+            return void statuses.push({ name, ok: false, tools: 0, hidden: 0, note: "no command" });
+        const transport = new StdioClientTransport({
+            command: c.command[0],
+            args: c.command.slice(1),
+            env: { ...process.env, ...(c.env ?? {}) },
+            cwd: opts.root,
+            stderr: "pipe",
+        });
+        const client = new Client({ name: "huddle", version: "1" });
+        try {
+            await withTimeout(client.connect(transport), opts.connectMs ?? 60_000, name);
+            const listed = await withTimeout(client.listTools(), opts.connectMs ?? 60_000, name);
+            if (closed)
+                return void client.close().catch(() => { });
+            open.push({ name, client, transport });
+            let hidden = 0;
+            for (const t of listed.tools) {
+                const write = !readsOnly(t);
+                if (write && !c.write) {
+                    hidden++;
+                    continue;
+                }
+                tools.push({
+                    name: toolName(name, t.name),
+                    description: `[${name}] ${t.description ?? t.name}`.slice(0, 1500),
+                    inputSchema: t.inputSchema ?? { type: "object", properties: {} },
+                    write,
+                    call: async (args) => flatten(await client.callTool({ name: t.name, arguments: args }, undefined, { timeout: 120_000 })),
+                });
+            }
+            statuses.push({ name, ok: true, tools: listed.tools.length - hidden, hidden, note: "" });
+        }
+        catch (e) {
+            client.close().catch(() => { });
+            statuses.push({ name, ok: false, tools: 0, hidden: 0, note: String(e?.message ?? e).split("\n")[0].slice(0, 200) });
+        }
+    };
+    const ready = Promise.all([github(), ...Object.entries(cfg.connectors ?? {}).map(([n, c]) => mcp(n, c))]).then(() => {
+        // Same name twice (two connectors exposing one tool): the first one wins.
+        const seen = new Set();
+        for (let i = 0; i < tools.length; i++) {
+            if (seen.has(tools[i].name))
+                tools.splice(i--, 1);
+            else
+                seen.add(tools[i].name);
+        }
+    });
+    return {
+        ready,
+        tools: () => tools,
+        status: () => statuses,
+        async call(name, args, agent) {
+            const t = tools.find((x) => x.name === name);
+            if (!t)
+                return { error: `no connector tool "${name}"` };
+            try {
+                return await t.call(args ?? {}, agent);
+            }
+            catch (e) {
+                return { error: String(e?.message ?? e) };
+            }
+        },
+        close() {
+            closed = true;
+            for (const o of open.splice(0))
+                o.client.close().catch(() => { });
+        },
+    };
+}
+/** One line per connector, for the run's opening and `huddle connectors`. */
+export function statusLine(s) {
+    if (!s.ok)
+        return `${s.name}: off — ${s.note}`;
+    return `${s.name}: ${s.tools} tool(s)${s.note ? ` · ${s.note}` : ""}${s.hidden ? ` · ${s.hidden} that write hidden` : ""}`;
+}
+const PHRASES = {
+    github_issues: (a) => `listed ${a.state && a.state !== "open" ? a.state + " " : ""}issues${a.search ? ` matching "${a.search}"` : ""}${a.label ? ` labelled ${a.label}` : ""}`,
+    github_issue: (a) => `read issue #${a.number}`,
+    github_prs: () => "listed pull requests",
+    github_pr: (a) => `read PR #${a.number}${a.diff ? " and its diff" : ""}`,
+    github_ci: (a) => `checked CI${a.branch ? ` on ${a.branch}` : ""}`,
+    github_comment: (a) => `commented on #${a.number}`,
+    github_new_issue: (a) => `opened an issue: ${String(a.title ?? "").slice(0, 80)}`,
+};
+/** A connector call in words, for the live run: { head: "github:", body: "read issue #12" }. */
+export function connectorLine(p) {
+    const tool = String(p.tool ?? "");
+    const [conn, ...rest] = tool.split("_");
+    const phrase = PHRASES[tool]?.(p.args ?? {}) ?? rest.join("_").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+    return { head: `${conn}:`, body: phrase + (p.ok === false ? " (failed)" : "") };
+}
+/**
+ * For the planner and the council, who plan without tools: what the agents
+ * will be able to read while they work, so a goal naming a ticket gets tasks
+ * that read it first instead of guessing what it says.
+ */
+export function toolsNote(hub) {
+    const by = new Map();
+    for (const t of hub.tools()) {
+        const conn = t.name.split("_")[0];
+        by.set(conn, [...(by.get(conn) ?? []), t.name]);
+    }
+    if (!by.size)
+        return "";
+    return `OUTSIDE TOOLS: every agent can call these while it works (you can't, in this step):
+${[...by].map(([c, names]) => `- ${c}: ${names.join(", ")}`).join("\n")}
+When the goal names something only these tools can show (a ticket, issue, PR, page, board), don't guess what it says: the spec of every task that needs it says to read it first, naming the tool and the item (e.g. "read WEB-7 with jira_getJiraIssue").`;
+}
+//# sourceMappingURL=hub.js.map

package/dist/connectors/types.js

@@ -0,0 +1,3 @@
+// What a connector gives agents: tools, each one callable through the Plug.
+export {};
+//# sourceMappingURL=types.js.map