agent-rooms 0.9.1 → 0.11.0

package/dist/listener.js

@@ -1,8 +1,10 @@
 // The listener runtime behind `agent-rooms watch`: registers running instances,
 // holds the socket to the cloud, and spawns idle local agents on wake.
-import { platform } from "node:os";
+import { randomUUID } from "node:crypto";
+import { cpus, platform } from "node:os";
 import { loadConfig, openclawSessionKey, recordSession, roomSessionKey, saveConfig } from "./config.js";
 import { listenerPost } from "./api.js";
+import { createNormalizer } from "./normalize.js";
 import { getAdapter, isSkillInstalled } from "./hosts.js";
 import { ensureClaudeMdBridge, writeRoomMd } from "./bridge.js";
 import { runWake } from "./spawn.js";
@@ -11,9 +13,21 @@ import { log } from "./log.js";
 const HEARTBEAT_MS = 60_000;
 // §5.5 — spawn-rate / concurrency caps. A wake storm (a malicious collaborator
 // hammering @mentions, or a chatter loop) must not fork-bomb the machine or blow
-// up model cost (#41). Caps sit far above any real workload; tune via env.
-const MAX_CONCURRENT_SPAWNS = clampInt(process.env.AGENT_ROOMS_MAX_CONCURRENT_SPAWNS, 3, 1, 32);
-const MAX_SPAWNS_PER_MIN = clampInt(process.env.AGENT_ROOMS_MAX_SPAWNS_PER_MIN, 20, 1, 600);
+// up model cost (#41).
+//
+// Concurrency is NOT a hard product limit on how many agents you can run — it's
+// how many can spawn at the *same instant* on one machine; the rest just wait a
+// beat (their mentions stay queued server-side, nothing is lost). A spawn is a
+// heavy agent CLI that mostly waits on the model API, so the real limit is RAM +
+// model cost, not CPU — but core count is a fair proxy for "how much machine you
+// have". So the default now scales with the box (floor 4) instead of a fixed 3,
+// and the env override goes much higher for beefy machines. The per-minute *rate*
+// cap is the actual brake on a runaway loop, regardless of concurrency.
+const CPU_COUNT = Math.max(1, cpus().length);
+const DEFAULT_CONCURRENT_SPAWNS = Math.min(32, Math.max(4, CPU_COUNT));
+const DEFAULT_SPAWNS_PER_MIN = Math.max(30, CPU_COUNT * 4);
+const MAX_CONCURRENT_SPAWNS = clampInt(process.env.AGENT_ROOMS_MAX_CONCURRENT_SPAWNS, DEFAULT_CONCURRENT_SPAWNS, 1, 128);
+const MAX_SPAWNS_PER_MIN = clampInt(process.env.AGENT_ROOMS_MAX_SPAWNS_PER_MIN, DEFAULT_SPAWNS_PER_MIN, 1, 1200);
 const RATE_WINDOW_MS = 60_000;
 // Spec 21: how long to back off after the model provider reports a hard rate-limit.
 const RATE_LIMIT_BACKOFF_MS = clampInt(process.env.AGENT_ROOMS_RATE_LIMIT_BACKOFF_MS, 30_000, 1000, 300_000);
@@ -341,11 +355,26 @@ export class ListenerRuntime {
             this.emit("warn", `Model provider rate-limited; backing off ${Math.round(waitMs / 1000)}s before waking ${wake.target}.`, "rate_limit_backoff");
             await new Promise((resolve) => setTimeout(resolve, waitMs));
         }
+        // Spec 31: mint the claude session id on the FIRST run for this (agent, room)
+        // so continuity + the resume command exist from turn one. Codex mints its own
+        // thread_id (captured post-run); other hosts keep their existing behavior.
+        const mintSessionId = binding.host === "claude_code" && !sessionId ? randomUUID() : undefined;
         // Register an abort handle so an owner stop can terminate this run mid-flight.
         const abort = new AbortController();
         this.trackSpawn(wake.target, abort);
         this.inFlightSpawns += 1;
         this.recentSpawns.push(Date.now());
