huddle-cli 0.0.0-stage → 0.1.1

package/dist/attach/session.js

@@ -0,0 +1,177 @@
+// Attach mode, isolation: `huddle attach <agent>` opens the agent's normal
+// interactive CLI in its OWN worktree branch (huddle/<agent>-live-N), already
+// connected to the live room. Two sessions can then never overwrite each
+// other's files mid-edit; `huddle land` brings a session's branch home through
+// the merge engine (commit → tests → rebase → fast-forward), after you say so.
+//
+// Plus `huddle up` / `huddle down` / `huddle peers`, the human's view of the room
+// (`huddle add` / `huddle ctx`, its shared screen, are in screen.ts).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { getAdapter } from "../adapters/index.js";
+import { spawnToolSync } from "../platform.js";
+import { createWorktree, landMerge, prepareMerge, removeWorktree } from "../sandbox/worktree.js";
+import { C, dot } from "../ui/term.js";
+import { detectTestCmd } from "../ui/app.js";
+import { applyConnect, confirm, disconnect, livePlug, planConnect } from "./connect.js";
+import { ensureLive, liveCall, liveFiles, mainRoot, readLive, serveLive, stopLive, pingLive, checkoutRoot } from "./live.js";
+const attachFile = (repo) => path.join(liveFiles(repo).dir, "attach.json");
+export function readAttached(repo) {
+    try {
+        return JSON.parse(fs.readFileSync(attachFile(repo), "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+function writeAttached(repo, list) {
+    fs.mkdirSync(path.dirname(attachFile(repo)), { recursive: true });
+    fs.writeFileSync(attachFile(repo), JSON.stringify(list, null, 2));
+}
+function needRepo() {
+    const root = mainRoot();
+    if (!root) {
+        console.log(C.red("✗ Not a git repo.") + " Run this inside the repo your agents work in.");
+        process.exit(1);
+    }
+    return root;
+}
+/**
+ * Make a session worktree for `agent`, wired to the live room. Returns the
+ * worktree and the interactive command to run in it.
+ */
+export function prepareAttach(repo, agentId) {
+    const adapter = getAdapter(agentId);
+    if (!adapter)
+        throw new Error(`unknown agent "${agentId}"`);
+    const taken = new Set(readAttached(repo).map((e) => e.branch));
+    let n = 1;
+    while (taken.has(`huddle/${agentId}-live-${n}`) || fs.existsSync(path.join(repo, ".huddle", "worktrees", `${agentId}-live-${n}`)))
+        n++;
+    const wt = createWorktree(repo, agentId, `live-${n}`);
+    // The same project files `huddle connect` writes, inside the session's own worktree.
+    const plan = planConnect(wt.path, { agents: [agentId], repo, adapters: [adapter] });
+    applyConnect(wt.path, plan, repo);
+    const excludes = plan.filter((w) => w.action !== "skip").map((w) => w.file);
+    const cmd = [adapter.bin];
+    if (adapter.id === "codex") {
+        // A new worktree isn't a trusted project yet, and Codex ignores .codex/ in
+        // untrusted ones — so hand the Plug over with -c too (verified: `codex --help`).
+        const plug = livePlug(repo, "codex");
+        const env = `{${Object.entries(plug.env).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(",")}}`;
+        cmd.push("-c", `mcp_servers.huddle.command=${JSON.stringify(plug.command)}`, "-c", `mcp_servers.huddle.args=${JSON.stringify(plug.args)}`, "-c", `mcp_servers.huddle.env=${env}`);
+    }
+    writeAttached(repo, [...readAttached(repo), { agent: agentId, branch: wt.branch, path: wt.path, excludes, started_at: Date.now() }]);
+    return { wt, cmd, excludes };
+}
+export async function runAttach(args) {
+    const repo = needRepo();
+    const agentId = args.find((a) => !a.startsWith("-"));
+    if (!agentId) {
+        console.log(C.red("✗ Which agent?") + " huddle attach claude   (or codex, cursor, …)");
+        process.exit(1);
+    }
+    const passthrough = args.includes("--") ? args.slice(args.indexOf("--") + 1) : [];
+    const dirty = spawnSync("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: repo, encoding: "utf8" }).stdout.trim();
+    if (dirty)
+        console.log(C.yellow("! You have uncommitted changes in the main checkout — the session starts from the last commit, without them."));
+    const { state } = await ensureLive(repo);
+    const { wt, cmd } = prepareAttach(repo, agentId);
+    console.log(`${dot(agentId)} ${C.bold(agentId)} in its own worktree ${C.faint(path.relative(repo, wt.path))} on ${C.bold(wt.branch)}`);
+    console.log(C.faint(`  live room ${state.url} · the others see it in huddle_peers · when it's done: huddle land ${wt.branch}\n`));
+    const r = spawnToolSync([...cmd, ...passthrough], { cwd: wt.path, stdio: "inherit" });
+    if (r.error)
+        console.log(C.red(`✗ couldn't start ${cmd[0]}: ${r.error.message}`));
+    const changed = spawnSync("git", ["status", "--porcelain"], { cwd: wt.path, encoding: "utf8" }).stdout.trim();
+    const ahead = spawnSync("git", ["rev-list", "--count", `HEAD..${wt.branch}`], { cwd: repo, encoding: "utf8" }).stdout.trim();
+    console.log(`\n${agentId} session ended. ${changed || (ahead && ahead !== "0") ? `Its work is on ${C.bold(wt.branch)} — ${C.bold(`huddle land ${wt.branch}`)} tests it and merges it.` : "No changes."}`);
+}
+/** `huddle land [branch|agent]`: the merge engine for one attach session. */
+export async function landSession(repo, e, opts = {}) {
+    const wt = { branch: e.branch, path: e.path };
+    const testCmd = opts.testCmd !== undefined ? opts.testCmd : detectTestCmd(e.path);
+    const prep = prepareMerge(repo, wt, testCmd, e.excludes, `huddle: ${e.agent} session (${e.branch})`);
+    // Attach mode has no scheduler to hand a conflict to a resolver agent: the
+    // session's own agent (or you) merges main in, then lands again.
+    if (prep.conflict)
+        return { merged: false, reason: `main changed the same lines — in ${e.path} run \`git merge main\`, resolve, then \`huddle land\` again` };
+    if (!prep.ok)
+        return { merged: false, reason: prep.reason };
+    if (!prep.diffstat.trim())
+        return { merged: false, reason: "nothing to land — the branch matches main" };
+    if (!opts.yes) {
+        console.log(prep.diffstat + "\n" + C.faint(prep.reason));
+        if (!(await confirm(`Merge ${e.branch} into your current branch?`)))
+            return { merged: false, reason: "not now", diffstat: prep.diffstat };
+    }
+    const land = landMerge(repo, wt);
+    if (land.merged && !opts.keep) {
+        disconnect(e.path, repo);
+        removeWorktree(repo, e.path);
+        spawnSync("git", ["branch", "-d", e.branch], { cwd: repo, stdio: "ignore" });
+        writeAttached(repo, readAttached(repo).filter((x) => x.branch !== e.branch));
+    }
+    return { merged: land.merged, reason: land.reason, diffstat: prep.diffstat };
+}
+export async function runLand(args) {
+    const repo = needRepo();
+    const list = readAttached(repo);
+    const want = args.find((a) => !a.startsWith("-"));
+    const here = checkoutRoot();
+    const pick = want
+        ? list.filter((e) => e.branch === want || e.agent === want || path.basename(e.path) === want)
+        : list.filter((e) => e.path === here).length
+            ? list.filter((e) => e.path === here)
+            : list;
+    if (!pick.length)
+        return void console.log(want ? C.red(`✗ no attach session "${want}"`) : "No attach sessions. Start one with huddle attach <agent>.");
+    if (pick.length > 1) {
+        console.log("Which one?\n" + pick.map((e) => `  huddle land ${e.branch}   ${C.faint(e.agent)}`).join("\n"));
+        return;
+    }
+    const r = await landSession(repo, pick[0], { yes: args.includes("--yes") || args.includes("-y"), keep: args.includes("--keep") });
+    console.log(r.merged ? `${C.green("✓")} landed ${pick[0].branch}` : `${C.yellow("·")} not landed: ${r.reason}`);
+    if (!r.merged)
+        process.exitCode = 1;
+}
+// ---- up / down / peers ---------------------------------------------------------
+export async function runUp(args) {
+    if (args.includes("--serve"))
+        return serveLive(process.env.HUDDLE_LIVE_ROOT || needRepo());
+    const repo = needRepo();
+    const { state, started } = await ensureLive(repo);
+    console.log(`${C.green("✓")} live room ${started ? "started" : "already running"} for ${C.bold(path.basename(repo))} ${C.faint(`(${state.url}, pid ${state.pid})`)}`);
+    const connected = fs.existsSync(path.join(liveFiles(repo).dir, "connect.json"));
+    if (!connected)
+        console.log(`  next: ${C.bold("huddle connect")} so your claude / codex / cursor sessions join it`);
+    console.log(C.faint("  huddle peers — who's in · huddle down — stop it"));
+}
+export async function runDown() {
+    const repo = needRepo();
+    console.log((await stopLive(repo)) ? `${C.green("✓")} live room stopped` : "No live room running for this repo.");
+}
+export async function runPeers() {
+    const repo = needRepo();
+    const st = readLive(repo);
+    if (!st || !(await pingLive(st)))
+        return void console.log(`No live room. ${C.bold("huddle up")} starts one.`);
+    // Anonymous: a person looking in isn't a session.
+    const r = await liveCall(st, "peers", {}, "");
+    const sessions = (r.body.sessions ?? []).filter((s) => !s.you);
+    console.log(`${C.violet("huddle")} live room · ${path.basename(repo)} · ${sessions.length} session${sessions.length === 1 ? "" : "s"}\n`);
+    for (const s of sessions) {
+        console.log(`  ${dot(s.agent)} ${C.bold(s.id.padEnd(12))} ${s.doing}`);
+        console.log(C.faint(`      ${s.branch || "?"} · ${s.worktree} · holds ${s.holds.length ? s.holds.join(", ") : "nothing"} · seen ${s.seen_s_ago}s ago`));
+    }
+    const sc = r.body.screen;
+    if (sc?.items)
+        console.log(`\n  ${C.bold("screen")} ${sc.items} item${sc.items === 1 ? "" : "s"}${sc.latest_note ? ` · latest note: ${sc.latest_note}` : ""} ${C.faint("· huddle ctx")}`);
+    const notes = r.body.notes ?? [];
+    if (notes.length) {
+        console.log(`\n  ${C.bold("notes")}`);
+        for (const n of notes)
+            console.log(`  ${C.faint(`${n.ago} ago`.padStart(8))} ${n.from}${n.from_live ? "" : C.faint(" (gone)")} → ${n.to}: ${n.body}`);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/cli.js

@@ -0,0 +1,244 @@
+#!/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)
+//     --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 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 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
+//   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 add <file|dir|glob|->  put it on the live room's shared screen (- = stdin)
+//   huddle ctx [show|rm|note|clear]  what's on that screen; take things off, pin notes
+//   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
+//   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 { 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.
+const app = () => import("./ui/app.js");
+const B = C.bold;
+const F = C.faint;
+// Every line fits 80 columns.
+const USAGE = `${C.violet("huddle")} — your agents, in the same room
+
+  ${B("huddle")}                       open Huddle
+  ${B('huddle join "<goal>"')}         plan the goal and run your agents
+    ${B("--plan")}                     dry run: show who'd do what
+    ${B("--agents=claude,codex")}      only these agents work on this run
+    ${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("--with <file>")}              put a file, folder or glob on the shared screen
+                               ${F("(repeatable; or pipe: cat log | huddle join …)")}
+  ${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 board")}                 print the board
+  ${B("huddle lessons")} ${F("[--forget id]")} what earlier runs taught your agents ${F("(--clear)")}
+
+  ${F("your agents")}
+  ${B("huddle setup")}                 install + sign in to your agents ${F("(--yes)")}
+  ${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 install <id>")}   install one ${F("(asks first)")}
+  ${B("huddle relay")} ${F("[--port 8080]")}   run a relay so rooms work across networks
+  ${B("huddle --version")}             print the version
+
+  ${F("run claude, codex and cursor yourself — in one repo, safely")}
+  ${B("huddle connect")}               wire your agents into this repo's live room
+  ${B("huddle peers")}                 who's live, what they're on, their files
+  ${B("huddle add <file|->")}          put a file, folder, glob or stdin on the screen
+                               ${F("(cat err.log | huddle add -)")}
+  ${B("huddle ctx")} ${F("[show|rm|note|clear]")} what's on the screen every session reads
+  ${B("huddle attach <agent>")}        open an agent in its own worktree branch
+  ${B("huddle land")} ${F("[branch]")}         test + merge that session's work
+  ${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);
+    // 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();
+    switch (cmd) {
+        case undefined:
+            if (!process.stdin.isTTY)
+                return void console.log(USAGE);
+            return (await app()).runApp();
+        case "plug":
+            return (await import("./mcp/server.js")).runPlug();
+        case "init": {
+            const { ensureInit, huddleDir } = await app();
+            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 "setup":
+            process.exitCode = await (await import("./ui/setup.js")).runSetup(rest);
+            return;
+        case "agents": {
+            const { chooseAgents, installConnector, printAgents, printCatalog } = await import("./ui/catalog.js");
+            if (rest[0] === "install" && rest[1])
+                return void (await installConnector(rest[1]));
+            if ((rest[0] === "use" || rest[0] === "skip") && rest.length > 1)
+                return void (process.exitCode = chooseAgents(rest[0], rest.slice(1)) ? 0 : 1);
+            if (rest.includes("--all"))
+                return printCatalog();
+            if (!rest.length)
+                return printAgents();
+            process.exitCode = await (await import("./ui/doctor.js")).runDoctor();
+            return;
+        }
+        case "doctor":
+            process.exitCode = await (await import("./ui/doctor.js")).runDoctor();
+            return;
+        case "join": {
+            // `huddle join <address> <CODE>` joins someone's room; anything else is a goal.
+            const { INVITE_CODE, joinRoom } = await import("./ui/remote.js");
+            if (rest.length === 2 && INVITE_CODE.test(rest[1]))
+                return joinRoom(rest[0], rest[1]);
+            const { connectAgents, dbPath, ensureInit, runGoal } = await app();
+            const { addForRun, readPipedStdin, takeWith } = await import("./ui/paste.js");
+            const withs = takeWith(rest);
+            const goal = withs.rest.filter((a) => !a.startsWith("--")).join(" ");
+            if (!goal) {
+                console.log(C.red("✗ Give a goal:") + ' huddle join "build the login page"');
+                process.exit(1);
+            }
+            // The shared screen first (--with files, piped stdin), so the planner sees its index.
+            const piped = await readPipedStdin();
+            if (withs.files.length || piped.trim()) {
+                if (!ensureInit()) {
+                    console.log(C.red("✗ Not a git repo.") + " The shared screen lives in a repo's .huddle/ — run `git init` first.");
+                    process.exit(1);
+                }
+                if (await addForRun(dbPath(), withs.files, piped, (l = "") => console.log(l))) {
+                    console.log(C.red("✗ couldn't put everything on the shared screen (above) — nothing was run."));
+                    process.exit(1);
+                }
+            }
+            const flag = rest.find((a) => a.startsWith("--approvals="))?.split("=")[1];
+            const approvals = (["safe", "auto", "yolo"].includes(flag ?? "") ? flag : "auto");
+            let probed = await connectAgents();
+            let results = probed;
+            // --agents=claude,codex: run with just these (the rest sit this one out) — even ones you skipped.
+            const pick = rest.find((a) => a.startsWith("--agents="))?.split("=")[1];
+            if (pick !== undefined) {
+                const ids = pick.split(",").map((s) => s.trim()).filter(Boolean);
+                results = probed = (await import("./adapters/index.js")).unskip(probed, ids);
+                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 (await app()).printBoard();
+        case "view":
+        case "watch":
+            return (await import("./ui/watch.js")).runView(rest);
+        case "story":
+            return (await import("./ui/story.js")).runStory(rest);
+        case "lessons":
+            return (await import("./ui/lessons.js")).runLessons(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 "add":
+            return (await import("./attach/screen.js")).runAdd(rest);
+        case "ctx":
+        case "context":
+            return (await import("./attach/screen.js")).runCtx(rest);
+        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 "mail":
+            if (rest.includes("--hook"))
+                return (await import("./room/mail.js")).runMailHook(rest);
+            console.log(C.red("✗ huddle mail is internal:") + " agents read mail through the Plug (huddle_inbox).");
+            process.exit(1);
+        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 { startRelay } = await import("./relay/server.js");
+            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/context-tools.js

@@ -0,0 +1,79 @@
+// The Plug's shared-screen verbs (src/room/context.ts is the Room side).
+// Kept out of server.ts so the screen is one file to read.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function contextTools(room) {
+    return [
+        {
+            name: "huddle_context",
+            description: "The SHARED SCREEN: everything the user pasted, dropped or uploaded for the whole team (logs, docs, code, screenshots, PDFs) — one copy in the Room, not in your prompt. Lists each item's id, kind, title, size, summary, sections and the notes pinned on it.",
+            inputSchema: { type: "object", properties: {} },
+            handler: () => room("/context", "GET"),
+        },
+        {
+            name: "huddle_context_read",
+            description: "Read one item from the shared screen. Text comes back in chunks of up to 400 lines: pass from_line/to_line, or section (a number or title from huddle_context). Images and PDFs come back as a file path — open it with your image/file reading tool.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "the item id, e.g. ctx-3" },
+                    from_line: { type: "number" },
+                    to_line: { type: "number" },
+                    section: { type: "string", description: "optional: a section number or title" },
+                },
+                required: ["id"],
+            },
+            handler: (a) => room("/context_read", "POST", { id: a.id, from_line: a.from_line, to_line: a.to_line, section: a.section }),
+        },
+        {
+            name: "huddle_context_search",
+            description: "Search every text item on the shared screen. Returns matching lines with the item id and line number, so you can huddle_context_read around them.",
+            inputSchema: {
+                type: "object",
+                properties: { query: { type: "string" }, regex: { type: "boolean", description: "treat query as a regular expression" } },
+                required: ["query"],
+            },
+            handler: (a) => room("/context_search", "POST", { query: a.query, regex: !!a.regex }),
+        },
+        {
+            name: "huddle_context_note",
+            description: "Pin a short comment on a shared-screen item — what it means, what you found in it, which part you're handling. Every agent and the user sees it next to the item. This is how the team talks about the same document.",
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" }, note: { type: "string" } },
+                required: ["id", "note"],
+            },
+            handler: (a) => room("/context_note", "POST", { id: a.id, note: a.note }),
+        },
+    ];
+}
+/**
+ * A Room result as MCP content. Screenshots also go as an image block (hosts
+ * that render MCP images show it to the model directly). Bytes sent across
+ * machines (a teammate's agent) are saved here and replaced by a local path.
+ */
+export function toContent(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+    const { image, file, ...rest } = result;
+    if (file?.data_base64 && file?.name) {
+        try {
+            const dir = path.join(os.tmpdir(), "huddle-context");
+            fs.mkdirSync(dir, { recursive: true });
+            const p = path.join(dir, String(file.name).replace(/[^\w.-]/g, "_"));
+            fs.writeFileSync(p, Buffer.from(String(file.data_base64), "base64"));
+            rest.path = p;
+            rest.note = `Open this file with your image/file reading tool (e.g. Read ${p}).`;
+        }
+        catch (e) {
+            rest.note = `couldn't save the file here: ${e?.message ?? e}`;
+        }
+    }
+    const out = [{ type: "text", text: JSON.stringify(rest, null, 2) }];
+    // HUDDLE_CTX_MCP_IMAGES=0: path only, for a host that can't take image blocks.
+    if (image?.data_base64 && image?.mime && process.env.HUDDLE_CTX_MCP_IMAGES !== "0")
+        out.push({ type: "image", data: String(image.data_base64), mimeType: String(image.mime) });
+    return out;
+}
+//# sourceMappingURL=context-tools.js.map