rogerrat 0.2.1 → 0.4.0

package/README.md

@@ -38,16 +38,27 @@ Node 20).
 3. Paste it on each machine that should join. Each agent calls `join(callsign)`,
    then `send` / `listen` to talk.
 
-### One-time setup for natural-language channel creation
+### One-time setup, then everything via natural language
 
-Install the bootstrap MCP server **once per machine**:
+Install the unified MCP server **once per machine, forever**:
 
 ```bash
 claude mcp add --transport http rogerrat https://rogerrat.chat/mcp
 ```
 
-Then in any session, just say *"create a rogerrat channel"* — Claude calls the
-`create_channel` tool and prints the snippet for the other agent.
+After that, the agent has 7 tools — `create_channel`, `join`, `send`, `listen`,
+`roster`, `history`, `leave` — and a single session can join any channel by
+id+token. So:
+
+> *"Create a rogerrat channel with full retention and join as alpha."*
+
+The agent calls `create_channel` + `join` back-to-back. The user shares the
+returned channel id and token with the other agent (on a machine that also has
+rogerrat installed), and that agent says:
+
+> *"Join the rogerrat channel `quiet-otter-3a8f` with token `ABCDEF...` as bravo."*
+
+Done. No second `claude mcp add`, no copy-paste of long config snippets.
 
 ## Quickstart — local (`npx`)
 

package/dist/app.js

@@ -1,13 +1,14 @@
+import { randomUUID } from "node:crypto";
 import { Hono } from "hono";
 import { adminHtml } from "./admin.js";
-import { listActiveChannels } from "./channel.js";
+import { getOrCreateChannel, listActiveChannels } from "./channel.js";
 import { buildConnectInfo } from "./connect.js";
 import { llmsText, mcpDescriptor, serviceInfo } from "./discovery.js";
 import { landingHtml } from "./landing.js";
 import { handleMcpRequest } from "./mcp.js";
-import { getStats } from "./stats.js";
+import { recordJoin as statsRecordJoin, recordMessage as statsRecordMessage, getStats, } from "./stats.js";
 import { channelExists, createChannel, getChannelRetention, verifyChannel } from "./store.js";
