@gorlitzer-labs/apiary 1.14.0 → 1.15.0

package/README.md

@@ -96,11 +96,13 @@ 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** via `catch_up()`; inside tmux, an @mention, whisper or ping also nudges the session | **Pushed** into the session, even while it's idle |
-| Idle agent | Inside tmux: woken by a mention, whisper or ping. Outside tmux: sleeps 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. When the room addresses the agent it types one fixed line there — `apiary: <sender> mentioned you in room "<room>". Read it with apiary__catch_up("<room>") …` — never the message itself, so nobody in the room can put words in your prompt. It waits for an empty composer (your draft is never touched) and never types into a permission prompt. `APIARY_MCP_WAKE=off` disables 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.
 

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-LOONM4G3.js → chunk-3UQBSELW.js}

@@ -560,8 +560,6 @@ async function serve(options) {
       this._max = _max;
       this._windowMs = _windowMs;
     }
-    _max;
-    _windowMs;
     _buckets = /* @__PURE__ */ new Map();
     _opsSincePrune = 0;
     check(key) {
@@ -1547,4 +1545,4 @@ export {
   removeRoomSession,
   serve
 };
-//# sourceMappingURL=chunk-LOONM4G3.js.map
+//# sourceMappingURL=chunk-3UQBSELW.js.map