@gorlitzer-labs/apiary 1.13.7 → 1.13.8

package/README.md

@@ -55,7 +55,7 @@ Changed code? Just `make build` (or `npm run build`) — the `npm link` symlink
 
 ## Quick start
 
-**1. Add apiary to your MCP config** (`~/.claude/mcp.json` or project `.mcp.json`):
+**1. Add apiary to your MCP config** (`~/.claude.json` for every Claude Code session, or project `.mcp.json`):
 ```json
 {
   "mcpServers": {
@@ -68,6 +68,8 @@ Changed code? Just `make build` (or `npm run build`) — the `npm link` symlink
 }
 ```
 
+The name is optional — `["mcp"]` alone gives each session a random name, and the agent can pick its own with `join_room(url, name)`. Leave out `--admin` for agents that shouldn't kick, mute, or promote.
+
 **2. Start a room:**
 ```bash
 apiary room brood-box
@@ -75,6 +77,21 @@ apiary room brood-box
 
 **3. Paste the room URL to any agent.** It calls `join_room()` and participates. No tmux, no wrapper — just MCP tools.
 
+The room server still has to be running — `apiary mcp` is only a client. One `apiary room` / `apiary serve` per room, left up, and any number of MCP clients can drop in and out with the URL.
+
+### MCP client or tmux wrapper?
+
+Both put an agent in a room. They differ in who wakes it up:
+
+| | MCP client (`apiary mcp`) | tmux wrapper (`apiary claude` / `codex`) |
+|---|---|---|
+| Setup | Any session you already have — Claude Code, Cursor, Windsurf | Apiary launches the CLI in its own `apiary_<name>` tmux session |
+| Room messages | **Pulled** — seen only when the agent calls `catch_up()` | **Pushed** into the session, even while it's idle |
+| Idle agent | Sleeps at the prompt until you type | Woken by a mention or a message |
+| `apiary stop`, factory, supervisor | Not managed — just a participant | Tracked by pid; factory can staff it |
+
+Use the MCP client for agents **you're driving** — "join the room, post what you found, ask X" — and for adding agents on the fly. Use the wrapper for agents that must **run unattended**: a coordinator, workers, anything that should react while nobody is at the keyboard.
+
 **Remote?** If you use Tailscale (or any VPN), bind the room to it instead of opening a public tunnel:
 
 ```bash
@@ -155,21 +172,29 @@ The primary way to connect any MCP client (Claude Code, Cursor, Windsurf, etc.)
 
 **Per-project setup** — add to `.mcp.json` in the repo root instead if you only want it for specific projects.
 
-**Other MCP clients** (Cursor, Windsurf, etc.) — use `npx` if `apiary` isn't globally linked:
+**Other MCP clients** (Cursor, Windsurf, etc.) — Cursor reads `~/.cursor/mcp.json`. GUI apps launched from the Dock don't inherit your shell's PATH, so the `apiary` launcher can't find `node` — give it the absolute path and a PATH:
 
 ```json
 {
   "mcpServers": {
     "apiary": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["apiary", "mcp", "WorkerBee", "--admin"]
+      "command": "/Users/you/Library/pnpm/apiary",
+      "args": ["mcp"],
+      "env": { "PATH": "/Users/you/Library/pnpm:/opt/homebrew/bin:/usr/bin:/bin" }
     }
   }
 }
 ```
 
-Then tell the agent a room URL — it calls `join_room()` and participates. Events are pull-based via `catch_up()`. The EventProcessor runs in the background classifying and buffering events, the agent pulls them when ready.
+(`which apiary` and `which node` give you the two paths.) Without a global install, use `npx` — with the **scoped** name:
+
+```json
+"args": ["-y", "@gorlitzer-labs/apiary", "mcp"]
+```
+
+Never `npx apiary`: the unscoped `apiary` on npm is an unrelated third-party package, so that line downloads and runs someone else's code.
+
+Then tell the agent a room URL — it calls `join_room()` and participates. Events are pull-based via `catch_up()` (see [MCP client or tmux wrapper?](#mcp-client-or-tmux-wrapper)). The EventProcessor runs in the background classifying and buffering events, the agent pulls them when ready.
 
 #### A note on `--dangerously-skip-permissions`
 

package/dist/agent/index.js

@@ -8,13 +8,13 @@ import {
   StoopsEngagement,
   classifyEvent,
   createRuntimeMcpServer
-} from "../chunk-TISBXM4R.js";
+} from "../chunk-LN6ATWE3.js";
 import {
   contentPartsToString,
   formatEvent,
   messageRef,
   participantLabel
-} from "../chunk-TMXQDGMN.js";
+} from "../chunk-YP4K2A7G.js";
 import "../chunk-BZ4VDWC2.js";
 export {
   EventMultiplexer,

package/dist/{chunk-7JXPJO3R.js → chunk-3O76FESR.js}

@@ -10,16 +10,16 @@ import {
   tmuxInjectText,
   tmuxSendEnter,
   tmuxSessionExists
-} from "./chunk-BCQQJR5E.js";
+} from "./chunk-FTN3D6WM.js";
 import {
   extractToken
-} from "./chunk-4A7MREYX.js";
+} from "./chunk-63Q3KJ4W.js";
 import {
   randomName
 } from "./chunk-D7DXZQWT.js";
 import {
   can
-} from "./chunk-TMXQDGMN.js";
+} from "./chunk-YP4K2A7G.js";
 
 // src/cli/join.ts
 import { randomUUID } from "crypto";
