huddle-cli 0.0.0-stage → 0.1.0

package/dist/room/identity.js

@@ -0,0 +1,122 @@
+// Identity = your GitHub account, proven with the SSH key you already use for git.
+//
+// GitHub publishes everyone's public SSH keys at https://github.com/<user>.keys.
+// So when a room invites @harsh, whoever joins must sign a one-time challenge
+// with a private key whose public half is on Harsh's GitHub. Huddle verifies
+// with `ssh-keygen -Y verify`. No passwords, no OAuth app, no credentials held —
+// the private key never leaves the joiner's machine.
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const NAMESPACE = "huddle-join";
+const cache = new Map();
+/** "ssh-ed25519 AAAA… comment" → "ssh-ed25519 AAAA…" */
+const bare = (line) => line.trim().split(/\s+/).slice(0, 2).join(" ");
+export async function githubKeys(user) {
+    const hit = cache.get(user.toLowerCase());
+    if (hit && Date.now() - hit.at < 10 * 60_000)
+        return hit.keys;
+    try {
+        const r = await fetch(`https://github.com/${encodeURIComponent(user)}.keys`, { signal: AbortSignal.timeout(8000) });
+        if (!r.ok)
+            return [];
+        const keys = (await r.text()).split("\n").filter((l) => l.startsWith("ssh-")).map(bare);
+        cache.set(user.toLowerCase(), { at: Date.now(), keys });
+        return keys;
+    }
+    catch {
+        return [];
+    }
+}
+/** Your GitHub login, from the gh CLI or git config. */
+export function githubUser() {
+    const gh = spawnSync("gh", ["api", "user", "--jq", ".login"], { encoding: "utf8", timeout: 8000 });
+    if (gh.status === 0 && gh.stdout.trim())
+        return gh.stdout.trim();
+    const g = spawnSync("git", ["config", "github.user"], { encoding: "utf8" });
+    return g.stdout?.trim() || null;
+}
+function localKeyPairs() {
+    const dir = path.join(os.homedir(), ".ssh");
+    let files = [];
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".pub"));
+    }
+    catch {
+        return [];
+    }
+    return files
+        .map((f) => {
+        const pub = path.join(dir, f);
+        const priv = pub.slice(0, -4);
+        try {
+            return { priv, pub, key: bare(fs.readFileSync(pub, "utf8")) };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => !!x && fs.existsSync(x.priv));
+}
+/**
+ * Sign a challenge as GitHub user `user`: pick the local key that's on their
+ * GitHub, sign with ssh-keygen (it asks for your passphrase if the key has one).
+ */
+export async function signAs(user, nonce) {
+    const published = new Set(await githubKeys(user));
+    if (!published.size)
+        return { ok: false, reason: `couldn't read github.com/${user}.keys (no keys, or no network)` };
+    const mine = localKeyPairs().find((k) => published.has(k.key));
+    if (!mine)
+        return { ok: false, reason: `none of your ~/.ssh keys are on github.com/${user} — are you ${user}?` };
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "huddle-sign-"));
+    const msg = path.join(tmp, "challenge");
+    fs.writeFileSync(msg, nonce);
+    const r = spawnSync("ssh-keygen", ["-Y", "sign", "-q", "-f", mine.priv, "-n", NAMESPACE, msg], { stdio: ["inherit", "pipe", "pipe"] });
+    try {
+        if (r.status !== 0)
+            return { ok: false, reason: `ssh-keygen couldn't sign: ${String(r.stderr).trim().split("\n")[0]}` };
+        return { ok: true, key: mine.key, sig: fs.readFileSync(msg + ".sig", "utf8") };
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** Is `sig` a signature of `nonce` by a key that's on github.com/<user>.keys? */
+export async function verifyAs(user, nonce, key, sig) {
+    if (!(await githubKeys(user)).includes(bare(key)))
+        return false;
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "huddle-verify-"));
+    try {
+        const allowed = path.join(tmp, "allowed");
+        const sigFile = path.join(tmp, "sig");
+        fs.writeFileSync(allowed, `${user} namespaces="${NAMESPACE}" ${bare(key)}\n`);
+        fs.writeFileSync(sigFile, sig);
+        const r = spawnSync("ssh-keygen", ["-Y", "verify", "-f", allowed, "-I", user, "-n", NAMESPACE, "-s", sigFile], {
+            input: nonce,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return r.status === 0;
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export const newNonce = () => crypto.randomBytes(24).toString("hex");
+/** "github.com/owner/repo" → "owner/repo", when the remote is on GitHub. */
+export function githubRepo(canonical) {
+    const m = /^github\.com\/([^/]+\/[^/]+)$/.exec(canonical);
+    return m ? m[1] : null;
+}
+/** Can `user` push to owner/repo? true/false, or null if we can't tell (no gh). */
+export function isCollaborator(repo, user) {
+    const r = spawnSync("gh", ["api", `repos/${repo}/collaborators/${user}`, "--silent"], { encoding: "utf8", timeout: 10_000 });
+    if (r.error)
+        return null;
+    if (r.status === 0)
+        return true;
+    return /404|not a collaborator/i.test(`${r.stderr}${r.stdout}`) ? false : null;
+}
+//# sourceMappingURL=identity.js.map

package/dist/room/live.js

@@ -0,0 +1,293 @@
+// Attach mode, the Room side: live sessions. When you run claude, codex and
+// cursor yourself — interactively, each in its own terminal — nobody schedules
+// them. Each one's Plug says hello here instead, and from then on the Room
+// knows who is in the repo, what each is doing, and which files each holds.
+//
+//   hello / heartbeat / bye   presence. A session that stops heart-beating for
+//                             STALE_MS is gone: its leases are released.
+//   announce / check          intent + files ("path", "dir/", "path::symbol").
+//                             Leases match by prefix, so "src/" covers src/a.ts.
+//   guard                     the pre-edit check (Claude's PreToolUse hook):
+//                             warn if someone else holds the file, else lease it.
+//   note / peers              messages between sessions; every reply carries the
+//                             caller's unread notes, so nobody has to poll.
+//
+// Sessions live in memory (presence is ephemeral); leases, notes and memory
+// are in the db, so `huddle peers` and the dashboard can read them.
+import fs from "node:fs";
+import path from "node:path";
+export const LIVE_TASK = "live";
+/** "a/b.ts" "a/" "a/b.ts::fn" — normalized against a checkout root. */
+export function normPath(p, roots) {
+    let [file, sym] = String(p).replace(/\\/g, "/").split("::");
+    file = file.trim();
+    if (path.isAbsolute(file)) {
+        const rel = relativeTo(file, roots) ?? relativeTo(realish(file), roots);
+        if (rel !== null)
+            file = rel;
+    }
+    file = file.replace(/^(\.\/)+/, "").replace(/\/\*\*?$/, "/");
+    if (!file || file === ".")
+        file = "/"; // the whole repo
+    return sym ? `${file}::${sym.trim()}` : file;
+}
+function relativeTo(file, roots) {
+    for (const r of roots) {
+        const rel = path.relative(r, file);
+        if (!rel)
+            return "";
+        if (!rel.startsWith("..") && !path.isAbsolute(rel))
+            return rel.split(path.sep).join("/");
+    }
+    return null;
+}
+/** realpath of the file, or of its nearest existing parent (/tmp vs /private/tmp on macOS). */
+function realish(file) {
+    let dir = file;
+    const rest = [];
+    while (dir !== path.dirname(dir)) {
+        try {
+            return path.join(fs.realpathSync(dir), ...rest.reverse());
+        }
+        catch {
+            rest.push(path.basename(dir));
+            dir = path.dirname(dir);
+        }
+    }
+    return file;
+}
+/** Do two leases cover any of the same code? Directories cover what's under them. */
+/** 42s · 5m · 3h · 2d — how long ago, for notes an agent reads. */
+export function ago(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    return s < 60 ? `${s}s` : s < 3600 ? `${Math.round(s / 60)}m` : s < 86400 ? `${Math.round(s / 3600)}h` : `${Math.round(s / 86400)}d`;
+}
+export function overlaps(a, b) {
+    const [fa, sa] = a.split("::");
+    const [fb, sb] = b.split("::");
+    const dir = (d, f) => d === "/" || (d.endsWith("/") && (f.startsWith(d) || f === d.slice(0, -1)));
+    if (dir(fa, fb) || dir(fb, fa))
+        return true;
+    if (fa !== fb)
+        return false;
+    return !sa || !sb || sa === sb; // same file: only distinct symbols can coexist
+}
+export function liveRoom(db, opts = { repoRoot: process.cwd() }) {
+    const STALE_MS = opts.staleMs ?? 60_000;
+    const LEASE_MS = opts.leaseMs ?? 30 * 60_000;
+    const live = new Map();
+    const end = (s, why) => {
+        live.delete(s.id);
+        db.releaseClaims(s.id);
+        db.setAgentStatus(s.id, "offline");
+        db.publish("live.left", { agent_id: s.id, payload: { id: s.id, agent: s.agent, why } });
+    };
+    // Found live: the laptop slept for 14 minutes in the middle of a run. On
+    // wake the room's first sweep saw every session silent for > STALE_MS and
+    // ended them all at once, so Claude lost its lease on src/strings.js
+    // mid-task (its huddle_release then said "released: []") and Cursor was
+    // handed the same file. Nobody could heartbeat while the whole machine was
+    // asleep, so a gap between sweeps longer than STALE_MS means the ROOM was
+    // suspended, not that the sessions went away: give everyone a fresh window
+    // (and fresh leases) instead. A session that really died in the meantime is
+    // swept one window later.
+    const SWEEP_MS = opts.sweepMs ?? Math.min(STALE_MS, 15_000);
+    let lastSweep = Date.now();
+    const sweep = () => {
+        const now = Date.now();
+        if (now - lastSweep > Math.max(STALE_MS, SWEEP_MS * 3)) {
+            for (const s of live.values()) {
+                s.seen_at = now;
+                db.renewClaims(s.id, now + LEASE_MS);
+            }
+            db.publish("live.resumed", { payload: { asleep_ms: now - lastSweep, sessions: live.size } });
+        }
+        lastSweep = now;
+        for (const s of [...live.values()])
+            if (now - s.seen_at > STALE_MS)
+                end(s, "went quiet");
+    };
+    const timer = setInterval(sweep, SWEEP_MS);
+    timer.unref();
+    const roots = (s) => [...(s ? [s.root] : []), opts.repoRoot];
+    const norm = (list, s) => [...new Set((Array.isArray(list) ? list : [list]).filter(Boolean).map((p) => normPath(String(p), roots(s))))].slice(0, 200);
+    /** Leases held by *other* live sessions that collide with `touches`. */
+    const conflicts = (touches, me) => {
+        const out = [];
+        const claims = db.listClaims().filter((c) => c.task_id === LIVE_TASK && c.held_by !== me && live.has(c.held_by));
+        for (const t of touches)
+            for (const c of claims)
+                if (overlaps(t, c.path)) {
+                    const h = live.get(c.held_by);
+                    out.push({ path: t, held: c.path, held_by: h.id, agent: h.agent, intent: h.intent });
+                }
+        return out;
+    };
+    const holds = (id) => db.listClaims().filter((c) => c.held_by === id && c.task_id === LIVE_TASK).map((c) => c.path);
+    const note = (from, to, body, kind = "note") => db.publish("note", { agent_id: from, payload: { from, to, body: body.slice(0, 2000), kind } });
+    /** Notes for `s` it hasn't seen: addressed to everyone, its id, or its agent name. */
+    const inbox = (s) => {
+        const out = [];
+        for (const e of db.eventsOfType(["note"], s.started_at - 1)) {
+            if (s.seen.has(e.id))
+                continue;
+            const p = JSON.parse(e.payload || "{}");
+            if (p.from === s.id)
+                continue;
+            if (p.to && p.to !== "all" && p.to !== s.id && p.to !== s.agent)
+                continue;
+            s.seen.add(e.id);
+            out.push({ from: p.from, body: p.body, kind: p.kind ?? "note", at: e.ts });
+        }
+        return out;
+    };
+    const peerView = (s, me) => ({
+        id: s.id,
+        agent: s.agent,
+        you: s.id === me,
+        branch: s.branch,
+        worktree: s.root === opts.repoRoot ? "(main checkout)" : path.relative(opts.repoRoot, s.root) || s.root,
+        doing: s.intent || "(hasn't said)",
+        holds: holds(s.id),
+        seen_s_ago: Math.round((Date.now() - s.seen_at) / 1000),
+    });
+    // Found live: notes outlive their sessions (they're in live.db), and a new
+    // codex read an hour-old "I'm adding whisper to strings.js" from a claude
+    // that had long finished as if it were current. So each note says how old it
+    // is and whether its author is still here.
+    // A session sees only notes it may read (to everyone, to it, or from it);
+    // the person's read-only view (`huddle peers`, no session) sees them all.
+    const recentNotes = (n = 10, s) => db
+        .eventsOfType(["note"], 0, s ? n * 5 : n)
+        .map((e) => ({ e, p: JSON.parse(e.payload || "{}") }))
+        .filter(({ p }) => !s || !p.to || p.to === "all" || p.to === s.id || p.to === s.agent || p.from === s.id)
+        .slice(-n)
+        .map(({ e, p }) => ({ from: p.from, to: p.to ?? "all", body: p.body, ago: ago(Date.now() - e.ts), from_live: live.has(p.from) }));
+    const take = (s, touches) => {
+        const exp = Date.now() + LEASE_MS;
+        return touches.filter((t) => db.leaseClaim(t, s.id, LIVE_TASK, exp));
+    };
+    const verbs = {
+        heartbeat: () => ({ ok: true }),
+        peers: (_b, s) => ({
+            sessions: [...live.values()].map((x) => peerView(x, s.id)),
+            notes: recentNotes(10, s),
+        }),
+        announce: (b, s) => {
+            const touches = norm(b.touches, s);
+            const hit = conflicts(touches, s.id);
+            const blocked = new Set(hit.map((c) => c.path));
+            s.intent = String(b.intent ?? "").slice(0, 300) || s.intent;
+            const leased = take(s, touches.filter((t) => !blocked.has(t)));
+            // Tell each holder someone wants their files — they hear it on their next call.
+            for (const h of new Set(hit.map((c) => c.held_by)))
+                note(s.id, h, `${s.id} wants ${hit.filter((c) => c.held_by === h).map((c) => c.held).join(", ")} (you hold it) for: ${s.intent}. Reply with huddle_note, or huddle_release when you're done.`, "heads-up");
+            db.publish("plan.announced", { task_id: LIVE_TASK, agent_id: s.id, payload: { intent: s.intent, touches, conflicts: hit } });
+            return {
+                ok: !hit.length,
+                leased,
+                conflicts: hit,
+                advice: hit.length
+                    ? "STOP: another live session holds some of these. Don't edit them — huddle_note the holder (they've been told you asked), pick other work, or ask your user."
+                    : "Yours. Others will be warned before they edit these. huddle_release when you're done.",
+            };
+        },
+        check: (b, s) => {
+            const hit = conflicts(norm(b.touches, s), s.id);
+            return { clear: !hit.length, conflicts: hit };
+        },
+        release: (b, s) => {
+            const mine = holds(s.id);
+            const want = b.touches?.length ? norm(b.touches, s) : mine;
+            const freed = mine.filter((m) => want.some((w) => overlaps(w, m)));
+            for (const f of freed)
+                db.releaseClaim(f, s.id);
+            if (!b.touches?.length)
+                s.intent = "";
+            db.publish("live.released", { agent_id: s.id, payload: { paths: freed } });
+            return { released: freed };
+        },
+        note: (b, s) => {
+            const body = String(b.body ?? "").trim();
+            if (!body)
+                return { ok: false, error: "empty note" };
+            const to = b.to ? String(b.to) : null;
+            note(s.id, to, body);
+            return { ok: true, to: to ?? "all" };
+        },
+        bye: (_b, s) => {
+            end(s, "closed");
+            return { ok: true };
+        },
+    };
+    return {
+        sessions: () => [...live.values()],
+        close: () => clearInterval(timer),
+        async handle(verb, body, sessionId) {
+            sweep();
+            if (verb === "ping")
+                return { status: 200, body: { ok: true, sessions: live.size } };
+            if (verb === "hello") {
+                const agent = String(body.agent ?? "agent").replace(/[^\w.-]/g, "").slice(0, 24) || "agent";
+                const pid = Number(body.pid) || 0;
+                const root = path.resolve(String(body.root ?? opts.repoRoot));
+                // The same process saying hello again (the room restarted) keeps its id.
+                let s = [...live.values()].find((x) => x.agent === agent && x.pid === pid && pid > 0);
+                if (!s) {
+                    let id = agent;
+                    for (let n = 2; live.has(id); n++)
+                        id = `${agent}#${n}`;
+                    s = { id, agent, pid, root, branch: String(body.branch ?? ""), intent: "", started_at: Date.now(), seen_at: Date.now(), seen: new Set() };
+                    live.set(id, s);
+                    db.upsertAgent({ id, vendor: agent, model: "", role: "worker" });
+                    db.setAgentStatus(id, "working", root);
+                    db.publish("live.joined", { agent_id: id, payload: { id, agent, branch: s.branch, root } });
+                }
+                s.seen_at = Date.now();
+                return { status: 200, body: { id: s.id, peers: [...live.values()].filter((x) => x.id !== s.id).map((x) => peerView(x)) } };
+            }
+            if (verb === "guard") {
+                // Called by a hook, not the Plug: find the session by its process tree.
+                const pids = (Array.isArray(body.pids) ? body.pids : []).map(Number);
+                const s = [...live.values()].find((x) => pids.includes(x.pid));
+                const touches = norm(body.path, s);
+                const hit = conflicts(touches, s?.id);
+                if (hit.length) {
+                    const c = hit[0];
+                    if (s)
+                        note(s.id, c.held_by, `${s.id} is about to edit ${c.path}, which you hold. Their user is being asked to confirm.`, "heads-up");
+                    return {
+                        status: 200,
+                        body: {
+                            decision: "ask",
+                            reason: `Huddle: ${c.path} is held by ${c.held_by} (${c.agent}) — "${c.intent || "no intent given"}". Editing now may collide; check huddle_peers or huddle_note ${c.held_by} first.`,
+                            conflicts: hit,
+                        },
+                    };
+                }
+                if (s) {
+                    s.seen_at = Date.now();
+                    return { status: 200, body: { decision: "allow", session: s.id, leased: take(s, touches) } };
+                }
+                return { status: 200, body: { decision: "allow", session: null } };
+            }
+            const s = live.get(sessionId);
+            // A person peeking in (`huddle peers`) isn't a session: read-only view.
+            if (!s && verb === "peers")
+                return { status: 200, body: { sessions: [...live.values()].map((x) => peerView(x)), notes: recentNotes() } };
+            if (!s)
+                return { status: 409, body: { error: "unknown session — say hello first", rehello: true } };
+            const fn = verbs[verb];
+            if (!fn)
+                return { status: 404, body: { error: `unknown live verb: ${verb}` } };
+            s.seen_at = Date.now();
+            db.renewClaims(s.id, Date.now() + LEASE_MS);
+            const out = fn(body, s);
+            if (verb === "bye")
+                return { status: 200, body: out };
+            const unread = inbox(s);
+            return { status: 200, body: unread.length ? { ...out, notes_for_you: unread } : out };
+        },
+    };
+}
+//# sourceMappingURL=live.js.map

package/dist/room/progress.js

@@ -0,0 +1,110 @@
+// The board as agents see it mid-task: for every task, who owns it, where it
+// is, the owner's last huddle_progress note and how old things are — so an
+// agent can tell a teammate that's nearly done from one that went quiet, and
+// see who took over whose work. Built from the task table plus Room events
+// (task.claimed / task.progress / task.takeover / task.split); no new tables.
+const ago = (s) => (s < 60 ? `${s}s` : s < 3600 ? `${Math.round(s / 60)}m` : `${Math.round(s / 360) / 10}h`);
+const parse = (s) => {
+    try {
+        return JSON.parse(s || "{}");
+    }
+    catch {
+        return {};
+    }
+};
+export function taskViews(db, now = Date.now()) {
+    const evs = db.eventsOfType(["task.claimed", "task.progress", "task.takeover", "task.split"], 0, 1000);
+    const claimed = new Map();
+    const note = new Map();
+    const touched = new Map();
+    const takeover = new Map();
+    const split = new Map();
+    for (const e of evs) {
+        if (!e.task_id)
+            continue;
+        const p = parse(e.payload);
+        touched.set(e.task_id, e.ts);
+        if (e.type === "task.claimed")
+            claimed.set(e.task_id, e.ts);
+        if (e.type === "task.progress" && p.note)
+            note.set(e.task_id, { text: String(p.note), ts: e.ts });
+        if (e.type === "task.takeover" && p.kind !== "split") {
+            takeover.set(e.task_id, { from: String(p.from ?? ""), reason: String(p.reason ?? "") });
+            claimed.set(e.task_id, e.ts); // the new owner's clock starts now
+        }
+        if (e.type === "task.split" && p.parent)
+            split.set(e.task_id, String(p.parent));
+    }
+    const secs = (ts) => Math.max(0, Math.round((now - ts) / 1000));
+    return db.listTasks().map((t) => {
+        const n = note.get(t.id);
+        const tk = takeover.get(t.id);
+        const c = claimed.get(t.id);
+        return {
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            owner: t.claimed_by,
+            progress_pct: t.progress_pct,
+            last_note: n?.text ?? null,
+            last_update_s: secs(Math.max(n?.ts ?? 0, touched.get(t.id) ?? 0, t.updated_at)),
+            age_s: t.status === "backlog" || c === undefined ? null : secs(c),
+            depends_on: JSON.parse(t.depends_on),
+            files: JSON.parse(t.files ?? "[]"),
+            ...(tk ? { taken_over_from: tk.from, takeover_reason: tk.reason } : {}),
+            ...(split.has(t.id) ? { split_from: split.get(t.id) } : {}),
+        };
+    });
+}
+/** One readable line per task: "codex · in_progress 40% · 3m · “wired the parser” (20s ago)". */
+export function progressLine(v) {
+    const who = v.owner ?? "unclaimed";
+    const pct = v.status === "in_progress" || v.status === "claimed" ? ` ${v.progress_pct}%` : "";
+    const age = v.age_s !== null && v.status !== "merged" ? ` · ${ago(v.age_s)} on it` : "";
+    const last = v.last_note ? ` · “${v.last_note.slice(0, 120)}” (${ago(v.last_update_s)} ago)` : "";
+    const tk = v.taken_over_from ? ` · took over from ${v.taken_over_from}` : "";
+    const sp = v.split_from ? ` · split from ${v.split_from}` : "";
+    return `[${v.id}] ${v.title} — ${who} · ${v.status}${pct}${age}${last}${tk}${sp}`;
+}
+/** What huddle_progress hands back: everyone else's in-flight work, at a glance. */
+export function teamProgress(db, exceptTask) {
+    return taskViews(db)
+        .filter((v) => v.id !== exceptTask && ["claimed", "in_progress", "review"].includes(v.status))
+        .map(progressLine);
+}
+/**
+ * The launch prompt's "WORKING ALONGSIDE YOU" section: the other tasks in
+ * flight right now, who is on them, and their files, so an agent knows WHO
+ * to tell when it settles something they also rely on or expose. Found live
+ * (capstone round 2): 0 agent-to-agent messages in a 9-task run; the CLI and
+ * API were built side by side over the same service, and neither agent knew
+ * the other was mid-task without polling huddle_board. Empty when nobody else is working.
+ */
+export function alongsideBrief(db, taskId, agentId) {
+    const others = db
+        .listTasks()
+        .filter((t) => t.id !== taskId && t.claimed_by && t.claimed_by !== agentId && ["claimed", "in_progress"].includes(t.status))
+        .filter((t) => !/^QA round \d+:/.test(t.title));
+    if (!others.length)
+        return "";
+    const lines = others.map((t) => {
+        const files = JSON.parse(t.files ?? "[]").slice(0, 6);
+        return `- ${t.claimed_by}: “${t.title}” (task ${t.id}${files.length ? ` · ${files.join(", ")}` : ""})`;
+    });
+    return (`\n\nWORKING ALONGSIDE YOU right now, each in its own worktree:\n${lines.join("\n")}\n` +
+        `When you settle something one of them also relies on or exposes (a function or data shape, an error message, an output format, a test helper), ` +
+        `huddle_send(to="<agent>", message=…) as soon as you decide it, not at the end. Unsure what theirs does? huddle_ask(…, to="<agent>"). ` +
+        `Nothing they need? Don't send.`);
+}
+/** Was this message Huddle's automatic help offer (sent in a free agent's name), not words the agent wrote? */
+export function isHelpOffer(from, body) {
+    return body.startsWith(`${from} is free and can take part of your task `);
+}
+/** The note an idle agent (or the scheduler on its behalf) drops in a busy teammate's inbox. */
+export function helpOffer(from, taskId, title) {
+    return (`${from} is free and can take part of your task "${title}" (${taskId}). ` +
+        `If a piece of it is separable — ideally in files you won't keep editing — call ` +
+        `huddle_split(task_id="${taskId}", title=…, spec=…, files=[…]) and Huddle hands that part to a free agent; then don't do that part yourself. ` +
+        `If it isn't worth splitting, ignore this.`);
+}
+//# sourceMappingURL=progress.js.map

package/dist/room/relaylink.js

@@ -0,0 +1,85 @@
+// The host's side of the relay: keeps one outbound WebSocket to the relay and
+// serves members through it with the exact same shared API as the direct door.
+import crypto from "node:crypto";
+import { WebSocket } from "ws";
+export function openRelayLink(room, relayUrl, log) {
+    const base = relayUrl.replace(/\/+$/, "").replace(/^http/, "ws");
+    const roomId = crypto.randomBytes(12).toString("base64url");
+    const key = crypto.randomBytes(24).toString("hex");
+    const subs = new Map(); // member connection → unsubscribe
+    let ws;
+    let closed = false;
+    let backoff = 1000;
+    const connect = (first) => {
+        ws = new WebSocket(`${base}/host/${roomId}?key=${key}`);
+        ws.on("open", () => {
+            backoff = 1000;
+            first(true);
+        });
+        ws.on("message", async (raw) => {
+            let m;
+            try {
+                m = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const send = (f, close) => ws.readyState === WebSocket.OPEN && ws.send(JSON.stringify({ t: "to", cid: m.cid, f, ...(close ? { close } : {}) }));
+            if (m.t === "gone") {
+                subs.get(m.cid)?.();
+                subs.delete(m.cid);
+                return;
+            }
+            if (m.t !== "from")
+                return;
+            const f = m.f ?? {};
+            if (f.t === "req") {
+                const r = await room.handleShared({ method: String(f.method), path: String(f.path), token: f.token, body: f.body });
+                send({ t: "res", id: f.id, status: r.status, body: r.body });
+            }
+            else if (f.t === "sub") {
+                const stop = room.subscribe(String(f.token ?? ""), (e) => send({ t: "event", e }), () => send({ t: "closed", code: 4403 }, 4403));
+                if (!stop)
+                    send({ t: "closed", code: 4401 }, 4401);
+                else
+                    subs.set(m.cid, stop);
+            }
+        });
+        ws.on("close", () => {
+            for (const stop of subs.values())
+                stop();
+            subs.clear();
+            if (closed)
+                return;
+            setTimeout(() => connect(() => { }), backoff);
+            backoff = Math.min(backoff * 2, 30_000);
+        });
+        ws.on("error", () => first(false));
+    };
+    return new Promise((resolve) => {
+        let done = false;
+        const timer = setTimeout(() => {
+            if (!done)
+                (done = true), resolve(null);
+        }, 10_000);
+        connect((ok) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (!ok) {
+                closed = true;
+                log(`  couldn't reach the relay at ${relayUrl}`);
+                return resolve(null);
+            }
+            resolve({
+                address: `${base}/r/${roomId}`,
+                close: () => {
+                    closed = true;
+                    ws.close(1000);
+                },
+            });
+        });
+    });
+}
+//# sourceMappingURL=relaylink.js.map