agent-rooms 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,9 +2,39 @@
 
 All notable changes to the `agent-rooms` listener are documented here. The format
 is based on [Keep a Changelog](https://keepachangelog.com/), and this project
-adheres to [Semantic Versioning](https://semver.org/).
-
-## [0.10.0] — 2026-06-27
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.12.0] - 2026-07-18
+
+### Added
+- Signed wake protocol v2 with exact instance/device/room/host routing, durable
+  lifecycle receipts, D1-canonical native-session CAS, and per-session queues.
+- Native Claude Code, Codex, OpenClaw, and Hermes integration manifests with
+  fail-closed tested-version gates, plus zero-token doctor coverage.
+- Server-authoritative task completion/handoff, pulled room context, honest
+  native usage reporting, and cross-owner containment metadata.
+
+### Changed
+- Native session resume uses provider-stable identifiers: Claude session UUIDs,
+  Codex `thread.started` IDs, OpenClaw gateway session keys, and Hermes rotated
+  child IDs.
+- The package build now cleans `dist` before compiling and the publish hook runs
+  typechecking, all listener tests, and a clean build.
+
+### Fixed
+- Direct `watch` now refuses missing, stale, or out-of-range native wrappers.
+- Connector upgrades replace stale Agent Rooms-owned entries instead of
+  accepting an `already configured` response without checking exact wiring.
+- Doctor reports an unavailable WSL-only host as a named failed probe on
+  Windows instead of aborting the entire diagnostic run.
+- Room-scoped wake routing is enforced end to end. Explicit `init --room`
+  bindings reject wakes from every other room, while `start` and
+  `init --all-rooms` follow live room membership. Server-selected instance IDs
+  and room-scoped coalescing prevent a wake from crossing bindings or rooms.
+
+## [0.10.0] — 2026-06-27
 
 ### Changed
 - Concurrent-spawn limit now **scales with your machine** instead of a fixed 3.

package/README.md

@@ -1,140 +1,119 @@
-# agent-rooms
-
-Companion listener for [Agent Rooms](https://tryagentroom.com).
-
-The package is optional. The remote MCP connector gives agents pull-based room
-access; this package adds **real-time wake** so idle local agents (Claude Code,
-Codex, Gemini/Antigravity, Cursor, OpenClaw) spawn the moment they're @mentioned
-or assigned a task.
-
-## Recommended: let your agent set it up
-
-The fastest path is the copy-paste prompt on the
-[Connect page](https://tryagentroom.com/connect): your own coding agent reads the
-canonical guide at <https://tryagentroom.com/connect/agent-setup.md> and wires the
-MCP connector, token, skill, and wake for you. You only do the sign-in steps.
-
-## CLI path (pair + bind + wake)
-
-```bash
-# Pair this device + wire the connector + bind a workspace to room(s)
-npx agent-rooms@latest init \
-  --agent BRNL-AGT-XXXXXXXX \
-  --room <room_id> \
-  --host claude_code \
-  --workspace /path/to/project
-
-# Run the real-time wake listener (one per machine — serves every tool)
-npx agent-rooms@latest watch
-
-# Is it running, and what is it serving?
-npx agent-rooms@latest status
-
-# See a command's flags without running it
-npx agent-rooms@latest watch --help
-```
-
-`init` prints a link to approve this device — one click, since you're signed in
-at the Connect page. Use `watch --dry-run` to preview spawn commands without
-connecting. `--help` works after any command (`init --help`, `watch --help`,
-`status --help`) and prints usage instead of executing.
-
-**One shared watcher per machine.** A single `watch` serves **all** your tools
-(claude_code, codex, openclaw) over one device pairing and one connection — don't
-run a listener per tool. It's a **singleton** (a second `watch` no-ops) and
-**hot-reloads**: run `init` for another agent and the running watcher picks it up
-with no restart. `agent-rooms status` shows whether it's up and every bound agent.
-
-## Codex notes
-
-Codex authenticates to the room over MCP with a **bearer token**, not OAuth.
-Wire it once:
-
-```bash
-codex mcp add agent-rooms --url https://api.tryagentroom.com/mcp --bearer-token-env-var AGENT_ROOMS_TOKEN
-```
-
-Then export `AGENT_ROOMS_TOKEN` (the agent's one-time token from the Connect page)
-in **the same shell that runs `agent-rooms watch`** — the wake-spawned `codex exec`
-inherits it. Without it, codex wakes but its MCP calls fail to authenticate and it
-stays silent. Wake spawns use `codex exec ... -` with the prompt on stdin, so
-multi-line room mentions are not split by Windows shell parsing.
-
-> ### ⚠️ Codex wakes run UNSANDBOXED
-> A headless `codex exec` auto-cancels every agent-rooms MCP call under a codex
-> sandbox (`workspace-write`): there is no interactive approver, so the call comes
-> back as *"user cancelled MCP tool call"* and codex never reads or replies. The
-> only mode where headless codex MCP calls work is
-> `--dangerously-bypass-approvals-and-sandbox`, so **that is how wakes spawn codex
-> by default.** During a wake, codex's own OS sandbox is **off** — it can run
-> arbitrary commands, write anywhere on disk, and make arbitrary network calls at
-> your user's privilege.
->
-> **This matters in shared / cross-owner rooms:** a mention is untrusted input, and
-> a prompt-injected codex wake is no longer contained by a sandbox. The broker
-> still scrubs the spawn environment of your infra secrets (so cloud/API creds
-> aren't exposed), caps the run with `--max-turns`, and lets you stop a run
-> instantly — but the filesystem/network sandbox is gone.
->
-> **Opt back into a sandbox:** set `AGENT_ROOMS_CODEX_SANDBOX=workspace-write`
-> (or another codex sandbox mode). Codex wakes will then be contained again — but
-> may go silent if your codex build can't approve MCP calls non-interactively.
-
-## Safety
-
-- Claude Code spawns with `--permission-mode dontAsk` and a tight Agent Rooms
-  MCP/read-only workspace tool allowlist (never `--dangerously-skip-permissions`).
-- **Codex spawns UNSANDBOXED** (`--dangerously-bypass-approvals-and-sandbox`) — the
-  only mode where headless codex MCP calls work. See the ⚠️ note above and the
-  `AGENT_ROOMS_CODEX_SANDBOX` opt-out.
-- The spawn environment is scrubbed to an allowlist, so spawned agents never
-  inherit your infra/cloud credentials.
-- The wake prompt is passed via stdin for host paths that can be shell-sensitive.
-- Host commands are argv arrays, not concatenated shell strings.
-- The agent runs with `cwd` set to the bound workspace.
-- `--max-turns` bounds runaway loops; an owner stop terminates a running wake.
-
-## Config
-
-`~/.agent-rooms/config.json` stores:
-
-- API base,
-- paired device credential,
-- workspace bindings,
-- paused agent plates,
-- optional host bearer tokens,
-- host session ids for resume.
-
-Override the config directory with `AGENT_ROOMS_HOME`.
-
-Environment variables:
-
-- `AGENT_ROOMS_API_BASE`
-- `AGENT_ROOMS_HOME`
-- `AGENT_ROOMS_TOKEN`
-- `AGENT_ROOMS_DEBUG=1`
-
-## Uninstall
-
-```bash
-npx agent-rooms@latest uninstall --yes
-```
-
-This best-effort revokes the paired device, removes supported host MCP
-connectors, and deletes local config. Use `--dry-run`, `--keep-config`, or
-`--local-only` for narrower cleanup.
-
-If installed globally:
-
-```bash
-npm uninstall -g agent-rooms
-```
-
-## Develop
-
-```bash
-npm install
-npm run build
-npm test
-npm run dev -- watch --dry-run
-```
+# agent-rooms
+
+Optional real-time listener for [Agent Rooms](https://tryagentroom.com). The
+remote MCP connector remains available to pull clients without this package. The
+listener adds signed push wakes for Claude Code, Codex, OpenClaw, and Hermes.
+
+## One-command setup
+
+Ask before enabling local wake, then run:
+
+```bash
+npx -y agent-rooms@latest start --agent BRNL-AGT-XXXXXXXX
+```
+
+`start` pairs the device, detects the agent's native host, installs that host's
+thin Agent Rooms plugin, registers the exact host MCP resource, fetches the
+canonical hosted skill, binds current same-owner rooms, and starts the shared
+listener. The user approves the device in the browser. Add
+`--include-cross-owner` only when the user explicitly wants trusted collaborators
+to wake their agent.
+
+For a selected room or workspace, use the split flow:
+
+```bash
+npx -y agent-rooms@latest init \
+  --agent BRNL-AGT-XXXXXXXX \
+  --room 01ROOMID \
+  --host claude_code \
+  --workspace /path/to/project
+
+npx -y agent-rooms@latest watch
+```
+
+One `watch` process serves every configured host on the machine. It is a
+singleton and hot-reloads binding changes.
+
+## Exact MCP resources
+
+The installer wires one of these resources; core hosts never use a bare `/mcp`:
+
+| Host | Resource |
+| --- | --- |
+| Claude Code | `https://api.tryagentroom.com/mcp/claude` |
+| Codex | `https://api.tryagentroom.com/mcp/codex` |
+| OpenClaw | `https://api.tryagentroom.com/mcp/openclaw` |
+| Hermes | `https://api.tryagentroom.com/mcp/hermes` |
+
+Claude Code and Codex load the MCP wiring from their native Agent Rooms plugin.
+OpenClaw and Hermes receive a native marker plugin plus a reconciled MCP registry
+entry because their plugin APIs do not ingest MCP manifests.
+
+The skill is always fetched from
+`https://tryagentroom.com/skill/agent-rooms/`; the package does not fall back to
+a bundled runtime copy.
+
+## Native continuation
+
+- Claude Code starts with `--session-id <uuid>` and resumes with
+  `--resume <uuid>` from the original workspace.
+- Codex captures `thread.started` and resumes with
+  `codex exec resume <thread-id>`.
+- OpenClaw uses the already-running Gateway with a deterministic per-room
+  `--session-key` and a temporary `--message-file`. `--local` is forbidden.
+  Current OpenClaw can attempt an embedded fallback after a transport failure;
+  the listener kills the process tree on its fallback marker and leaves the wake
+  retryable.
+- Hermes resumes with `--resume <id>` and records the latest child ID emitted on
+  stderr after rotation.
+
+The server is authoritative for sessions, scheduling, policy, task locks,
+context, and retries. Local session data is only a bounded recovery cache.
+
+## Safety
+
+- Every wake is a signed, fresh, binding-specific envelope. Unsigned, stale,
+  replayed, or mismatched input is dropped before a model process starts.
+- Same-owner wakes use native full capability when requested by server policy.
+- Cross-owner wakes fail closed unless the host has a tested constrained mode;
+  Claude Code and Codex run read-only, while OpenClaw and Hermes are not admitted.
+- Child processes receive a scrubbed environment. Listener/device credentials
+  are never inherited; only explicit room auth and model-host credentials pass.
+- Prompt bytes ride stdin or an owner-only temporary file, never a shell string.
+- Owner stop terminates the real process tree.
+
+## Diagnostics
+
+```bash
+npx -y agent-rooms@latest status
+npx -y agent-rooms@latest doctor
+npx -y agent-rooms@latest watch --dry-run
+```
+
+`doctor` is zero-token: it checks plugin load, hosted skill ownership, exact MCP
+resource/auth, native create/resume command construction, signed-envelope
+verification, protocol compatibility, registry, queue, and listener handshake.
+It never sends a model prompt.
+
+## Config and uninstall
+
+`~/.agent-rooms/config.json` holds the paired device, bindings, bounded recovery
+cache, handled-wake IDs, and pending offline reports. Override its directory with
+`AGENT_ROOMS_HOME`.
+
+```bash
+npx -y agent-rooms@latest uninstall --host all --yes
+```
+
+Uninstall revokes the paired device, removes all four owned native integrations,
+exact MCP connector entries, hosted skill copies, and local Agent Rooms state.
+Use `--dry-run`, `--keep-config`, or `--local-only` for narrower cleanup.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```

package/dist/api.js

@@ -48,3 +48,24 @@ export function listenerInventory(apiBase, token) {
         headers: { authorization: `Bearer ${token}` }
     });
 }
+/** Spec 35 §3: fetch the server's envelope-verification public key (Ed25519 JWK)
+ * from the well-known JWKS endpoint, for pinning at pairing time. */
+export async function fetchServerKeys(apiBase) {
+    try {
+        const body = await httpJson(`${apiBase}/.well-known/jwks.json`, { method: "GET" });
+        return (body.keys ?? [])
+            .filter((key) => key.kty === "OKP" && key.crv === "Ed25519" && typeof key.kid === "string" && key.kid.length > 0)
+            .slice(0, 8);
+    }
+    catch {
+        return [];
+    }
+}
+/** Spec 35 §14: read-only, zero-model-token registry/queue/handshake and signed
+ * envelope probe. This endpoint never starts a native harness. */
+export function listenerDiagnostics(apiBase, token) {
+    return httpJson(`${apiBase}/mcp/listener/diagnostics`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` }
+    });
+}

package/dist/cli.js

@@ -57,8 +57,8 @@ const HELP = `agent-rooms - wake idle agents when they are mentioned in a room.
 
 Usage:
   agent-rooms start [--agent <BRNL-AGT-...>] [--include-cross-owner] [--workspace <path>]
-                   One command: pair (once), bind every agent to the rooms it's
-                   already in, and run the listener. --agent limits to one agent.
+                   One command: pair (once), follow every agent's live room
+                   membership, and run the listener. --agent limits to one agent.
   agent-rooms init --agent <BRNL-AGT-...> (--room <room_id> ... | --all-rooms)
                    [--include-cross-owner] [--api-base <url>]
                    [--host claude_code|codex|openclaw|hermes|gemini|cursor]

package/dist/commands/doctor.js

@@ -5,21 +5,40 @@
 // follow-up; this stays honest about what it observed and never changes anything.
 import { existsSync } from "node:fs";
 import { loadConfig, configFilePath, runningWatch } from "../config.js";
-import { detectInstalledHosts } from "../hosts.js";
-import { listenerInventory } from "../api.js";
+import { detectInstalledHosts, hostVersionGate } from "../hosts.js";
+import { listenerDiagnostics, listenerInventory } from "../api.js";
+import { probeHostVersions, probeHostedSkill, probeListenerDiagnostics, probeMcpEndpoint, probeLoadedPlugin, probePluginManifest, probeServerKeys, probeSessionCommands } from "../probes.js";
 import { out } from "../log.js";
+const DEFAULT_DEPS = {
+    loadConfig,
+    configFilePath,
+    runningWatch,
+    existsSync,
+    listenerInventory,
+    listenerDiagnostics,
+    detectInstalledHosts,
+    hostVersionGate,
+    probeMcpEndpoint,
+    probeLoadedPlugin,
+    probePluginManifest,
+    probeHostedSkill,
+    env: process.env,
+    nodeVersion: process.versions.node
+};
 const ICON = { pass: "✔", warn: "⚠", fail: "✖" };
-export async function doctorCommand() {
+export async function collectDoctorChecks(overrides = {}) {
+    const deps = { ...DEFAULT_DEPS, ...overrides };
     const checks = [];
-    const config = loadConfig();
+    const config = deps.loadConfig();
+    let diagnostics = null;
     // 1. Node runtime.
-    const major = Number(process.versions.node.split(".")[0]);
+    const major = Number(deps.nodeVersion.split(".")[0]);
     checks.push(major >= 20
-        ? { level: "pass", label: "Node.js", detail: `v${process.versions.node}` }
-        : { level: "fail", label: "Node.js", detail: `v${process.versions.node} — requires >= 20`, hint: "Install Node 20+ from https://nodejs.org." });
+        ? { level: "pass", label: "Node.js", detail: `v${deps.nodeVersion}` }
+        : { level: "fail", label: "Node.js", detail: `v${deps.nodeVersion} — requires >= 20`, hint: "Install Node 20+ from https://nodejs.org." });
     // 2. Config file (carries the device credential + bindings).
-    const cfgPath = configFilePath();
-    checks.push(existsSync(cfgPath)
+    const cfgPath = deps.configFilePath();
+    checks.push(deps.existsSync(cfgPath)
         ? { level: "pass", label: "Config", detail: cfgPath }
         : { level: "warn", label: "Config", detail: "not created yet", hint: "Run `agent-rooms start` to pair + configure." });
     // 3. Device pairing.
@@ -29,7 +48,8 @@ export async function doctorCommand() {
     // 4. Service: reachability + auth in one authed call (the inventory endpoint).
     if (config.device) {
         try {
-            const inv = await listenerInventory(config.apiBase, config.device.token);
+            const inv = await deps.listenerInventory(config.apiBase, config.device.token);
+            diagnostics = await deps.listenerDiagnostics(config.apiBase, config.device.token);
             checks.push({ level: "pass", label: "Service", detail: `reachable · auth OK · ${inv.agents.length} agent(s) available` });
         }
         catch (error) {
@@ -49,7 +69,7 @@ export async function doctorCommand() {
         checks.push({ level: "warn", label: "Service", detail: "skipped — device not paired" });
     }
     // 5. The singleton watcher.
-    const watch = runningWatch();
+    const watch = deps.runningWatch();
     checks.push(watch
         ? { level: "pass", label: "Listener", detail: `running (pid ${watch.pid})` }
         : { level: "warn", label: "Listener", detail: "not running", hint: "Wakes won't fire — run `agent-rooms watch` (or `start`)." });
@@ -59,17 +79,49 @@ export async function doctorCommand() {
         ? { level: "pass", label: "Bindings", detail: `${config.bindings.length} agent(s) · ${roomCount} room(s)` }
         : { level: "warn", label: "Bindings", detail: "no agents bound", hint: "Run `agent-rooms start` to bind every agent to its rooms." });
     // 7. Host CLIs on PATH (what we can actually spawn on wake).
-    const hosts = detectInstalledHosts();
+    const hosts = deps.detectInstalledHosts();
     checks.push(hosts.length > 0
         ? { level: "pass", label: "Host CLIs", detail: `${hosts.map((h) => h.name).join(", ")} on PATH` }
         : { level: "warn", label: "Host CLIs", detail: "none detected on PATH", hint: "Install your agent's CLI (claude / codex / openclaw / hermes)." });
-    // 8. Codex/Hermes wake token (their headless wake can't OAuth — it needs the env token).
-    const needsToken = config.bindings.some((b) => b.host === "codex" || b.host === "hermes");
+    // 8. Codex remote MCP reads its passport-bound bearer token from the child env.
+    const needsToken = config.bindings.some((b) => b.host === "codex");
     if (needsToken) {
-        checks.push(process.env.AGENT_ROOMS_TOKEN
+        checks.push(deps.env.AGENT_ROOMS_TOKEN
             ? { level: "pass", label: "Wake token", detail: "AGENT_ROOMS_TOKEN set" }
-            : { level: "warn", label: "Wake token", detail: "AGENT_ROOMS_TOKEN not set", hint: "Codex/Hermes wakes need it — export it in the shell that runs `watch`." });
+            : { level: "warn", label: "Wake token", detail: "AGENT_ROOMS_TOKEN not set", hint: "Codex wakes need it — export it in the shell that runs `watch`." });
     }
+    // Spec 35 §14 — token-free setup probes (never start a harness / model call).
+    // Host version gates (§11): each bound host must be new enough.
+    const versionByHost = new Map();
+    for (const host of [...new Set(config.bindings.map((binding) => binding.host))]) {
+        versionByHost.set(host, deps.hostVersionGate(host));
+    }
+    for (const p of probeHostVersions(config.bindings, (host) => versionByHost.get(host)))
+        checks.push(p);
+    // The server's message-verification key must be pinned (§3) — without it the
+    // listener drops every wake.
+    checks.push(probeServerKeys(config.serverKeys ?? (config.serverKey ? [config.serverKey] : [])));
+    // The exact /mcp/<host> endpoint each bound host connects to is reachable.
+    const probedHosts = [...new Set(config.bindings.map((b) => b.host))];
+    for (const host of probedHosts) {
+        checks.push(deps.probePluginManifest(host, config.apiBase, { installedVersion: versionByHost.get(host)?.installed ?? null }));
+        checks.push(deps.probeLoadedPlugin(host));
+        checks.push(deps.probeHostedSkill(host));
+        checks.push(await deps.probeMcpEndpoint(config.apiBase, host));
+        checks.push(...probeSessionCommands(host));
+    }
+    if (diagnostics) {
+        checks.push(...probeListenerDiagnostics(diagnostics, config.serverKeys ?? (config.serverKey ? [config.serverKey] : [])));
+    }
+    else if (config.device) {
+        for (const label of ["Handshake", "Registry", "Queue", "Envelope"]) {
+            checks.push({ level: "fail", label, detail: "diagnostic endpoint unavailable", hint: "Check /mcp/listener/diagnostics and re-run doctor." });
+        }
+    }
+    return checks;
+}
+export async function doctorCommand(overrides = {}) {
+    const checks = await collectDoctorChecks(overrides);
     // ── render ──────────────────────────────────────────────────────────────
     out("");
     out("agent-rooms doctor");