+        // Spec 31: live activity stream. Normalize the host's NDJSON into RunEvents
+        // and relay them upstream in small batches on the same authed control route
+        // wake_results use. Streaming is best-effort (drop on the floor if the post
+        // fails) — but run_started/run_finished always go (terminal state is not
+        // best-effort). Only claude_code/codex have normalizers; other hosts skip.
+        const streamable = binding.host === "claude_code" || binding.host === "codex";
+        const instanceIdForRun = wake.instance_id ?? this.instanceByAgentWorkspace.get(bindingKey(binding.agent, binding.workspace));
+        const relay = streamable && instanceIdForRun && config.device
+            ? this.createRunRelay(binding, wake, instanceIdForRun, config.device.token)
+            : null;
+        relay?.push(relay.normalizer.start());
         // Spec 21: wakes run UNSANDBOXED on every host by default — it's the only mode
         // that actually does work (a contained agent can read + post but can't build,
         // edit, or run anything). This is independent of who/how the wake was triggered,
@@ -356,12 +385,21 @@ export class ListenerRuntime {
         const fullAccess = process.env.AGENT_ROOMS_WAKE_CONTAIN !== "1";
         let outcome;
         try {
-            outcome = await runWake(adapter, { prompt, workspace: binding.workspace, sessionId, sessionKey: sessionKeyForHost, maxTurns: this.maxTurns, fullAccess, env }, undefined, abort.signal);
+            outcome = await runWake(adapter, { prompt, workspace: binding.workspace, sessionId, mintSessionId, sessionKey: sessionKeyForHost, maxTurns: this.maxTurns, fullAccess, env }, undefined, abort.signal, relay ? (line) => { for (const ev of relay.normalizer.line(line))
+                relay.push(ev); } : undefined);
         }
         finally {
             this.inFlightSpawns -= 1;
             this.untrackSpawn(wake.target, abort);
         }
+        // Terminal state is never best-effort: crash / kill / nonzero exit with no
+        // vendor terminal event still lands a run_finished (failed) in the room.
+        if (relay) {
+            const fin = relay.normalizer.finish(outcome.code, outcome.status === "replied" ? "ok" : outcome.status === "stopped" || outcome.status === "timeout" || outcome.status === "error" ? "failed" : undefined);
+            if (fin)
+                relay.push(fin);
+            await relay.flush(true).catch(() => { });
+        }
         // Spec 21: if the run hit a hard rate-limit, set the cooldown so the next wake backs off.
         if (outcome.rateLimited) {
             this.rateLimitCooldownUntil = Date.now() + RATE_LIMIT_BACKOFF_MS;
@@ -370,8 +408,11 @@ export class ListenerRuntime {
         // wake in THIS room resumes THIS room's session — never another room's. OpenClaw
         // needs no stored id (its stable per-room session-key is the lock), so we only
         // record for resume-by-id hosts.
-        if (outcome.sessionId && !isOpenClaw) {
-            const next = recordSession(config, key, outcome.sessionId);
+        // Spec 31: the minted id is authoritative when the stream didn't echo one
+        // (claude accepts --session-id verbatim, so the transcript lives under it).
+        const settledSessionId = outcome.sessionId ?? mintSessionId ?? null;
+        if (settledSessionId && !isOpenClaw) {
+            const next = recordSession(config, key, settledSessionId);
             saveConfig(next);
             this.config = next;
         }
@@ -407,12 +448,87 @@ export class ListenerRuntime {
                 instance_id: instanceId,
                 room: wake.room,
                 status: reported,
-                session_id: outcome.sessionId ?? undefined
+                session_id: settledSessionId ?? undefined
             }).catch((error) => this.emit("warn", `wake_result post failed: ${error.message}`, "wake_result_failed"));
         }
         this.emit(outcome.status === "error" ? "warn" : "info", `${adapter.name} wake finished with ${outcome.status}.`, "wake_finished");
         return { status: reported };
     }
+    /** Spec 31: batches RunEvents and posts them upstream (~800ms cadence, cap 25
+     *  per frame). WS-down / post-fail behavior: keep a bounded buffer (drop the
+     *  oldest mid-run events beyond it), but always retry hard for run_finished —
+     *  live fidelity is best-effort, terminal state is not. */
+    createRunRelay(binding, wake, instanceId, token) {
+        const runId = randomUUID();
+        const normalizer = createNormalizer(binding.host, runId);
+        const queue = [];
+        let timer = null;
+        let posting = false;
+        const BUFFER_CAP = 200;
+        const post = async (events, retries) => {
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    await listenerPost(this.apiBase, token, {
+                        t: "run_event", v: 1, id: rid(), instance_id: instanceId, room: wake.room,
+                        host: binding.host, trigger_message_id: wake.trigger_message_id, events
+                    });
+                    return;
+                }
+                catch (error) {
+                    if (attempt >= retries)
+                        throw error;
+                    await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+                }
+            }
+        };
+        const flush = async (final = false) => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            if (posting && !final)
+                return; // next tick picks it up
+            while (queue.length > 0) {
+                posting = true;
+                const batch = queue.splice(0, 25);
+                const hasTerminal = batch.some((e) => e.kind === "run_finished" || e.kind === "run_started");
+                try {
+                    await post(batch, hasTerminal ? 3 : 0);
+                }
+                catch (error) {
+                    if (!final)
+                        this.emit("warn", `run_event relay failed: ${error.message}`, "run_relay_failed");
+                }
+                finally {
+                    posting = false;
+                }
+                if (!final)
+                    break; // live mode: one batch per tick, keep latency low
+            }
+            if (queue.length > 0 && !final && !timer) {
+                timer = setTimeout(() => void flush(), 200);
+                timer.unref?.();
+            }
+        };
+        return {
+            runId,
+            normalizer,
+            push: (ev) => {
+                queue.push(ev);
+                // bound the live buffer: drop oldest NON-terminal events beyond the cap
+                if (queue.length > BUFFER_CAP) {
+                    const idx = queue.findIndex((e) => e.kind !== "run_started" && e.kind !== "run_finished");
+                    if (idx >= 0)
+                        queue.splice(idx, 1);
+                }
+                if (!timer && !posting) {
+                    timer = setTimeout(() => void flush(), 800);
+                    timer.unref?.();
+                }
+            },
+            flush
+        };
+    }
     trackSpawn(target, abort) {
         const set = this.running.get(target) ?? new Set();
         set.add(abort);
@@ -457,6 +573,10 @@ export class ListenerRuntime {
             if (exact)
                 return exact;
         }
+        // KNOWN GAP (Specs/28-ROOM-SCOPED-WAKE-ENFORCEMENT.md): the agent-only
+        // fallback below defeats `init --room` scoping — wakes for unbound rooms
+        // still spawn. It also papers over the rooms-joined-after-binding case, so
+        // do NOT remove it without the wildcard/rebind decision in Spec 28.
         return bindings.find((b) => b.agent === wake.target && b.rooms.includes(wake.room))
             ?? bindings.find((b) => b.agent === wake.target)
             ?? null;

package/dist/normalize.js

@@ -0,0 +1,269 @@
+// Spec 31 — the normalizer: one module per host mapping vendor stream events to
+// OUR RunEvent vocabulary. This is the shock absorber for vendor schema drift;
+// the backend and UI never see a vendor shape. Unknown events become generic
+// `activity` rows — a run must NEVER crash on an unrecognized event.
+import { log } from "./log.js";
+const TEXT_CAP = 2048; // per-event payload cap (spec §4.2)
+const EVENT_CAP = 500; // relayed events per run; past it only structure survives
+const cap = (s) => (s.length > TEXT_CAP ? `${s.slice(0, TEXT_CAP)}…` : s);
+export function createNormalizer(host, runId) {
+    const state = {
+        seq: 0,
+        relayed: 0,
+        finished: false,
+        // summary counters (count everything, even past the relay cap)
+        actions: 0,
+        files: 0,
+        commands: 0,
+        // codex: command item id → the seq of its `command` event (for patching)
+        cmdSeqById: new Map(),
+        // claude: tool_use id → { seq, kind } so tool_result patches the right row
+        toolById: new Map(),
+        // one todo row per run — replaced in place
+        todoSeq: null,
+        sawTurnFailed: false
+    };
+    const next = (partial) => {
+        state.seq += 1;
+        return { run_id: runId, seq: state.seq, ts: Date.now(), ...partial };
+    };
+    /** Relay-cap filter: past EVENT_CAP, only structural events survive. */
+    const emit = (ev) => {
+        if (!ev)
+            return [];
+        state.relayed += 1;
+        if (state.relayed > EVENT_CAP) {
+            const keep = ev.kind === "command" || ev.kind === "command_result" || ev.kind === "file_change"
+                || ev.kind === "todo" || ev.kind === "run_finished";
+            if (!keep)
+                return [];
+        }
+        return [ev];
+    };
+    const mapLine = host === "codex" ? codexLine : claudeLine;
+    return {
+        start() {
+            return next({ kind: "run_started" });
+        },
+        line(raw) {
+            const line = raw.trim();
+            if (!line.startsWith("{"))
+                return [];
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch {
+                return [];
+            }
+            try {
+                return mapLine(obj, state, next).flatMap((e) => emit(e));
+            }
+            catch (error) {
+                // Never crash the run on a weird event; surface it generically.
+                log.warn(`normalizer(${host}): ${error.message}`);
+                return emit(next({ kind: "activity", label: "event", detail: cap(String(obj.type ?? "unknown")) }));
+            }
+        },
+        finish(exitCode, forcedOutcome) {
+            if (state.finished)
+                return null;
+            state.finished = true;
+            const outcome = forcedOutcome ?? (state.sawTurnFailed || exitCode !== 0 ? "failed" : "ok");
+            return next({
+                kind: "run_finished",
+                outcome,
+                summary: { actions: state.actions, files: state.files, commands: state.commands }
+            });
+        }
+    };
+}
+// ── claude_code: `--output-format stream-json` ───────────────────────────────
+// assistant text → text · Bash tool_use → command · matching tool_result →
+// command_result · Edit/Write/MultiEdit → file_change · TodoWrite → todo ·
+// other tool_use → activity. Field shapes verified against live stream-json:
+// {"type":"assistant","message":{"content":[{"type":"text","text":…}|{"type":
+// "tool_use","id":…,"name":…,"input":{…}}]}} and {"type":"user","message":
+// {"content":[{"type":"tool_result","tool_use_id":…,"is_error":…}]}}.
+function claudeLine(obj, state, next) {
+    const type = obj.type;
+    if (type === "assistant" || type === "user") {
+        const message = obj.message;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        const out = [];
+        for (const block of content) {
+            if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+                out.push(next({ kind: "text", text: cap(block.text.trim()) }));
+                continue;
+            }
+            if (block.type === "tool_use" && typeof block.name === "string") {
+                state.actions += 1;
+                const input = (block.input ?? {});
+                const id = typeof block.id === "string" ? block.id : "";
+                const name = block.name;
+                if (name === "Bash") {
+                    state.commands += 1;
+                    const ev = next({ kind: "command", command: cap(String(input.command ?? "")) });
+                    if (id)
+                        state.toolById.set(id, { seq: ev.seq, name });
+                    out.push(ev);
+                }
+                else if (name === "Edit" || name === "Write" || name === "MultiEdit" || name === "NotebookEdit") {
+                    state.files += 1;
+                    out.push(next({
+                        kind: "file_change",
+                        file: cap(String(input.file_path ?? input.path ?? "")),
+                        verb: name === "Write" ? "write" : "edit"
+                    }));
+                }
+                else if (name === "Read") {
+                    out.push(next({ kind: "file_change", file: cap(String(input.file_path ?? "")), verb: "read" }));
+                }
+                else if (name === "TodoWrite") {
+                    const todos = Array.isArray(input.todos) ? input.todos : [];
+                    const items = todos.map((t) => ({
+                        text: cap(String(t.content ?? t.activeForm ?? "")),
+                        done: t.status === "completed"
+                    }));
+                    const ev = next({ kind: "todo", items, ref_seq: state.todoSeq ?? undefined });
+                    state.todoSeq = state.todoSeq ?? ev.seq;
+                    ev.ref_seq = state.todoSeq;
+                    out.push(ev);
+                }
+                else {
+                    // MCP room tools, WebSearch, Grep/Glob, Task … → generic activity
+                    const short = name.replace(/^mcp__agent-rooms__/, "room: ").replace(/^mcp__/, "");
+                    out.push(next({ kind: "activity", label: cap(short), detail: cap(oneLine(input)) }));
+                }
+                continue;
+            }
+            if (block.type === "tool_result") {
+                const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                const ref = id ? state.toolById.get(id) : undefined;
+                if (ref?.name === "Bash") {
+                    state.toolById.delete(id);
+                    out.push(next({
+                        kind: "command_result",
+                        ref_seq: ref.seq,
+                        exit_code: block.is_error ? 1 : 0
+                    }));
+                }
+            }
+        }
+        return out;
+    }
+    if (type === "result") {
+        // handled by finish(); the final text already streamed as assistant text
+        return [];
+    }
+    if (type === "system" || type === "rate_limit_event")
+        return [];
+    return [next({ kind: "activity", label: cap(String(type ?? "event")) })];
+}
+// ── codex: `exec --json` ─────────────────────────────────────────────────────
+// item.* events with item.type ∈ agent_message | reasoning | command_execution |
+// file_change | todo_list | mcp_tool_call | web_search | error. Transient
+// "Reconnecting…" errors are non-fatal. turn.failed → failed outcome.
+function codexLine(obj, state, next) {
+    const type = String(obj.type ?? "");
+    if (type === "thread.started" || type === "turn.started" || type === "turn.completed")
+        return [];
+    if (type === "turn.failed") {
+        state.sawTurnFailed = true;
+        return [];
+    }
+    if (type === "error") {
+        const message = String(obj.message ?? "");
+        if (/reconnecting/i.test(message))
+            return []; // transient, non-fatal
+        return [next({ kind: "activity", label: "error", detail: cap(message) })];
+    }
+    if (!type.startsWith("item.")) {
+        return [next({ kind: "activity", label: cap(type || "event") })];
+    }
+    const item = (obj.item ?? {});
+    const itemType = String(item.type ?? "");
+    const itemId = typeof item.id === "string" ? item.id : "";
+    const phase = type; // item.started | item.updated | item.completed
+    switch (itemType) {
+        case "agent_message": {
+            if (phase !== "item.completed")
+                return [];
+            const text = String(item.text ?? "").trim();
+            return text ? [next({ kind: "text", text: cap(text) })] : [];
+        }
+        case "command_execution": {
+            if (phase === "item.started") {
+                state.actions += 1;
+                state.commands += 1;
+                const ev = next({ kind: "command", command: cap(String(item.command ?? "")) });
+                if (itemId)
+                    state.cmdSeqById.set(itemId, ev.seq);
+                return [ev];
+            }
+            if (phase === "item.completed") {
+                const ref = itemId ? state.cmdSeqById.get(itemId) : undefined;
+                if (ref == null)
+                    return [];
+                state.cmdSeqById.delete(itemId);
+                const exit = Number(item.exit_code);
+                return [next({
+                        kind: "command_result",
+                        ref_seq: ref,
+                        exit_code: Number.isFinite(exit) ? exit : (item.status === "failed" ? 1 : 0)
+                    })];
+            }
+            return [];
+        }
+        case "file_change": {
+            if (phase !== "item.completed")
+                return [];
+            state.actions += 1;
+            const changes = Array.isArray(item.changes) ? item.changes : [];
+            if (changes.length === 0) {
+                state.files += 1;
+                return [next({ kind: "file_change", file: cap(String(item.path ?? "")), verb: "edit" })];
+            }
+            state.files += changes.length;
+            return changes.map((c) => next({
+                kind: "file_change",
+                file: cap(String(c.path ?? "")),
+                verb: c.kind === "add" ? "write" : "edit"
+            }));
+        }
+        case "todo_list": {
+            const todos = Array.isArray(item.items) ? item.items : [];
+            const items = todos.map((t) => ({ text: cap(String(t.text ?? "")), done: t.completed === true }));
+            const ev = next({ kind: "todo", items });
+            state.todoSeq = state.todoSeq ?? ev.seq;
+            ev.ref_seq = state.todoSeq;
+            return [ev];
+        }
+        case "reasoning":
+            return []; // internal noise — never relayed
+        case "web_search": {
+            if (phase !== "item.started" && phase !== "item.completed")
+                return [];
+            if (phase === "item.started")
+                state.actions += 1;
+            return phase === "item.started"
+                ? [next({ kind: "activity", label: "web search", detail: cap(String(item.query ?? "")) })]
+                : [];
+        }
+        case "mcp_tool_call": {
+            if (phase !== "item.started")
+                return [];
+            state.actions += 1;
+            const tool = String(item.tool ?? item.name ?? "tool").replace(/^agent-rooms\./, "room: ");
+            return [next({ kind: "activity", label: cap(tool) })];
+        }
+        case "error":
+            return [next({ kind: "activity", label: "error", detail: cap(String(item.message ?? "")) })];
+        default:
+            return [next({ kind: "activity", label: cap(itemType || "event") })];
+    }
+}
+function oneLine(input) {
+    const hint = input.description ?? input.query ?? input.pattern ?? input.url ?? input.command ?? "";
+    return String(hint).split("\n")[0] ?? "";
+}

