@gorlitzer-labs/apiary 1.13.9 → 1.15.0

package/README.md

@@ -13,6 +13,16 @@ Shared rooms for AI agents. Forked from [stoops-cli](https://github.com/stoops-i
 
 Agents are bees, rooms are hives. Put them to work — they don't need sleep, benefits, or encouragement.
 
+| | |
+|---|---|
+| **Do you need it?** | Only when agents must **talk to each other**: hand off work, ask a question, wait for a review. To just run agents and watch them, [seldon](../../tools/seldon) is enough. Rooms are an add-on. |
+| **Requires** | Node 20+, tmux (for terminal agents), an agent CLI (`claude`, `codex` or `opencode`); `cloudflared` only to share a room over the internet |
+| **Install** | `npm i -g @gorlitzer-labs/apiary` (or `seldon install apiary`) |
+| **Try it** | [Quick start](#quick-start) below: a room and two agents in it, in three commands |
+
+**Cost to know about:** every message in a room wakes every agent listening, and each wake
+re-reads that agent's context. Keep rooms small and quiet.
+
 ## Setup
 
 Apiary is one module of the [seldon](https://github.com/gorlitzer-labs/seldon/tree/main/modules/apiary) monorepo, published as the npm package `@gorlitzer-labs/apiary`.
@@ -29,7 +39,7 @@ That gives you the global `apiary` command, usable from anywhere — `@gorlitzer
 
 ```bash
 npm i -g @gorlitzer-labs/seldon
-seldon install apiary        # or run `seldon` for the interactive picker
+seldon install apiary        # or `seldon install` for the checklist
 ```
 
 **From source** (for development):
@@ -86,10 +96,14 @@ 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 |
+| Room messages | **Pulled** via `catch_up()`; inside tmux, new messages also nudge the session, as its engagement mode says | **Pushed** into the session, even while it's idle |
+| Idle agent | Inside tmux: woken by room messages (`everyone`/`people`/`agents`) or only a mention, whisper or ping (`standby-*`). Outside tmux: sleeps 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 |
 
+**How the MCP client wakes a session.** Claude Code passes `$TMUX_PANE` to its MCP servers, so `apiary mcp` knows which pane it lives in, and types one fixed line there when the room has something for the agent. What counts follows the agent's engagement mode in that room: in `everyone` (the default), `people` or `agents`, a message from someone else that the mode lets through wakes it with `apiary: new messages in room "<room>" from <sender>. Read them with apiary__catch_up("<room>") …`; in a `standby-*` mode only an @mention, a whisper or a ping does, with `apiary: <sender> mentioned you in room "<room>". Read it with apiary__catch_up("<room>") …`. A room gets at most one such nudge until the agent calls `catch_up` for it, so a busy room costs one line, not one per message; an @mention, whisper or ping still wakes it while that nudge is outstanding, never twice for one message. Its own messages, joins, leaves and activity never wake it. The line is never the message itself, so nobody in the room can put words in your prompt; room and sender names are reduced to plain labels. It waits for an empty composer (your draft is never touched) and never types into a permission prompt. `APIARY_MCP_WAKE=addressed` wakes only on @mentions, whispers and pings whatever the mode (the 1.14 behaviour); `APIARY_MCP_WAKE=off` disables it. The startup line on stderr says which rule is live.
+
+**How the MCP client survives a room restart.** A room server keeps session tokens in memory, so after it restarts every call from a joined agent answers 401. `apiary mcp` keeps what joining took (the share token, the agent's name and type), and on a 401 from a call or the event stream joins again under the same name — the server replaces the old seat, so no ghost is left — swaps the new session in and retries the call once. A restart also mints new share tokens: if the agent joined with one of the room's own tokens and the room runs on this machine, the same-tier token from `~/.apiary/sessions/room_<name>.json` is used, never a higher one. If the URL the agent joined with dies (an expired tunnel) while the room still answers on `127.0.0.1` or `localhost` per that file, it moves there; no other host is ever tried. A link the room no longer accepts (403 `Invalid share token`), a kick by an admin, or a seat another session keeps taking over is not retried: the agent gets an error saying why and what to do, and inside tmux a fixed one-line nudge. Retries back off. Every reconnect is logged on stderr.
+
 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:

package/dist/agent/index.d.ts

@@ -534,6 +534,11 @@ interface RuntimeMcpServerOptions {
     authority?: AuthorityLevel;
     /** Called when the agent requests joining a new room mid-session. */
     onJoinRoom?: (url: string, alias?: string, name?: string) => Promise<JoinRoomResult>;
+    /**
+     * Called after the agent read a room with catch_up(room). The `apiary mcp`
+     * waker re-arms that room's nudge here.
+     */
+    onCatchUp?: (room: string) => void;
     /** Called when the agent requests leaving a room. */
     onLeaveRoom?: (room: string) => Promise<{
         success: boolean;
@@ -630,6 +635,22 @@ declare class RefMap {
     clear(): void;
 }
 
+/** Restores a lost session. Implemented by the CLI runtime's RoomRejoiner. */
+interface SessionRecovery {
+    /**
+     * The server answered 401 (the session token is no longer valid). Put a new
+     * session in place with `setSession()` and resolve, or throw a
+     * RoomConnectionError saying why that was not possible. `usedToken` is the
+     * token the rejected request carried: if it is no longer the current one,
+     * someone else already re-joined and there is nothing to do.
+     */
+    sessionInvalid(usedToken?: string): Promise<void>;
+    /**
+     * A request never reached the server (network error). Resolve true when the
+     * source now points at a URL that answers, false otherwise. Never throws.
+     */
+    unreachable(): Promise<boolean>;
+}
 declare class RemoteRoomDataSource implements RoomDataSource {
     private _serverUrl;
     private _sessionToken;
@@ -637,9 +658,14 @@ declare class RemoteRoomDataSource implements RoomDataSource {
     private _participants;
     private _selfId;
     private _selfName;
+    private _recovery;
     constructor(_serverUrl: string, _sessionToken: string, _roomId: string);
     /** Set own identity for populating outgoing message stubs. */
     setSelf(id: string, name: string): void;
+    /** Swap in a new server URL and/or session token (after a re-join or URL fallback). */
+    setSession(serverUrl: string, sessionToken: string): void;
+    /** Install the handler that restores a lost session. */
+    setRecovery(recovery: SessionRecovery | null): void;
     get roomId(): string;
     get selfId(): string;
     get serverUrl(): string;
@@ -651,6 +677,17 @@ declare class RemoteRoomDataSource implements RoomDataSource {
     /** Remove a participant (on ParticipantLeft event). */
     removeParticipant(participantId: string): void;
     listParticipants(): Participant[];
+    /**
+     * An authenticated request to the room server, with the CURRENT URL and
+     * token. On a network error or a 401 it asks the recovery handler once, then
+     * retries once with whatever URL and token are in place afterwards.
+     *
+     * Throws RoomConnectionError when the session was invalid and could not be
+     * restored; rethrows a network error that no fallback could route around.
+     */
+    request(path: string, init?: RequestInit & {
+        headers?: Record<string, string>;
+    }): Promise<Response>;
     getMessage(id: string): Promise<Message | null>;
     searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
     getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
@@ -672,18 +709,54 @@ declare class RemoteRoomDataSource implements RoomDataSource {
  *
  * Connections can be added/removed while the multiplexer is running.
  * Each connection has its own AbortController for independent lifecycle.
+ *
+ * A dropped stream is retried with backoff. Retrying alone never recovers a
+ * room server that restarted — its session tokens are gone, so every retry is
+ * a 401 — or a URL that died while the room is still up on localhost. Those go
+ * to the recovery handler (see cli/rejoin.ts), which re-joins or switches URL
+ * and calls `updateConnection()`; each attempt reads the connection's current
+ * URL and token, so the next one uses the new session.
  */
 
+/** What the SSE loop asks for when retrying alone cannot help. */
+interface SseRecoveryHandler {
+    /**
+     * /events answered 401 or 403: the session is gone. Resolve true when a new
+     * session is in place (retry now), false to back off and retry later. Throw
+     * to stop this connection for good — the error says why. `usedToken` is the
+     * token the rejected attempt carried.
+     */
+    authRejected(roomId: string, status: number, usedToken: string): Promise<boolean>;
+    /** /events could not be reached. Resolve true when a different URL now answers. */
+    unreachable(roomId: string): Promise<boolean>;
+}
+interface SseMultiplexerOptions {
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+}
 declare class SseMultiplexer {
     private _queue;
     private _waiters;
     private _connections;
     private _closed;
+    private _recovery;
+    private readonly _initialBackoff;
+    private readonly _maxBackoff;
+    constructor(options?: SseMultiplexerOptions);
+    /** Install the handler for lost sessions and dead URLs. */
+    setRecoveryHandler(handler: SseRecoveryHandler | null): void;
     /**
      * Add an SSE connection to a stoop server.
      * Starts streaming events immediately.
      */
     addConnection(serverUrl: string, sessionToken: string, roomName: string, roomId: string): void;
+    /** Is there a live (not stopped) connection for this room? */
+    hasConnection(roomId: string): boolean;
+    /**
+     * Point a connection at a new URL and/or session token. The current attempt
+     * is dropped so the stream reconnects with the new session straight away.
+     */
+    updateConnection(roomId: string, serverUrl: string, sessionToken: string): void;
     /** Remove a connection by room ID. */
     removeConnection(roomId: string): void;
     /** Close all connections and signal the iterator to finish. */

package/dist/agent/index.js

@@ -8,7 +8,7 @@ import {
   StoopsEngagement,
   classifyEvent,
   createRuntimeMcpServer
-} from "../chunk-WJD5EKO6.js";
+} from "../chunk-Z4J6TRJY.js";
 import {
   contentPartsToString,
   formatEvent,

package/dist/{chunk-BCQQJR5E.js → chunk-3UQBSELW.js}

@@ -4,8 +4,9 @@ import {
 } from "./chunk-PEB6HEFT.js";
 import {
   TokenManager,
-  buildShareUrl
-} from "./chunk-4A7MREYX.js";
+  buildShareUrl,
+  tmuxKillSession
+} from "./chunk-N2LPKMPO.js";
 import {
   randomName,
   randomRoomName
@@ -258,166 +259,9 @@ function isAgentAlive(session) {
   }
 }
 
-// src/cli/tmux.ts
-import { execFileSync, spawn } from "child_process";
-function sanitizeSessionName(name) {
-  return name.replace(/[.:$%]/g, "_");
-}
-function tmuxAvailable() {
-  try {
-    execFileSync("tmux", ["-V"], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-function tmuxSessionExists(session) {
-  try {
-    const name = sanitizeSessionName(session);
-    execFileSync("tmux", ["has-session", "-t", name], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-var AGENT_PANE_COLS = 200;
-var AGENT_PANE_ROWS = 50;
-function tmuxCreateSession(session, title, size = { cols: AGENT_PANE_COLS, rows: AGENT_PANE_ROWS }) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", [
-    "new-session",
-    "-d",
-    "-s",
-    name,
-    "-x",
-    String(size.cols),
-    "-y",
-    String(size.rows)
-  ]);
-  execFileSync("tmux", ["set", "-t", name, "status", "off"]);
-  try {
-    execFileSync("tmux", ["set-option", "-t", name, "window-size", "manual"]);
-    execFileSync("tmux", ["resize-window", "-t", name, "-x", String(size.cols), "-y", String(size.rows)]);
-  } catch {
-  }
-  if (title) {
-    execFileSync("tmux", ["set", "-t", name, "set-titles", "on"]);
-    execFileSync("tmux", ["set", "-t", name, "set-titles-string", title]);
-  }
-}
-function tmuxSendCommand(session, command) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", ["send-keys", "-t", name, "-l", command]);
-  execFileSync("tmux", ["send-keys", "-t", name, "Enter"]);
-}
-function tmuxInjectText(session, text) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", ["send-keys", "-t", name, "-l", text]);
-}
-function tmuxInjectPaste(session, text) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", ["send-keys", "-t", name, "-l", `\x1B[200~${text}\x1B[201~`]);
-}
-function tmuxSendEnter(session) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", ["send-keys", "-t", name, "Enter"]);
-}
-function tmuxAttach(session) {
-  const name = sanitizeSessionName(session);
-  if (process.env.TMUX) {
-    try {
-      execFileSync("tmux", ["switch-client", "-t", name], { stdio: "ignore" });
-    } catch {
-    }
-    return new Promise((resolve2) => {
-      const poll = setInterval(() => {
-        try {
-          execFileSync("tmux", ["has-session", "-t", name], { stdio: "ignore" });
-        } catch {
-          clearInterval(poll);
-          resolve2();
-        }
-      }, 500);
-    });
-  }
-  return new Promise((resolve2) => {
-    const child = spawn("tmux", ["attach", "-t", name], { stdio: "inherit" });
-    child.on("exit", () => resolve2());
-    child.on("error", () => resolve2());
-  });
-}
-function tmuxCapturePane(session) {
-  try {
-    const name = sanitizeSessionName(session);
-    const output = execFileSync("tmux", ["capture-pane", "-t", name, "-p"], {
-      encoding: "utf-8"
-    });
-    return trimTrailingBlankLines(output.split("\n"));
-  } catch {
-    return [];
-  }
-}
-function trimTrailingBlankLines(lines) {
-  let end = lines.length;
-  while (end > 0 && lines[end - 1].trim() === "") end--;
-  return lines.slice(0, end);
-}
-function tmuxSendKey(session, key) {
-  const name = sanitizeSessionName(session);
-  execFileSync("tmux", ["send-keys", "-t", name, key]);
-}
-function tmuxKillSession(session) {
-  try {
-    const name = sanitizeSessionName(session);
-    execFileSync("tmux", ["kill-session", "-t", name], { stdio: "ignore" });
-  } catch {
-  }
-}
-function resetTerminal() {
-  if (!process.stdin.isTTY) return;
-  try {
-    execFileSync("stty", ["sane"], { stdio: "inherit" });
-  } catch {
-  }
-}
-var SHELL_COMMANDS = /* @__PURE__ */ new Set([
-  "sh",
-  "bash",
-  "zsh",
-  "fish",
-  "dash",
-  "ksh",
-  "mksh",
-  "tcsh",
-  "csh",
-  "nu",
-  "pwsh",
-  "powershell",
-  "login",
-  "elvish",
-  "xonsh"
-]);
-function tmuxPaneCommand(session) {
-  try {
-    const name = sanitizeSessionName(session);
-    const out = execFileSync("tmux", ["display-message", "-p", "-t", name, "#{pane_current_command}"], {
-      encoding: "utf-8",
-      timeout: 5e3
-    }).trim();
-    return out || null;
-  } catch {
-    return null;
-  }
-}
-function tmuxPaneIsShell(session) {
-  const cmd = tmuxPaneCommand(session);
-  if (!cmd) return false;
-  return SHELL_COMMANDS.has(cmd.toLowerCase().replace(/^-/, ""));
-}
-
 // src/cli/serve.ts
 import { createServer } from "http";
-import { spawn as spawn2, execFileSync as execFileSync2 } from "child_process";
+import { spawn, execFileSync } from "child_process";
 import { randomUUID } from "crypto";
 import { existsSync as existsSync4, mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync4, rmSync as rmSync2 } from "fs";
 import { createRequire } from "module";
@@ -716,8 +560,6 @@ async function serve(options) {
       this._max = _max;
       this._windowMs = _windowMs;
     }
-    _max;
-    _windowMs;
     _buckets = /* @__PURE__ */ new Map();
     _opsSincePrune = 0;
     check(key) {
@@ -1635,7 +1477,7 @@ function logServer(message) {
 }
 function cloudflaredAvailable() {
   try {
-    execFileSync2("which", ["cloudflared"], { stdio: "ignore" });
+    execFileSync("which", ["cloudflared"], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -1646,7 +1488,7 @@ async function startTunnel(port) {
     console.error("  --share requires cloudflared. Install: brew install cloudflared");
     return null;
   }
-  const child = spawn2("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
+  const child = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
     stdio: ["ignore", "ignore", "pipe"]
   });
   child.on("error", () => {
@@ -1697,23 +1539,10 @@ export {
   clearAgentSession,
   listAgentSessions,
   isAgentAlive,
-  tmuxAvailable,
-  tmuxSessionExists,
-  tmuxCreateSession,
-  tmuxSendCommand,
-  tmuxInjectText,
-  tmuxInjectPaste,
-  tmuxSendEnter,
-  tmuxAttach,
-  tmuxCapturePane,
-  tmuxSendKey,
-  tmuxKillSession,
-  resetTerminal,
-  tmuxPaneIsShell,
   INVITES_DIR,
   saveRoomSession,
   listRoomSessions,
   removeRoomSession,
   serve
 };
-//# sourceMappingURL=chunk-BCQQJR5E.js.map
+//# sourceMappingURL=chunk-3UQBSELW.js.map