@@ -2018,4 +2018,4 @@ export {
   HEADLESS_READY,
   join
 };
-//# sourceMappingURL=chunk-7JXPJO3R.js.map
+//# sourceMappingURL=chunk-3O76FESR.js.map

package/dist/{chunk-4A7MREYX.js → chunk-63Q3KJ4W.js}

@@ -1,6 +1,6 @@
 import {
   TIER_ORDER
-} from "./chunk-TMXQDGMN.js";
+} from "./chunk-YP4K2A7G.js";
 
 // src/cli/auth.ts
 import { randomBytes } from "crypto";
@@ -149,4 +149,4 @@ export {
   buildShareUrl,
   extractToken
 };
-//# sourceMappingURL=chunk-4A7MREYX.js.map
+//# sourceMappingURL=chunk-63Q3KJ4W.js.map

package/dist/{chunk-BCQQJR5E.js → chunk-FTN3D6WM.js}

@@ -5,7 +5,7 @@ import {
 import {
   TokenManager,
   buildShareUrl
-} from "./chunk-4A7MREYX.js";
+} from "./chunk-63Q3KJ4W.js";
 import {
   randomName,
   randomRoomName
@@ -13,7 +13,7 @@ import {
 import {
   can,
   formatTimestamp
-} from "./chunk-TMXQDGMN.js";
+} from "./chunk-YP4K2A7G.js";
 import {
   AttachmentSchema,
   createEvent
@@ -1716,4 +1716,4 @@ export {
   removeRoomSession,
   serve
 };
-//# sourceMappingURL=chunk-BCQQJR5E.js.map
+//# sourceMappingURL=chunk-FTN3D6WM.js.map

package/dist/{chunk-MEWZT5KA.js → chunk-J3T2PS3M.js}

@@ -1,6 +1,6 @@
 import {
   INVITES_DIR
-} from "./chunk-BCQQJR5E.js";
+} from "./chunk-FTN3D6WM.js";
 
 // src/cli/invites.ts
 import { existsSync, readFileSync, unlinkSync } from "fs";
@@ -92,4 +92,4 @@ export {
   invitePrompt,
   deliverInvite
 };
-//# sourceMappingURL=chunk-MEWZT5KA.js.map
+//# sourceMappingURL=chunk-J3T2PS3M.js.map

package/dist/{chunk-TISBXM4R.js → chunk-LN6ATWE3.js}

@@ -4,55 +4,125 @@ import {
   formatEvent,
   formatTimestamp,
   messageRef
-} from "./chunk-TMXQDGMN.js";
+} from "./chunk-YP4K2A7G.js";
 import {
   EVENT_ROLE,
   EventCategory,
   createEvent
 } from "./chunk-BZ4VDWC2.js";
 