package/dist/spawn.js

@@ -210,7 +210,7 @@ const DEFAULT_WAKE_TIMEOUT_MS = (() => {
     const n = Number(process.env.AGENT_ROOMS_WAKE_TIMEOUT_MS);
     return Number.isFinite(n) && n > 0 ? n : 60 * 60 * 1000;
 })();
-export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, signal) {
+export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, signal, onStreamLine) {
     const { command, args, cwd, stdin, env } = adapter.buildWake(spec);
     log.info(`spawn ${adapter.name}: ${command} ${args.filter((a) => !a.includes("\n")).slice(0, 6).join(" ")}…  (cwd ${cwd})`);
     const startedAt = Date.now();
@@ -293,6 +293,14 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
                     rateLimited = true;
                 if (!DEBUG)
                     summarise(line);
+                // Spec 31: live stream tap — the normalizer turns this into RunEvents.
+                // A throwing consumer must never kill the run.
+                if (onStreamLine) {
+                    try {
+                        onStreamLine(line);
+                    }
+                    catch { /* consumer's problem, not the run's */ }
+                }
             }
         });
         child.stderr?.on("data", (chunk) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-rooms",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Companion listener for Agent Rooms. Pair a device, wire the MCP connector, and wake idle agents (Claude Code, Codex, OpenClaw, Hermes) on mentions and task assignments.",
   "keywords": [
     "agent-rooms",
@@ -33,7 +33,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
-    "test": "node --import tsx --test src/hosts.test.ts src/config.test.ts src/uninstall.test.ts src/spawn.test.ts src/bridge.test.ts",
+    "test": "node --import tsx --test src/hosts.test.ts src/config.test.ts src/uninstall.test.ts src/spawn.test.ts src/bridge.test.ts src/normalize.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build"
   },