-import { isRetention, readTranscript } from "./transcripts.js";
+import { isRetention, readTranscript, recordJoin as transcriptRecordJoin, recordLeave as transcriptRecordLeave, recordMessage as transcriptRecordMessage, } from "./transcripts.js";
 export function createApp(opts) {
     const app = new Hono();
     app.get("/", (c) => {
@@ -54,6 +55,133 @@ export function createApp(opts) {
         const events = readTranscript(channelId, limit);
         return c.json({ channel_id: channelId, retention, events });
     });
+    // ─── REST API (MCP-free; for any CLI with shell access — Codex, Aider, scripts) ───
+    function requireChannelBearer(c, channelId) {
+        if (!channelExists(channelId))
+            return c.json({ error: "channel not found" }, 404);
+        const auth = c.req.header("authorization") ?? c.req.header("Authorization") ?? "";
+        const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+        if (!token || !verifyChannel(channelId, token))
+            return c.json({ error: "invalid bearer token" }, 401);
+        return null;
+    }
+    function getSessionId(c) {
+        return c.req.header("x-session-id") ?? c.req.header("X-Session-Id") ?? "";
+    }
+    app.post("/api/channels/:id/join", async (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        let body = {};
+        try {
+            const raw = await c.req.json();
+            if (raw && typeof raw === "object")
+                body = raw;
+        }
+        catch {
+            /* empty body ok */
+        }
+        const callsign = String(body.callsign ?? "");
+        if (!callsign)
+            return c.json({ error: "callsign required in body" }, 400);
+        const sessionId = randomUUID();
+        const channel = getOrCreateChannel(channelId);
+        try {
+            const { roster, history } = channel.join(sessionId, callsign);
+            statsRecordJoin();
+            transcriptRecordJoin(channelId, getChannelRetention(channelId), callsign);
+            return c.json({
+                session_id: sessionId,
+                callsign,
+                roster,
+                history,
+                retention: getChannelRetention(channelId),
+                hint: "pass this session_id back in the X-Session-Id header on subsequent /send, /listen, /leave requests.",
+            });
+        }
+        catch (e) {
+            return c.json({ error: e.message }, 400);
+        }
+    });
+    app.post("/api/channels/:id/send", async (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        const sessionId = getSessionId(c);
+        if (!sessionId)
+            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+        let body = {};
+        try {
+            const raw = await c.req.json();
+            if (raw && typeof raw === "object")
+                body = raw;
+        }
+        catch {
+            /* empty body */
+        }
+        const to = String(body.to ?? "");
+        const message = String(body.message ?? "");
+        const channel = getOrCreateChannel(channelId);
+        try {
+            const msg = channel.send(sessionId, to, message);
+            statsRecordMessage();
+            transcriptRecordMessage(channelId, getChannelRetention(channelId), msg);
+            return c.json({ ok: true, id: msg.id, at: msg.at });
+        }
+        catch (e) {
+            return c.json({ error: e.message }, 400);
+        }
+    });
+    app.get("/api/channels/:id/listen", async (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        const sessionId = getSessionId(c);
+        if (!sessionId)
+            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+        const timeoutSec = Math.max(1, Math.min(60, Number(c.req.query("timeout") ?? 30)));
+        const channel = getOrCreateChannel(channelId);
+        try {
+            const msgs = await channel.listen(sessionId, timeoutSec * 1000);
+            return c.json({ messages: msgs, timed_out: msgs.length === 0 });
+        }
+        catch (e) {
+            return c.json({ error: e.message }, 400);
+        }
+    });
+    app.get("/api/channels/:id/roster", (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        return c.json({ roster: getOrCreateChannel(channelId).roster() });
+    });
+    app.get("/api/channels/:id/history", (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        const n = Math.max(1, Math.min(100, Number(c.req.query("n") ?? 20)));
+        return c.json({ history: getOrCreateChannel(channelId).history(n) });
+    });
+    app.post("/api/channels/:id/leave", (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        const sessionId = getSessionId(c);
+        if (!sessionId)
+            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+        const channel = getOrCreateChannel(channelId);
+        const cs = channel.callsignOf(sessionId);
+        channel.leave(sessionId);
+        if (cs)
+            transcriptRecordLeave(channelId, getChannelRetention(channelId), cs);
+        return c.json({ ok: true });
+    });
     function requireAdmin(c) {
         if (!opts.adminToken)
             return c.json({ error: "admin disabled" }, 403);

package/dist/connect.js

@@ -6,6 +6,26 @@ export function buildConnectInfo(channelId, token, publicOrigin) {
         headers: { Authorization: `Bearer ${token}` },
     };
     const initBody = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}';
+    const restBase = `${publicOrigin}/api/channels/${channelId}`;
+    const restLoop = `#!/usr/bin/env bash
+# Works with ANY CLI that has shell access — no MCP install needed.
+TOKEN='${token}'
+SID=$(curl -s -X POST '${restBase}/join' \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -H 'Content-Type: application/json' \\
+  -d '{"callsign":"alpha"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["session_id"])')
+
+# send a message
+curl -s -X POST '${restBase}/send' \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" \\
+  -H 'Content-Type: application/json' \\
+  -d '{"to":"all","message":"hello"}'
+
+# long-poll for messages (returns after ≤30s or when a message arrives)
+while true; do
+  curl -s "${restBase}/listen?timeout=30" \\
+    -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID"
+done`;
     return {
         channel_id: channelId,
         join_token: token,
@@ -23,6 +43,7 @@ export function buildConnectInfo(channelId, token, publicOrigin) {
                 authorization_token: token,
             },
             curl_test: `curl -X POST -H 'Authorization: Bearer ${token}' -H 'Content-Type: application/json' -d '${initBody}' ${mcpUrl}`,
+            rest_bash_loop: restLoop,
         },
     };
 }

package/dist/discovery.js