-// src/agent/room-data-source.ts
-var LocalRoomDataSource = class {
-  constructor(_room, _channel) {
-    this._room = _room;
-    this._channel = _channel;
-  }
-  _room;
-  _channel;
-  get roomId() {
-    return this._room.roomId;
-  }
-  get selfId() {
-    return this._channel.participantId;
-  }
-  /** Direct access to the underlying Room (for backward compat / internal use). */
-  get room() {
-    return this._room;
-  }
-  /** Direct access to the underlying Channel (for backward compat / internal use). */
-  get channel() {
-    return this._channel;
-  }
-  listParticipants() {
-    return this._room.listParticipants();
-  }
-  async getMessage(id) {
-    return this._room.getMessage(id);
+// src/agent/sse-multiplexer.ts
+var SseMultiplexer = class {
+  _queue = [];
+  _waiters = [];
+  _connections = /* @__PURE__ */ new Map();
+  _closed = false;
+  /**
+   * Add an SSE connection to a stoop server.
+   * Starts streaming events immediately.
+   */
+  addConnection(serverUrl, sessionToken, roomName, roomId) {
+    if (this._connections.has(roomId) || this._closed) return;
+    const abortController = new AbortController();
+    const loopPromise = this._sseLoop(serverUrl, sessionToken, roomName, roomId, abortController.signal);
+    this._connections.set(roomId, { serverUrl, sessionToken, roomName, roomId, abortController, loopPromise });
   }
-  async searchMessages(query, limit = 10, cursor = null) {
-    return this._room.searchMessages(query, limit, cursor);
+  /** Remove a connection by room ID. */
+  removeConnection(roomId) {
+    const entry = this._connections.get(roomId);
+    if (!entry) return;
+    entry.abortController.abort();
+    this._connections.delete(roomId);
   }
-  async getMessages(limit = 30, cursor = null) {
-    return this._room.listMessages(limit, cursor);
+  /** Close all connections and signal the iterator to finish. */
+  close() {
+    this._closed = true;
+    for (const [, entry] of this._connections) {
+      entry.abortController.abort();
+    }
+    this._connections.clear();
+    for (const waiter of this._waiters) {
+      waiter.resolve(null);
+    }
+    this._waiters = [];
   }
-  async getEvents(category = null, limit = 50, cursor = null) {
-    return this._room.listEvents(category, limit, cursor);
+  async _sseLoop(serverUrl, sessionToken, roomName, roomId, signal) {
+    const INITIAL_BACKOFF = 1e3;
+    const MAX_BACKOFF = 3e4;
+    let backoff = INITIAL_BACKOFF;
+    while (!signal.aborted && !this._closed) {
+      try {
+        const res = await fetch(`${serverUrl}/events`, {
+          method: "POST",
+          headers: {
+            Accept: "text/event-stream",
+            Authorization: `Bearer ${sessionToken}`
+          },
+          signal
+        });
+        if (!res.ok || !res.body) {
+          throw new Error(`SSE connect failed: ${res.status}`);
+        }
+        backoff = INITIAL_BACKOFF;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (!signal.aborted) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const parts = buffer.split("\n\n");
+          buffer = parts.pop();
+          for (const part of parts) {
+            const dataLine = part.split("\n").find((l) => l.startsWith("data: "));
+            if (!dataLine) continue;
+            try {
+              const event = JSON.parse(dataLine.slice(6));
+              this._push({ roomId, roomName, event });
+            } catch {
+            }
+          }
+        }
+      } catch (err) {
+        if (signal.aborted) break;
+      }
+      if (!signal.aborted && !this._closed) {
+        await new Promise((r) => setTimeout(r, backoff));
+        backoff = Math.min(backoff * 2, MAX_BACKOFF);
+      }
+    }
   }
-  async sendMessage(content, replyToId, image, attachments, recipients) {
-    return this._channel.sendMessage(content, replyToId, image ?? void 0, attachments, recipients);
+  _push(labeled) {
+    if (this._closed) return;
+    if (this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      waiter.resolve(labeled);
+    } else {
+      this._queue.push(labeled);
+    }
   }
-  async emitEvent(event) {
-    await this._channel.emit(event);
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this._queue.length > 0) {
+          return Promise.resolve({ value: this._queue.shift(), done: false });
+        }
+        if (this._closed) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => {
+          this._waiters.push({
+            resolve: (value) => {
+              if (this._closed || value === null) {
+                resolve({ value: void 0, done: true });
+              } else {
+                resolve({ value, done: false });
+              }
+            }
+          });
+        });
+      }
+    };
   }
 };
 
@@ -138,6 +208,51 @@ function classifyEvent(event, mode, selfId, senderType, senderId) {
   return classify(event, mode, selfId, senderType, senderId);
 }
 
+// src/agent/room-data-source.ts
+var LocalRoomDataSource = class {
+  constructor(_room, _channel) {
+    this._room = _room;
+    this._channel = _channel;
+  }
+  _room;
+  _channel;
+  get roomId() {
+    return this._room.roomId;
+  }
+  get selfId() {
+    return this._channel.participantId;
+  }
+  /** Direct access to the underlying Room (for backward compat / internal use). */
+  get room() {
+    return this._room;
+  }
+  /** Direct access to the underlying Channel (for backward compat / internal use). */
+  get channel() {
+    return this._channel;
+  }
+  listParticipants() {
+    return this._room.listParticipants();
+  }
+  async getMessage(id) {
+    return this._room.getMessage(id);
+  }
+  async searchMessages(query, limit = 10, cursor = null) {
+    return this._room.searchMessages(query, limit, cursor);
+  }
+  async getMessages(limit = 30, cursor = null) {
+    return this._room.listMessages(limit, cursor);
+  }
+  async getEvents(category = null, limit = 50, cursor = null) {
+    return this._room.listEvents(category, limit, cursor);
+  }
+  async sendMessage(content, replyToId, image, attachments, recipients) {
+    return this._channel.sendMessage(content, replyToId, image ?? void 0, attachments, recipients);
+  }
+  async emitEvent(event) {
+    await this._channel.emit(event);
+  }
+};
+
 // src/agent/remote-room-data-source.ts
 var RemoteRoomDataSource = class {
   constructor(_serverUrl, _sessionToken, _roomId) {
@@ -1637,126 +1752,12 @@ async function createStdioRuntimeMcpServer(opts) {
   return { stop, closed };
 }
 
-// src/agent/sse-multiplexer.ts
-var SseMultiplexer = class {
-  _queue = [];
-  _waiters = [];
-  _connections = /* @__PURE__ */ new Map();
-  _closed = false;
-  /**
-   * Add an SSE connection to a stoop server.
-   * Starts streaming events immediately.
-   */
-  addConnection(serverUrl, sessionToken, roomName, roomId) {
-    if (this._connections.has(roomId) || this._closed) return;
-    const abortController = new AbortController();
-    const loopPromise = this._sseLoop(serverUrl, sessionToken, roomName, roomId, abortController.signal);
-    this._connections.set(roomId, { serverUrl, sessionToken, roomName, roomId, abortController, loopPromise });
-  }
-  /** Remove a connection by room ID. */
-  removeConnection(roomId) {
-    const entry = this._connections.get(roomId);
-    if (!entry) return;
-    entry.abortController.abort();
-    this._connections.delete(roomId);
-  }
-  /** Close all connections and signal the iterator to finish. */
-  close() {
-    this._closed = true;
-    for (const [, entry] of this._connections) {
-      entry.abortController.abort();
-    }
-    this._connections.clear();
-    for (const waiter of this._waiters) {
-      waiter.resolve(null);
-    }
-    this._waiters = [];
-  }
-  async _sseLoop(serverUrl, sessionToken, roomName, roomId, signal) {
-    const INITIAL_BACKOFF = 1e3;
-    const MAX_BACKOFF = 3e4;
-    let backoff = INITIAL_BACKOFF;
-    while (!signal.aborted && !this._closed) {
-      try {
-        const res = await fetch(`${serverUrl}/events`, {
-          method: "POST",
-          headers: {
-            Accept: "text/event-stream",
-            Authorization: `Bearer ${sessionToken}`
-          },
-          signal
-        });
-        if (!res.ok || !res.body) {
-          throw new Error(`SSE connect failed: ${res.status}`);
-        }
-        backoff = INITIAL_BACKOFF;
-        const reader = res.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        while (!signal.aborted) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          const parts = buffer.split("\n\n");
-          buffer = parts.pop();
-          for (const part of parts) {
-            const dataLine = part.split("\n").find((l) => l.startsWith("data: "));
-            if (!dataLine) continue;
-            try {
-              const event = JSON.parse(dataLine.slice(6));
-              this._push({ roomId, roomName, event });
-            } catch {
-            }
-          }
-        }
-      } catch (err) {
-        if (signal.aborted) break;
-      }
-      if (!signal.aborted && !this._closed) {
-        await new Promise((r) => setTimeout(r, backoff));
-        backoff = Math.min(backoff * 2, MAX_BACKOFF);
-      }
-    }
-  }
-  _push(labeled) {
-    if (this._closed) return;
-    if (this._waiters.length > 0) {
-      const waiter = this._waiters.shift();
-      waiter.resolve(labeled);
-    } else {
-      this._queue.push(labeled);
-    }
-  }
-  [Symbol.asyncIterator]() {
-    return {
-      next: () => {
-        if (this._queue.length > 0) {
-          return Promise.resolve({ value: this._queue.shift(), done: false });
-        }
-        if (this._closed) {
-          return Promise.resolve({ value: void 0, done: true });
-        }
-        return new Promise((resolve) => {
-          this._waiters.push({
-            resolve: (value) => {
-              if (this._closed || value === null) {
-                resolve({ value: void 0, done: true });
-              } else {
-                resolve({ value, done: false });
-              }
-            }
-          });
-        });
-      }
-    };
-  }
-};
-
 export {
-  LocalRoomDataSource,
+  SseMultiplexer,
   parseEngagementMode,
   StoopsEngagement,
   classifyEvent,
+  LocalRoomDataSource,
   RemoteRoomDataSource,
   buildCatchUpLines,
   EventMultiplexer,
@@ -1765,7 +1766,6 @@ export {
   EventProcessor,
   RUNTIME_TOOL_NAMES,
   createRuntimeMcpServer,
-  createStdioRuntimeMcpServer,
-  SseMultiplexer
+  createStdioRuntimeMcpServer
 };
-//# sourceMappingURL=chunk-TISBXM4R.js.map
+//# sourceMappingURL=chunk-LN6ATWE3.js.map