huddle-cli 0.1.0 → 0.1.1

package/dist/attach/plug.js

@@ -7,6 +7,8 @@ import { execFileSync } from "node:child_process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { contextTools, toContent } from "../mcp/context-tools.js";
+import { packageInfo } from "../preflight.js";
 import { checkoutRoot, ensureLive, liveCall, mainRoot, roomCall } from "./live.js";
 /** What every attached agent is told, via the MCP `instructions` field. */
 export const LIVE_INSTRUCTIONS = `
@@ -16,6 +18,7 @@ Before you edit ANY file:
 2. huddle_announce_plan(intent, touches) with every file (or "dir/") you'll change. If it returns conflicts, DO NOT edit those files: huddle_note the holder or pick other work, and tell your user.
 3. When you finish a change, huddle_release so the others can proceed.
 Notes from other sessions arrive in "notes_for_you" on any huddle_* reply — read them and answer with huddle_note. Record lasting decisions with huddle_remember.
+The shared screen holds what your user put up for everyone (logs, docs, screenshots): huddle_context lists it, huddle_context_read / huddle_context_search open it, huddle_context_note pins what you found.
 `.trim();
 const tools = [
     {
@@ -119,7 +122,12 @@ export async function runLivePlug() {
             await sayHello();
         return roomCall(st, method, p, body, sid);
     };
+    // The shared screen: the same tools (and Room routes) as a `huddle join` agent's Plug.
+    const screen = contextTools((p, method, body) => plain(method, p, body ?? {}));
     const call = (name, a) => {
+        const ctx = screen.find((t) => t.name === name);
+        if (ctx)
+            return ctx.handler(a);
         switch (name) {
             case "huddle_peers":
                 return live("peers", {});
@@ -139,12 +147,15 @@ export async function runLivePlug() {
         }
         throw new Error(`unknown tool: ${name}`);
     };
-    const server = new Server({ name: "huddle", version: "0.1.0" }, { capabilities: { tools: {} }, instructions: LIVE_INSTRUCTIONS });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools.map((t) => ({ ...t })) }));
+    const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: LIVE_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...tools.map((t) => ({ ...t })), ...screen.map(({ handler: _h, ...t }) => t)],
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         try {
             const result = await call(req.params.name, req.params.arguments ?? {});
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            // toContent: JSON text, plus an MCP image block for a screenshot.
+            return { content: toContent(result) };
         }
         catch (e) {
             // Never wedge the agent: say what's wrong and let it carry on.

package/dist/attach/screen.js

@@ -0,0 +1,150 @@
+// Attach mode, the human's side of the shared screen: `huddle add` and
+// `huddle ctx`, typed in any terminal while your own claude / codex / cursor
+// sessions run in theirs.
+//
+//   huddle add err.log src/auth/ "*.png"   files, folders (one bundle), globs
+//   cat err.log | huddle add -              stdin (pbpaste | huddle add - too)
+//   huddle ctx [show <id>|rm <id>|note <id> <text>|clear]
+//
+// Same store, same commands as the `huddle` prompt (src/ui/paste.ts on
+// src/room/context.ts) — only the db differs: the live room's .huddle/live.db.
+// The room reads that db on every call, so writing it here is the same whether
+// the room is up or not; when it's up, each session hears about a new item (or
+// a pinned note) in notes_for_you on its next huddle_* call — the path
+// huddle_note takes (src/room/live.ts, inbox).
+import fs from "node:fs";
+import path from "node:path";
+import { getAdapter } from "../adapters/index.js";
+import { ContextStore, normalizePathToken } from "../room/context.js";
+import { RoomDB } from "../room/db.js";
+import { addPaths, addPiped, ctxCommand } from "../ui/paste.js";
+import { C } from "../ui/term.js";
+import { confirm } from "./connect.js";
+import { ensureHuddleDir, liveCall, liveFiles, mainRoot, pingLive, readLive } from "./live.js";
+/** The sessions in the live room right now (agent names), or null when it's down. */
+async function liveAgents(repo) {
+    const st = readLive(repo);
+    if (!st || !(await pingLive(st)))
+        return null;
+    try {
+        const r = await liveCall(st, "peers", {}, "", 2000);
+        return (r.body.sessions ?? []).map((s) => String(s.agent));
+    }
+    catch {
+        return null;
+    }
+}
+/** A ScreenUI on the live room's store. `interactive` = a person can answer the secrets question. */
+function screenUI(repo, agents, interactive) {
+    let db = null;
+    const ui = {
+        print: (l = "") => console.log(l),
+        yes: (q, def = true) => confirm(q, def),
+        db: async () => {
+            if (!db) {
+                ensureHuddleDir(repo); // .huddle/ with its own .gitignore
+                db = new RoomDB(liveFiles(repo).db);
+            }
+            return db;
+        },
+        audience: () => {
+            const list = [...new Set(agents ?? [])];
+            return { agents: list, companies: new Set(list.map((a) => getAdapter(a)?.vendor ?? a)).size };
+        },
+        root: () => repo,
+        interactive,
+        announce: false, // the live room delivers it with each session's notes
+    };
+    return { ui, close: () => db?.close() };
+}
+function needRepo() {
+    const repo = mainRoot();
+    if (!repo)
+        console.log(C.red("✗ Not a git repo.") + " The shared screen belongs to a repo — cd into the one your agents work in.");
+    return repo;
+}
+/**
+ * A path as typed: file:// URLs and ~ resolved (cmd.exe expands neither), and
+ * Windows separators read as "/" where "\" isn't one (logs\err.log on macOS).
+ */
+export function cliPath(arg, cwd = process.cwd()) {
+    const p = normalizePathToken(arg);
+    if (path.sep === "\\" || !p.includes("\\") || fs.existsSync(path.resolve(cwd, p)))
+        return p;
+    return p.replace(/\\/g, "/");
+}
+async function readAllStdin(stdin = process.stdin) {
+    let s = "";
+    for await (const c of stdin)
+        s += c.toString();
+    return s;
+}
+/** `huddle add <file|folder|glob|->…` — `--title <t>` names a stdin item. */
+export async function runAdd(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    let title;
+    const paths = [];
+    let piped = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--title" && i + 1 < args.length)
+            title = args[++i];
+        else if (a.startsWith("--title="))
+            title = a.slice(8);
+        else if (a === "-")
+            piped = true;
+        else
+            paths.push(cliPath(a));
+    }
+    if (!paths.length && !piped) {
+        console.log(`usage: ${C.bold("huddle add <file|folder|glob>")} … ${C.faint("· or pipe it:")} ${C.bold("cat err.log | huddle add -")}`);
+        return void (process.exitCode = 1);
+    }
+    if (piped && process.stdin.isTTY) {
+        console.log(C.red("  ✗ nothing piped in") + C.faint(" — e.g. pbpaste | huddle add -   ·   cat err.log | huddle add -"));
+        return void (process.exitCode = 1);
+    }
+    const agents = await liveAgents(repo);
+    // Stdin is the pipe with `-`, so nobody can answer: secrets are redacted.
+    const { ui, close } = screenUI(repo, agents, !piped && !!process.stdin.isTTY && !!process.stdout.isTTY);
+    let failed = 0;
+    let before = 0;
+    try {
+        const store = ContextStore.open((await ui.db()));
+        before = store.list().length;
+        if (piped && !(await addPiped(store, await readAllStdin(), ui, { title })))
+            failed++;
+        if (paths.length)
+            failed += await addPaths(paths, ui);
+        const added = store.list().length - before;
+        if (added > 0)
+            console.log(C.faint(agents === null
+                ? "     no live room right now — sessions find it with huddle_context when they're up"
+                : agents.length
+                    ? `     ${[...new Set(agents)].join(", ")} see it on their next huddle_* call`
+                    : "     live room is up; sessions that join find it with huddle_context"));
+    }
+    finally {
+        close();
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+/** `huddle ctx [list|show <id>|rm <id…>|note <id> <text>|clear|add <path…>]` */
+export async function runCtx(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    const { ui, close } = screenUI(repo, await liveAgents(repo), !!process.stdin.isTTY && !!process.stdout.isTTY);
+    try {
+        if (args[0] === "add")
+            return void (await addPaths(args.slice(1).map((a) => cliPath(a)), ui));
+        await ctxCommand(args.join(" "), ui);
+    }
+    finally {
+        close();
+    }
+}
+//# sourceMappingURL=screen.js.map

package/dist/attach/session.js

@@ -4,11 +4,13 @@
 // 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.
+// 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";
@@ -78,7 +80,7 @@ export async function runAttach(args) {
     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 = spawnSync(cmd[0], [...cmd.slice(1), ...passthrough], { cwd: wt.path, stdio: "inherit" });
+    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();
@@ -162,6 +164,9 @@ export async function runPeers() {
         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")}`);

package/dist/cli.js

@@ -8,96 +8,151 @@
 //     --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 said what to whom, reviews, merges
+//   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 { runPlug } from "./mcp/server.js";
-import { C } from "./ui/term.js";
-import { connectAgents, ensureInit, huddleDir, printBoard, runApp, runGoal } from "./ui/app.js";
-import { INVITE_CODE, joinRoom } from "./ui/remote.js";
-import { startRelay } from "./relay/server.js";
-import { runDoctor } from "./ui/doctor.js";
+import { C, useAsciiOutput } from "./ui/term.js";
 import { SqliteUnavailableError } from "./room/sqlite.js";
-import { installConnector, printCatalog } from "./ui/catalog.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
 
-  ${C.bold("huddle")}                      open Huddle
-  ${C.bold('huddle join "<goal>"')}        plan the goal and run your agents
-  ${C.bold('huddle join "<goal>" --plan')} dry run — show who'd do what
-  ${C.bold("  --approvals=safe|auto|yolo")}  what agents may do without asking (default auto)
-  ${C.bold("  --agents=claude,codex")}       only these agents work on this run
-  ${C.bold("  --council | --no-council")}    every agent brainstorms the design first ${C.faint("(default: big goals only)")}
-  ${C.bold("  --qa")} ${C.faint("/")} ${C.bold("--no-qa")}             agents re-check the build and fix what they find ${C.faint("(default: big goals)")}
-  ${C.bold("huddle join <address> <CODE>")} join someone's room from an invite
-  ${C.bold("huddle doctor")}               check this machine: node, git, your agents
-  ${C.bold("huddle agents --all")}         every connector Huddle knows, installed or not
-  ${C.bold("huddle agents install <id>")}  install one (asks first)
-  ${C.bold("huddle relay")} ${C.faint("[--port 8080]")}  run a relay so rooms work across networks
-  ${C.bold("huddle board")}                print the board
-  ${C.bold("huddle view")} ${C.faint("[repo]")}          watch a run live from another terminal ${C.faint("(read-only)")}
-  ${C.bold("huddle story")} ${C.faint("[--html f]")}     replay the last run: messages, reviews, merges ${C.faint("(--list, --run n)")}
-  ${C.bold("huddle --version")}            print the version
+  ${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
 
-  ${C.faint("run claude, codex and cursor yourself — in one repo, safely:")}
-  ${C.bold("huddle connect")}              wire your agents into this repo's live room ${C.faint("(asks first)")}
-  ${C.bold("huddle peers")}                who's live, what they're doing, which files they hold
-  ${C.bold("huddle attach <agent>")}       open an agent in its own worktree branch
-  ${C.bold("huddle land")} ${C.faint("[branch]")}         test + merge that session's work
-  ${C.bold("huddle up")} ${C.faint("/")} ${C.bold("down")} ${C.faint("/")} ${C.bold("disconnect")}  start · stop the live room · unwire
+  ${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 runApp();
+            return (await app()).runApp();
         case "plug":
-            return runPlug();
-        case "init":
+            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 "doctor":
-        case "agents":
+        }
+        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();
-            process.exitCode = await runDoctor();
+            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 goal = rest.filter((a) => !a.startsWith("--")).join(" ");
+            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");
-            const probed = await connectAgents();
+            let probed = await connectAgents();
             let results = probed;
-            // --agents=claude,codex: run with just these (the rest sit this one out).
+            // --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(", ")}`);
@@ -115,18 +170,25 @@ async function main() {
             return runGoal(goal, { results, probed, mode: rest.includes("--plan") ? "plan" : "auto", approvals, council, qa });
         }
         case "board":
-            return printBoard();
+            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":
@@ -137,6 +199,11 @@ async function main() {
             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");
@@ -145,6 +212,7 @@ async function main() {
                 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;

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