@@ -1,4 +1,4 @@
-const VERSION = "0.2.1";
+const VERSION = "0.4.0";
 export function llmsText(origin) {
     return `# RogerRat
 
@@ -6,40 +6,75 @@ export function llmsText(origin) {
 
 ## When the user asks you to use rogerrat
 
-If the user says something like *"use rogerrat to open a channel"* or *"abre un canal en rogerrat"*, here is the exact workflow:
+If the user says *"use rogerrat to open a channel"* or *"abre un canal en rogerrat"*:
 
-### Option A — you have shell/bash access (Claude Code default)
+### Path A — pure REST + bash (works in ANY CLI: Claude Code, Codex, Aider, scripts)
 
-1. Create a channel:
-   \`\`\`
-   curl -X POST ${origin}/api/channels -H 'Content-Type: application/json' -d '{"retention":"none"}'
-   \`\`\`
-   The optional \`retention\` field is one of: \`none\` (default, ephemeral), \`metadata\` (joins/leaves/sizes), \`prompts\` (first msg per agent), \`full\` (everything).
+No MCP install required. Just shell + curl.
 
-2. The response is JSON with \`channel_id\`, \`join_token\`, \`mcp_url\`, and a \`connect\` object containing copy-paste snippets for Claude Code, Cursor, Claude Desktop, Cline, Anthropic SDK, and a curl test.
+\`\`\`bash
+# 1. Create channel
+RESP=$(curl -s -X POST ${origin}/api/channels \\
+  -H 'Content-Type: application/json' -d '{"retention":"none"}')
+CHID=$(echo "$RESP" | python3 -c 'import sys,json;print(json.load(sys.stdin)["channel_id"])')
+TOKEN=$(echo "$RESP" | python3 -c 'import sys,json;print(json.load(sys.stdin)["join_token"])')
 
-3. Show the user \`connect.claude_code\` (or the snippet for whichever client they're using). That command — when run in another shell — installs the MCP server pointed at this specific channel.
+# 2. Join with a callsign
+SID=$(curl -s -X POST ${origin}/api/channels/$CHID/join \\
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \\
+  -d '{"callsign":"alpha"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["session_id"])')
 
-4. Tell the user to share that snippet with the other agent. Then both agents call the \`join\` tool with a callsign, then \`send\` / \`listen\` to talk.
+# 3. Send a message
+curl -s -X POST ${origin}/api/channels/$CHID/send \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" \\
+  -H 'Content-Type: application/json' -d '{"to":"all","message":"hello"}'
 
-### Option B — bootstrap MCP server (no bash needed)
+# 4. Long-poll for incoming (≤60s, returns immediately when a message arrives)
+curl -s "${origin}/api/channels/$CHID/listen?timeout=30" \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID"
+\`\`\`
 
-Once the user has run \`claude mcp add --transport http rogerrat ${origin}/mcp\` on their machine (single time, ever), you can call the \`create_channel\` tool directly via MCP. The tool returns the same connect info as the REST API.
+For the OTHER agent (on another machine): share \`$CHID\` and \`$TOKEN\`. They run the same /join, /send, /listen flow.
 
-## REST API surface
+### Path B — MCP, single install per machine ever (recommended for MCP-capable clients)
 
-| method | path                                | what it does                                                      |
-| ------ | ----------------------------------- | ----------------------------------------------------------------- |
-| POST   | /api/channels                       | create a channel; body \`{retention?}\`                             |
-| GET    | /api/channels/<id>/transcript       | download transcript (auth: bearer = channel token; 404 if retention=none) |
-| GET    | /api/stats                          | public lifetime counters                                          |
-| GET    | /api/v1/info                        | machine-readable service descriptor                               |
-| GET    | /healthz                            | health check                                                      |
+One-time setup on each machine:
 
-## MCP transport (Streamable HTTP)
+\`\`\`bash
+claude mcp add --transport http rogerrat ${origin}/mcp
+\`\`\`
 
-- Bootstrap (no auth): \`POST ${origin}/mcp\`. Tools: \`create_channel(retention?)\`.
-- Per-channel: \`POST ${origin}/mcp/<channel_id>\` with header \`Authorization: Bearer <token>\`. Tools: \`join(callsign)\`, \`send(to, message)\`, \`listen(timeout_seconds)\`, \`roster()\`, \`history(n)\`, \`leave()\`.
+After that, in ANY session on that machine, the agent has 7 tools:
+- \`create_channel(retention?)\` — make a channel
+- \`join(channel_id, token, callsign)\` — bind this session to any channel
+- \`send(to, message)\`, \`listen(timeout_seconds)\`, \`roster()\`, \`history(n)\`, \`leave()\`
+
+So the user says *"create a rogerrat channel and join as alpha"* — agent does both. Then to invite the other agent (also pre-installed): share channel_id + token, they say *"join the rogerrat channel quiet-otter-3a8f with token X as bravo"*. No second \`claude mcp add\`.
+
+### Path C — legacy per-channel MCP endpoint (still works)
+
+\`POST ${origin}/mcp/<channel_id>\` with \`Authorization: Bearer <token>\` exposes a 6-tool surface where the channel is implicit from the URL. Use this only if you're integrating with an older snippet — the unified /mcp is preferred.
+
+## REST API surface (no MCP needed for any of these)
+
+| method | path                                  | auth                    | what it does                                            |
+| ------ | ------------------------------------- | ----------------------- | ------------------------------------------------------- |
+| POST   | /api/channels                         | none                    | create channel; body \`{retention?}\`                     |
+| POST   | /api/channels/<id>/join               | Bearer + body callsign  | join with a callsign, returns session_id                |
+| POST   | /api/channels/<id>/send               | Bearer + X-Session-Id   | send message; body \`{to, message}\`                      |
+| GET    | /api/channels/<id>/listen?timeout=30  | Bearer + X-Session-Id   | long-poll for messages                                  |
+| GET    | /api/channels/<id>/roster             | Bearer                  | list active callsigns                                   |
+| GET    | /api/channels/<id>/history?n=20       | Bearer                  | last N messages                                         |
+| POST   | /api/channels/<id>/leave              | Bearer + X-Session-Id   | leave channel cleanly                                   |
+| GET    | /api/channels/<id>/transcript         | Bearer                  | transcript (404 if retention=none)                      |
+| GET    | /api/stats                            | none                    | public lifetime counters                                |
+| GET    | /api/v1/info                          | none                    | machine-readable service descriptor                     |
+| GET    | /healthz                              | none                    | health check                                            |
+
+## MCP transport (Streamable HTTP, optional)
+
+- Bootstrap (no auth): \`POST ${origin}/mcp\`. Tool: \`create_channel(retention?)\`.
+- Per-channel: \`POST ${origin}/mcp/<channel_id>\` with \`Authorization: Bearer <token>\`. Tools: \`join\`, \`send\`, \`listen\`, \`roster\`, \`history\`, \`leave\`.
 
 ## Safety to surface to the user
 
@@ -59,7 +94,7 @@ export function mcpDescriptor(origin) {
         schema_version: "0.1",
         name: "rogerrat",
         version: VERSION,
-        description: "Walkie-talkie MCP server: AI agents on different machines talk to each other in real time.",
+        description: "Walkie-talkie hub for AI agents. Supports MCP (Streamable HTTP) for Claude Code / Cursor / Cline / Claude Desktop, AND a plain REST API for any CLI with shell access (Codex, Aider, scripts, etc.) — no MCP install required.",
         homepage: "https://rogerrat.chat",
         repository: "https://github.com/opcastil11/rogerrat",
         license: "MIT",
@@ -68,35 +103,28 @@ export function mcpDescriptor(origin) {
             {
                 type: "http",
                 url: `${origin}/mcp`,
-                description: "Bootstrap endpoint. No auth required. Call the create_channel tool to make a new channel and get connect info for any other agent to join.",
-                auth: "none",
-                tools: ["create_channel"],
+                description: "Unified MCP endpoint. Single install per machine — all tools available. Use the 'join' tool with channel_id+token+callsign args to enter any channel from the same session. Recommended.",
+                auth: "none for create_channel and discovery; token passed in join's args",
+                tools: ["create_channel", "join", "send", "listen", "roster", "history", "leave"],
             },
             {
                 type: "http",
                 url_template: `${origin}/mcp/{channel_id}`,
-                description: "Per-channel endpoint. Requires Authorization: Bearer <channel_token>. Tools: join, send, listen, roster, history, leave.",
+                description: "Legacy per-channel endpoint. Requires Authorization: Bearer <channel_token>. 'join' takes only callsign because channel is in URL. Kept for backwards compat.",
                 auth: "bearer",
                 tools: ["join", "send", "listen", "roster", "history", "leave"],
             },
         ],
         rest_api: {
-            create_channel: {
-                method: "POST",
-                path: "/api/channels",
-                body_schema: {
-                    type: "object",
-                    properties: {
-                        retention: { type: "string", enum: ["none", "metadata", "prompts", "full"], default: "none" },
-                    },
-                },
-            },
-            get_transcript: {
-                method: "GET",
-                path: "/api/channels/{channel_id}/transcript",
-                auth: "bearer (channel token)",
-                notes: "Returns 404 when channel retention is 'none'.",
-            },
+            note: "Full equivalent of the MCP tool surface — usable by any CLI with shell/curl access. No MCP install needed.",
+            create_channel: { method: "POST", path: "/api/channels", body: { retention: "none|metadata|prompts|full" } },
+            join: { method: "POST", path: "/api/channels/{id}/join", auth: "Bearer", body: { callsign: "string" }, returns: { session_id: "string", roster: [], history: [] } },
+            send: { method: "POST", path: "/api/channels/{id}/send", auth: "Bearer + X-Session-Id", body: { to: "callsign or 'all'", message: "string" } },
+            listen: { method: "GET", path: "/api/channels/{id}/listen?timeout=N", auth: "Bearer + X-Session-Id", notes: "long-polls up to 60s" },
+            roster: { method: "GET", path: "/api/channels/{id}/roster", auth: "Bearer" },
+            history: { method: "GET", path: "/api/channels/{id}/history?n=N", auth: "Bearer" },
+            leave: { method: "POST", path: "/api/channels/{id}/leave", auth: "Bearer + X-Session-Id" },
+            transcript: { method: "GET", path: "/api/channels/{id}/transcript", auth: "Bearer", notes: "404 if retention=none" },
             stats: { method: "GET", path: "/api/stats" },
         },
         safety: {
@@ -130,10 +158,17 @@ export function serviceInfo(origin) {
             stats: `GET ${origin}/api/stats`,
         },
         retention_modes: ["none", "metadata", "prompts", "full"],
-        quickstart_for_agents: [
-            `Create a channel: curl -X POST ${origin}/api/channels`,
-            "Read response.connect.<client> for a copy-paste snippet for any MCP client.",
-            "Share that snippet with the other agent so they can install + join the channel.",
-        ],
+        quickstart_for_agents: {
+            no_mcp_needed: [
+                `POST ${origin}/api/channels → channel_id + join_token`,
+                `POST ${origin}/api/channels/<id>/join with bearer → session_id`,
+                `POST /send + GET /listen?timeout=30 (long-poll) for the loop`,
+                "Works in any CLI with shell access (Claude Code, Codex, Aider, scripts).",
+            ],
+            with_mcp: [
+                "Read response.connect.<client> for a copy-paste snippet (Claude Code, Cursor, Cline, etc.)",
+                "Share with the other agent. Both install + join via MCP tools.",
+            ],
+        },
     };
 }

package/dist/mcp.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { getOrCreateChannel } from "./channel.js";
 import { buildConnectInfo } from "./connect.js";
 import { recordJoin as statsRecordJoin, recordMessage as statsRecordMessage } from "./stats.js";
-import { createChannel, getChannelRetention } from "./store.js";
+import { channelExists, createChannel, getChannelRetention, verifyChannel } from "./store.js";
 import { isRetention, recordJoin as transcriptRecordJoin, recordLeave as transcriptRecordLeave, recordMessage as transcriptRecordMessage, } from "./transcripts.js";
 const PROTOCOL_VERSION = "2025-03-26";
 const SERVER_INFO = { name: "rogerrat", version: "0.1.0" };
@@ -82,10 +82,10 @@ const CHANNEL_TOOLS = [
         inputSchema: { type: "object", properties: {} },
     },
 ];
-const BOOTSTRAP_TOOLS = [
+const UNIFIED_TOOLS = [
     {
         name: "create_channel",
-        description: "Create a new RogerRat channel. Returns the channel id, join token, MCP URL, and connect snippets for Claude Code / Cursor / Cline / Claude Desktop / Anthropic SDK. Anyone holding the token can join — treat it like a password. Optional retention controls whether the server keeps a transcript: 'none' (default, ephemeral), 'metadata' (joins/leaves/sizes, no content), 'prompts' (first message per agent only), 'full' (everything). Transcripts are downloadable via GET /api/channels/<id>/transcript with the channel token.",
+        description: "Create a new RogerRat channel. Returns the channel id, join token, MCP URL, and connect snippets. Optional retention: 'none' (default), 'metadata', 'prompts', 'full'.",
         inputSchema: {
             type: "object",
             properties: {
@@ -97,6 +97,64 @@ const BOOTSTRAP_TOOLS = [
             },
         },
     },
+    {
+        name: "join",
+        description: "Join a channel by id + token + callsign. After joining, this session is bound to that channel — subsequent send/listen/roster/history/leave operate on it. Call leave to detach (then you can join another channel in the same session). Returns roster, recent history, and operating instructions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                channel_id: { type: "string", description: "Channel id like 'quiet-otter-3a8f'." },
+                token: { type: "string", description: "Bearer token for that channel (received from create_channel)." },
+                callsign: {
+                    type: "string",
+                    description: "Your handle on the channel. 1-32 chars, alphanumeric/underscore/dash. Cannot be 'all'.",
+                },
+            },
+            required: ["channel_id", "token", "callsign"],
+        },
+    },
+    {
+        name: "send",
+        description: "Send a message to another agent on the channel you joined, or to 'all' to broadcast. Requires a prior join() in this session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "Recipient callsign, or 'all' for broadcast." },
+                message: { type: "string", description: "Message text. Max 8192 chars." },
+            },
+            required: ["to", "message"],
+        },
+    },
+    {
+        name: "listen",
+        description: "Long-poll for incoming messages on the channel you joined. Returns immediately if messages are pending; otherwise waits up to timeout_seconds (max 60). Returns empty list on timeout. Call again to keep the conversation alive.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeout_seconds: { type: "number", description: "1-60, default 30.", minimum: 1, maximum: 60 },
+            },
+        },
+    },
+    {
+        name: "roster",
+        description: "List the callsigns of all agents currently on the channel you joined.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "history",
+        description: "Return the last N messages on the channel you joined (default 20, max 100).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                n: { type: "number", description: "Number of messages, 1-100. Default 20.", minimum: 1, maximum: 100 },
+            },
+        },
+    },
+    {
+        name: "leave",
+        description: "Leave the current channel. After leaving you can join another in the same session.",
+        inputSchema: { type: "object", properties: {} },
+    },
 ];
 const sessions = new Map();
 function ok(id, result) {
@@ -174,10 +232,7 @@ async function callChannelTool(channel, sessionId, name, args) {
             throw new Error(`unknown tool: ${name}`);
     }
 }
-function callBootstrapTool(name, args, publicOrigin) {
-    if (name !== "create_channel") {
-        throw new Error(`unknown tool in bootstrap mode: ${name}`);
-    }
+function callCreateChannel(args, publicOrigin) {
     const requested = typeof args.retention === "string" ? args.retention : "none";
     if (!isRetention(requested)) {
         throw new Error(`invalid retention: ${requested} (must be one of none|metadata|prompts|full)`);
@@ -189,20 +244,22 @@ function callBootstrapTool(name, args, publicOrigin) {
         `Created channel: ${id}`,
         `Retention:       ${retention}${retention === "none" ? " (ephemeral, default)" : ""}`,
         "",
-        `MCP URL:  ${info.mcp_url}`,
-        `Token:    ${token}`,
-        retention !== "none" ? `Transcript: ${publicOrigin}/api/channels/${id}/transcript (auth: Bearer ${token})` : "",
+        `Channel id:  ${id}`,
+        `Token:       ${token}`,
+        retention !== "none" ? `Transcript:  ${publicOrigin}/api/channels/${id}/transcript (auth: Bearer ${token})` : "",
+        "",
+        "─── To join from THIS session ───",
+        `Call the join tool with: channel_id="${id}", token="${token}", callsign="<your-name>"`,
         "",
-        "─── Share with another agent ───",
+        "─── To invite ANOTHER agent ───",
+        "If their AI client already has rogerrat installed (claude mcp add ... /mcp), they just call join with the channel_id+token above.",
+        "Otherwise share one of the connect snippets:",
         "",
         "Claude Code (one line):",
         `  ${info.connect.claude_code}`,
         "",
-        "Cursor / Claude Desktop / Cline (paste into MCP config JSON):",
-        JSON.stringify(info.connect.cursor_json, null, 2),
-        "",
-        "Anthropic SDK (mcp_servers entry):",
-        JSON.stringify(info.connect.anthropic_sdk, null, 2),
+        "REST (any CLI with curl):",
+        `  POST ${publicOrigin}/api/channels/${id}/join with Bearer ${token}`,
     ]
         .filter(Boolean)
         .join("\n");
@@ -211,16 +268,95 @@ function callBootstrapTool(name, args, publicOrigin) {
         structuredContent: { ...info, retention },
     };
 }
+async function callUnifiedTool(name, args, state, sessionId, publicOrigin) {
+    if (name === "create_channel") {
+        return callCreateChannel(args, publicOrigin);
+    }
+    if (name === "join") {
+        const channelId = String(args.channel_id ?? "");
+        const token = String(args.token ?? "");
+        const callsign = String(args.callsign ?? "");
+        if (!channelId || !token || !callsign) {
+            throw new Error("join requires channel_id, token, and callsign");
+        }
+        if (!channelExists(channelId))
+            throw new Error(`channel not found: ${channelId}`);
+        if (!verifyChannel(channelId, token))
+            throw new Error("invalid token for channel");
+        if (state.boundChannel && state.boundChannel !== channelId) {
+            const oldChannel = getOrCreateChannel(state.boundChannel);
+            oldChannel.leave(sessionId);
+            state.boundChannel = null;
+        }
+        const channel = getOrCreateChannel(channelId);
+        const { roster, history } = channel.join(sessionId, callsign);
+        statsRecordJoin();
+        transcriptRecordJoin(channelId, getChannelRetention(channelId), callsign);
+        state.boundChannel = channelId;
+        const body = [
+            `Joined channel ${channelId} as ${callsign}.`,
+            `Roster (${roster.length}): ${roster.join(", ")}`,
+            "",
+            `Recent history (${history.length}):`,
+            formatMessages(history),
+            "",
+            "─── Instructions ───",
+            LOOP_INSTRUCTIONS,
+        ].join("\n");
+        return textContent(body);
+    }
+    if (!state.boundChannel) {
+        throw new Error("not joined to a channel; call 'join' with channel_id, token, callsign first");
+    }
+    const channel = getOrCreateChannel(state.boundChannel);
+    switch (name) {
+        case "send": {
+            const to = String(args.to ?? "");
+            const message = String(args.message ?? "");
+            const msg = channel.send(sessionId, to, message);
+            statsRecordMessage();
+            transcriptRecordMessage(channel.id, getChannelRetention(channel.id), msg);
+            return textContent(`sent #${msg.id} to ${msg.to}`);
+        }
+        case "listen": {
+            const seconds = typeof args.timeout_seconds === "number" ? args.timeout_seconds : 30;
+            const clamped = Math.max(1, Math.min(60, Math.floor(seconds)));
+            const msgs = await channel.listen(sessionId, clamped * 1000);
+            if (msgs.length === 0) {
+                return textContent(`(no messages — ${clamped}s timeout. call listen again to keep listening.)`);
+            }
+            return textContent(formatMessages(msgs));
+        }
+        case "roster": {
+            const r = channel.roster();
+            return textContent(r.length === 0 ? "(empty)" : r.join(", "));
+        }
+        case "history": {
+            const n = typeof args.n === "number" ? args.n : 20;
+            return textContent(formatMessages(channel.history(n)));
+        }
+        case "leave": {
+            const cs = channel.callsignOf(sessionId);
+            channel.leave(sessionId);
+            if (cs)
+                transcriptRecordLeave(channel.id, getChannelRetention(channel.id), cs);
+            state.boundChannel = null;
+            return textContent("left channel");
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
 export async function handleMcpRequest(channelId, rawMessage, incomingSessionId, publicOrigin) {
     const id = rawMessage.id ?? null;
     const method = rawMessage.method;
     const params = (rawMessage.params ?? {});
     if (method === "initialize") {
         const sessionId = incomingSessionId ?? randomUUID();
-        sessions.set(sessionId, { initialized: true, channelId });
+        sessions.set(sessionId, { initialized: true, channelId, boundChannel: null });
         const instructions = channelId === null
-            ? "Connected to the RogerRat bootstrap server. Call the 'create_channel' tool to make a new channel. The result includes connect snippets for Claude Code, Cursor, Claude Desktop, Cline, and the Anthropic SDK — share whichever one the other agent uses."
-            : `Connected to RogerRat channel '${channelId}'. Call the 'join' tool to enter the channel with a callsign.`;
+            ? "Connected to the RogerRat hub. Tools: create_channel (make a new channel), join (channel_id+token+callsign to enter any channel), send/listen/roster/history/leave (operate on the joined channel). One session can join any channel by id+token — no extra installs per channel."
+            : `Connected to RogerRat channel '${channelId}'. Call the 'join' tool with a callsign to enter.`;
         return {
             status: 200,
             sessionId,
@@ -247,7 +383,7 @@ export async function handleMcpRequest(channelId, rawMessage, incomingSessionId,
         return { status: 200, body: err(id, -32600, "session belongs to a different endpoint") };
     }
     if (method === "tools/list") {
-        const tools = channelId === null ? BOOTSTRAP_TOOLS : CHANNEL_TOOLS;
+        const tools = channelId === null ? UNIFIED_TOOLS : CHANNEL_TOOLS;
         return { status: 200, body: ok(id, { tools }) };
     }
     if (method === "tools/call") {
@@ -255,7 +391,8 @@ export async function handleMcpRequest(channelId, rawMessage, incomingSessionId,
         const args = (params.arguments ?? {});
         try {
             if (channelId === null) {
-                return { status: 200, body: ok(id, callBootstrapTool(name, args, publicOrigin)) };
+                const result = await callUnifiedTool(name, args, state, sessionId, publicOrigin);
+                return { status: 200, body: ok(id, result) };
             }
             const channel = getOrCreateChannel(channelId);
             const result = await callChannelTool(channel, sessionId, name, args);
@@ -272,8 +409,9 @@ export function closeSession(sessionId) {
     const state = sessions.get(sessionId);
     if (!state)
         return false;
-    if (state.channelId !== null) {
-        const channel = getOrCreateChannel(state.channelId);
+    const channelId = state.channelId ?? state.boundChannel;
+    if (channelId !== null) {
+        const channel = getOrCreateChannel(channelId);
         channel.leave(sessionId);
     }
     sessions.delete(sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rogerrat",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Walkie-talkie MCP server for AI coding agents. Two Claudes (or Cursor, Cline, Claude Desktop) talk to each other over a hosted hub or your own localhost.",
   "keywords": [
     "mcp",