@nolag/agents 0.4.1 → 1.1.1

package/dist/index.mjs

@@ -1,5 +1,3 @@
-import { NoLag } from '@nolag/js-sdk';
-
 /**
  * Tiny typed event emitter — framework-agnostic base for NoLagAgents and AgentRoom.
  *
@@ -36,7 +34,19 @@ class EventEmitter {
             return;
         for (const handler of handlers) {
             try {
-                handler(...args);
+                // Async handlers don't throw — they return rejected promises, which
+                // the catch below never sees. Left unattached, one bad envelope from
+                // the wire becomes an unhandled rejection and (Node ≥15) TERMINATES
+                // THE HOST PROCESS. An event emitter fed by network input must never
+                // hand a remote peer that power, so rejections are contained here
+                // exactly like sync throws.
+                const result = handler(...args);
+                if (result &&
+                    typeof result.then === "function") {
+                    result.then(undefined, (e) => {
+                        console.error(`Error in async ${String(event)} handler:`, e);
+                    });
+                }
             }
             catch (e) {
                 console.error(`Error in ${String(event)} handler:`, e);
@@ -66,23 +76,31 @@ const TOPIC_TOOLS = "tools";
 const TOPIC_APPROVAL = "approval";
 /** Default room for agent coordination */
 const DEFAULT_ROOM = "default-workflow";
+/** Delay before the post-setup lobby presence refetch (catches simultaneous joiners) */
+const LOBBY_REFRESH_DELAY_MS = 2000;
 /** Agents-protocol version: 2 = directed replies (filter-routed results),
  *  NO_HANDLER NACKs, presence protocol advertisement. Absent/1 = legacy
  *  broadcast replies (pre-0.2.0 SDKs). */
 const AGENTS_PROTOCOL_VERSION = 2;
 
 /**
- * AgentRoom — wraps a RoomContext from @nolag/js-sdk.
+ * AgentRoom — a single agent-coordination room (scoped unit).
+ *
+ * Wraps a RoomContext from @nolag/js-sdk with typed pub/sub for agent
+ * coordination topics, presence-based service discovery, and capability
+ * routing.
  *
- * Provides typed pub/sub for agent coordination topics,
- * presence-based service discovery, and capability routing.
+ * Created via `NoLagAgents.room(name)`. Do not instantiate directly. Presence
+ * events are routed in by the parent NoLagAgents (which owns the shared
+ * client's connection-level presence handlers); the room only wires its own
+ * topic handlers on its RoomContext, and cleanup removes exactly those.
  *
  * @example
  * ```typescript
  * const room = agents.room('default-workflow');
  *
  * // Service discovery - see who's connected
- * const agents = room.getConnectedAgents();
+ * const connected = room.getConnectedAgents();
  * const summarizers = room.findAgents('summarize');
  *
  * // Capability-filtered task handler
@@ -90,28 +108,32 @@ const AGENTS_PROTOCOL_VERSION = 2;
  * ```
  */
 class AgentRoom extends EventEmitter {
-    constructor(name, roomContext, client, log, agentId, presence) {
+    /** @internal */
+    constructor(name, roomContext, log, agentId, appName, isConnected, presence) {
         super();
         /** Registry of connected agents discovered via presence */
         this._agents = new Map();
+        // Stored topic handler refs — cleanup removes exactly these, never all
+        // handlers for a topic (the client may be shared with other consumers).
+        this._topicHandlers = [];
         this.name = name;
         this.agentId = agentId;
         this._roomContext = roomContext;
-        this._client = client;
         this._log = log;
+        this._appName = appName;
+        this._isConnected = isConnected;
         this._presence = presence;
         this._wireTopicListeners();
-        this._wirePresenceListeners();
         // Set presence if provided (with the SDK's protocol version advertised
-        // so counterparts can detect incompatible reply semantics)
+        // so counterparts can detect incompatible reply semantics, and a __scope
+        // tag so co-attached wrappers on other apps filter our presence out).
         if (presence) {
-            const withProtocol = { protocol: AGENTS_PROTOCOL_VERSION, ...presence };
-            this._presence = withProtocol;
-            this._log(`setting presence in room ${name}:`, withProtocol);
-            this._roomContext.setPresence(withProtocol);
+            this._presence = { protocol: AGENTS_PROTOCOL_VERSION, ...presence };
+            this._log(`setting presence in room ${name}:`, this._presence);
+            this._roomContext.setPresence({ ...this._presence, __scope: appName });
         }
         // Fetch initial presence snapshot
-        this._fetchInitialPresence();
+        void this._fetchInitialPresence();
     }
     // ============================================================
     // SERVICE DISCOVERY
@@ -143,10 +165,9 @@ class AgentRoom extends EventEmitter {
     // ============================================================
     /** Update this agent's presence data (protocol version auto-injected) */
     setPresence(data) {
-        const withProtocol = { protocol: AGENTS_PROTOCOL_VERSION, ...data };
-        this._presence = withProtocol;
+        this._presence = { protocol: AGENTS_PROTOCOL_VERSION, ...data };
         this._log(`updating presence in room ${this.name}`);
-        this._roomContext.setPresence(withProtocol);
+        this._roomContext.setPresence({ ...this._presence, __scope: this._appName });
     }
     /** Fetch current presence snapshot for this room */
     async fetchPresence() {
@@ -158,24 +179,13 @@ class AgentRoom extends EventEmitter {
             return [];
         }
     }
-    /**
-     * @internal Emit a presence event (used by NoLagAgents for lobby forwarding)
-     */
-    _emitPresence(event, actorId, data) {
-        if (event === 'presenceLeave') {
-            this.emit('presenceLeave', actorId);
-        }
-        else {
-            this.emit(event, actorId, data || {});
-        }
-    }
-    // ============================================================
-    // PUBLISH (with automatic agentId injection)
-    // ============================================================
     /** Get the underlying RoomContext for advanced usage */
     get context() {
         return this._roomContext;
     }
+    // ============================================================
+    // PUBLISH (with automatic agentId injection)
+    // ============================================================
     /** Publish to the tasks topic */
     publishTask(envelope) {
         // Auto-set createdBy if not set
@@ -237,8 +247,82 @@ class AgentRoom extends EventEmitter {
         this._publish(TOPIC_APPROVAL, data, { retain: true });
     }
     // ============================================================
+    // INTERNAL (called by NoLagAgents)
+    // ============================================================
+    /** @internal Re-apply local presence after a reconnect (core does not restore it) */
+    _updateLocalPresence() {
+        if (this._presence) {
+            this._roomContext.setPresence({ ...this._presence, __scope: this._appName });
+        }
+    }
+    /** @internal Route a presence:join event in from the parent */
+    _handlePresenceJoin(actorId, data) {
+        const d = data || {};
+        const agent = {
+            actorId,
+            name: d.name || actorId,
+            role: d.role || "agent",
+            capabilities: d.capabilities || [],
+            metadata: d.metadata,
+            connectedAt: Date.now(),
+            protocol: typeof d.protocol === "number" ? d.protocol : 1,
+        };
+        this._agents.set(actorId, agent);
+        this._log(`agent joined room ${this.name}:`, agent.name, agent.capabilities);
+        this.emit("presenceJoin", actorId, d);
+    }
+    /** @internal Route a presence:leave event in from the parent */
+    _handlePresenceLeave(actorId) {
+        const agent = this._agents.get(actorId);
+        this._agents.delete(actorId);
+        this._log(`agent left room ${this.name}:`, agent?.name || actorId);
+        this.emit("presenceLeave", actorId);
+    }
+    /** @internal Route a presence:update event in from the parent */
+    _handlePresenceUpdate(actorId, data) {
+        const d = data || {};
+        const existing = this._agents.get(actorId);
+        const agent = {
+            actorId,
+            name: d.name || existing?.name || actorId,
+            role: d.role || existing?.role || "agent",
+            capabilities: d.capabilities || existing?.capabilities || [],
+            metadata: d.metadata || existing?.metadata,
+            connectedAt: existing?.connectedAt || Date.now(),
+            protocol: typeof d.protocol === "number" ? d.protocol : (existing?.protocol ?? 1),
+        };
+        this._agents.set(actorId, agent);
+        this.emit("presenceUpdate", actorId, d);
+    }
+    /**
+     * @internal Unsubscribe topics (when connected) and remove exactly this
+     * room's handler refs. Handler-specific removal only: the client may be
+     * shared, and a bare off(topic) would strip other consumers' handlers too.
+     */
+    _cleanup() {
+        this._log(`room cleanup: ${this.name}`);
+        // Server unsubscribes need a live socket; skip when disconnected
+        // (best-effort — the core would no-op with an error callback anyway).
+        if (this._isConnected()) {
+            const topics = new Set(this._topicHandlers.map((t) => t.topic));
+            for (const topic of topics) {
+                this._roomContext.unsubscribe(topic);
+            }
+        }
+        for (const { topic, handler } of this._topicHandlers) {
+            this._roomContext.off(topic, handler);
+        }
+        this._topicHandlers = [];
+        this._agents.clear();
+        this.removeAllListeners();
+    }
+    // ============================================================
     // INTERNALS
     // ============================================================
+    _on(topic, handler) {
+        this._topicHandlers.push({ topic, handler });
+        this._roomContext.on(topic, handler);
+    }
     _publish(topic, data, options) {
         this._log(`publish to ${topic} in room ${this.name}`);
         if (options) {
@@ -249,15 +333,15 @@ class AgentRoom extends EventEmitter {
         }
     }
     _toConnectedAgent(actor) {
-        const presence = actor.presence || actor.data || {};
+        const presence = (actor.presence || actor.data || {});
         return {
-            actorId: actor.actorTokenId || actor.actorId || '',
-            name: presence.name || actor.actorTokenId || '',
-            role: presence.role || 'agent',
+            actorId: actor.actorTokenId || actor.actorId || "",
+            name: presence.name || actor.actorTokenId || "",
+            role: presence.role || "agent",
             capabilities: presence.capabilities || [],
             metadata: presence.metadata,
             connectedAt: actor.joinedAt || Date.now(),
-            protocol: typeof presence.protocol === 'number' ? presence.protocol : 1,
+            protocol: typeof presence.protocol === "number" ? presence.protocol : 1,
             status: actor.status,
         };
     }
@@ -278,62 +362,6 @@ class AgentRoom extends EventEmitter {
             // fetchPresence may not be available yet
         }
     }
-    _wirePresenceListeners() {
-        if (!this._client)
-            return;
-        const client = this._client;
-        client.on?.('presence:join', (evt) => {
-            if (evt?.roomId === this.name || !evt?.roomId) {
-                const id = evt?.actorId || evt?.actorTokenId;
-                const data = evt?.data || evt?.presence || {};
-                if (id) {
-                    const agent = {
-                        actorId: id,
-                        name: data.name || id,
-                        role: data.role || 'agent',
-                        capabilities: data.capabilities || [],
-                        metadata: data.metadata,
-                        connectedAt: Date.now(),
-                        protocol: typeof data.protocol === 'number' ? data.protocol : 1,
-                    };
-                    this._agents.set(id, agent);
-                    this._log(`agent joined room ${this.name}:`, agent.name, agent.capabilities);
-                    this.emit('presenceJoin', id, data);
-                }
-            }
-        });
-        client.on?.('presence:leave', (evt) => {
-            if (evt?.roomId === this.name || !evt?.roomId) {
-                const id = evt?.actorId || evt?.actorTokenId;
-                if (id) {
-                    const agent = this._agents.get(id);
-                    this._agents.delete(id);
-                    this._log(`agent left room ${this.name}:`, agent?.name || id);
-                    this.emit('presenceLeave', id);
-                }
-            }
-        });
-        client.on?.('presence:update', (evt) => {
-            if (evt?.roomId === this.name || !evt?.roomId) {
-                const id = evt?.actorId || evt?.actorTokenId;
-                const data = evt?.data || evt?.presence || {};
-                if (id) {
-                    const existing = this._agents.get(id);
-                    const agent = {
-                        actorId: id,
-                        name: data.name || existing?.name || id,
-                        role: data.role || existing?.role || 'agent',
-                        capabilities: data.capabilities || existing?.capabilities || [],
-                        metadata: data.metadata || existing?.metadata,
-                        connectedAt: existing?.connectedAt || Date.now(),
-                        protocol: typeof data.protocol === 'number' ? data.protocol : (existing?.protocol ?? 1),
-                    };
-                    this._agents.set(id, agent);
-                    this.emit('presenceUpdate', id, data);
-                }
-            }
-        });
-    }
     _wireTopicListeners() {
         // Work distribution topics honour the connection-level loadBalance
         // setting, so a pool shares each message one-of-N (no double handling):
@@ -367,14 +395,14 @@ class AgentRoom extends EventEmitter {
             { topic: TOPIC_INBOX, event: "inbox" },
         ];
         for (const { topic, event } of simpleMap) {
-            this._roomContext.on(topic, (data) => {
+            this._on(topic, (data) => {
                 this._log(`received ${topic} in room ${this.name}`);
                 this.emit(event, data);
             });
         }
         // Multiplexed: results topic carries task results AND tool responses,
         // both filter-directed to this agent.
-        this._roomContext.on(TOPIC_RESULTS, (data) => {
+        this._on(TOPIC_RESULTS, (data) => {
             this._log(`received ${TOPIC_RESULTS} in room ${this.name}`);
             if (data?.type === "tool_response") {
                 this.emit("toolResponse", data);
@@ -384,7 +412,7 @@ class AgentRoom extends EventEmitter {
             }
         });
         // Multiplexed: approval topic carries requests + responses
-        this._roomContext.on(TOPIC_APPROVAL, (data) => {
+        this._on(TOPIC_APPROVAL, (data) => {
             this._log(`received ${TOPIC_APPROVAL} in room ${this.name}`);
             if (data?.type === "approval_response") {
                 this.emit("approvalResponse", data);
@@ -396,7 +424,7 @@ class AgentRoom extends EventEmitter {
         // Tools topic carries requests; tool_response is still accepted here for
         // backward compatibility with responders on older SDK versions (their
         // responses are only reliable when the requester is not load-balanced).
-        this._roomContext.on(TOPIC_TOOLS, (data) => {
+        this._on(TOPIC_TOOLS, (data) => {
             this._log(`received ${TOPIC_TOOLS} in room ${this.name}`);
             if (data?.type === "tool_response") {
                 this.emit("toolResponse", data);
@@ -436,6 +464,29 @@ function createLogger(prefix, enabled) {
 function createTimestamp() {
     return Date.now();
 }
+// ============ Wrapper registry ============
+// One wrapper instance per (client, appName): two wrappers sharing an app on
+// one connection would collide on topics, presence and the lobby.
+// Warn (not throw): HMR and tests legitimately construct before disposing.
+const wrapperRegistry = new WeakMap();
+/** Register a wrapper against a client + appName; warns on collision. */
+function registerWrapper(client, appName, wrapperName) {
+    let apps = wrapperRegistry.get(client);
+    if (!apps) {
+        apps = new Map();
+        wrapperRegistry.set(client, apps);
+    }
+    const existing = apps.get(appName);
+    if (existing) {
+        console.warn(`[${wrapperName}] Another wrapper (${existing}) is already attached to this client for app "${appName}". ` +
+            `Use one wrapper per (client, app) — detach the other instance first.`);
+    }
+    apps.set(appName, wrapperName);
+}
+/** Release a wrapper's (client, appName) registration on detach. */
+function releaseWrapper(client, appName) {
+    wrapperRegistry.get(client)?.delete(appName);
+}
 
 /**
  * NoLagAgents — high-level agent coordination SDK built on @nolag/js-sdk.
@@ -443,193 +494,438 @@ function createTimestamp() {
  * Provides typed rooms for multi-agent patterns: Handoff, Blackboard,
  * Inbox, Tools, Approval, and Observe.
  *
+ * The wrapper NEVER manages the connection. The app owns one core NoLag
+ * client (shared by any number of wrappers on distinct apps) and the
+ * wrapper attaches to it at construction and releases it via `detach()`.
+ *
  * @example
  * ```typescript
+ * import { NoLag } from '@nolag/js-sdk';
  * import { NoLagAgents } from '@nolag/agents';
  *
- * const agents = new NoLagAgents(token, {
+ * const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token);
+ * const agents = new NoLagAgents({
+ *   client,
  *   appName: 'my-workflow',
  *   agentId: 'worker-1',
  *   presence: { name: 'worker-1', role: 'agent', capabilities: ['summarize'] },
  * });
- * await agents.connect();
+ *
+ * await client.connect();   // the app owns the connection
+ * await agents.ready();     // wrapper setup done (identity, rooms, lobby)
  *
  * const room = agents.room('default-workflow');
- * room.handoff.onTask(['summarize'], async (task, respond) => {
- *   const result = await summarize(task.payload);
- *   respond('success', { result });
- * });
+ * room.on('task', (task) => console.log('New task:', task));
+ *
+ * agents.detach();          // wrapper releases its handlers and topics
+ * client.disconnect();      // the app closes the socket
  * ```
  */
 class NoLagAgents extends EventEmitter {
-    constructor(token, options = {}) {
+    constructor(options) {
         super();
-        this._client = null;
-        this._appContext = null;
         this._rooms = new Map();
-        this._connected = false;
-        this._token = token;
+        this._lobby = null;
+        // Lifecycle: one setup run per connection epoch; detach is terminal.
+        this._epoch = 0;
+        this._detached = false;
+        this._isReady = false;
+        this._lobbyRefreshTimer = null;
+        // Stored client handler refs. INVARIANT: every client.on() below has a
+        // matching client.off() in detach() — never bare off(event), never inline
+        // closures on the client.
+        this._onConnectRef = () => this._onConnect();
+        this._onDisconnectRef = (reason) => {
+            this._log("disconnected:", reason);
+            this.emit("disconnected", reason);
+        };
+        this._onReconnectRef = () => {
+            this._log("reconnecting...");
+            this.emit("reconnecting");
+        };
+        this._onErrorRef = (error) => {
+            this._log("error:", error?.message ?? error);
+            this.emit("error", error);
+        };
+        this._onPresenceJoinRef = (data) => this._handleRoomPresenceJoin(data);
+        this._onPresenceLeaveRef = (data) => this._handleRoomPresenceLeave(data);
+        this._onPresenceUpdateRef = (data) => this._handleRoomPresenceUpdate(data);
+        this._onLobbyJoinRef = (data) => this._handleLobbyJoin(data);
+        this._onLobbyLeaveRef = (data) => this._handleLobbyLeave(data);
+        this._onLobbyUpdateRef = (data) => this._handleLobbyUpdate(data);
+        if (!options?.client) {
+            throw new TypeError("NoLagAgents requires an injected NoLag client: new NoLagAgents({ client, ... })");
+        }
+        this._client = options.client;
         this._options = {
             appName: options.appName ?? DEFAULT_APP_NAME,
             agentId: options.agentId ?? generateId(),
+            name: options.name,
+            role: options.role,
             debug: options.debug ?? false,
             rooms: options.rooms ?? [DEFAULT_ROOM],
             lobby: options.lobby,
-            presence: options.presence,
-            clientOptions: options.clientOptions,
+            presence: options.presence ?? this._presenceFromIdentity(options),
         };
         this._log = createLogger("NoLagAgents", this._options.debug);
+        this._readyPromise = new Promise((resolve, reject) => {
+            this._readyResolve = resolve;
+            this._readyReject = reject;
+        });
+        // ready() rejection is only meaningful to callers that await it
+        this._readyPromise.catch(() => { });
+        registerWrapper(this._client, this._options.appName, "NoLagAgents");
+        // Construction = attach: wire everything now, with stored refs.
+        this._client.on("connect", this._onConnectRef);
+        this._client.on("disconnect", this._onDisconnectRef);
+        this._client.on("reconnect", this._onReconnectRef);
+        this._client.on("error", this._onErrorRef);
+        this._client.on("presence:join", this._onPresenceJoinRef);
+        this._client.on("presence:leave", this._onPresenceLeaveRef);
+        this._client.on("presence:update", this._onPresenceUpdateRef);
+        this._client.on("lobbyPresence:join", this._onLobbyJoinRef);
+        this._client.on("lobbyPresence:leave", this._onLobbyLeaveRef);
+        this._client.on("lobbyPresence:update", this._onLobbyUpdateRef);
+        // Attach-to-connected: if the client is already authenticated, run setup.
+        // The microtask lets the caller wire wrapper event handlers synchronously
+        // first; a racing real 'connect' event wins via the epoch guard.
+        queueMicrotask(() => {
+            if (this._epoch === 0 && !this._detached && this._client.connected) {
+                this._onConnect();
+            }
+        });
     }
+    // ============ Public Properties ============
     /** The agent's unique ID */
     get agentId() {
         return this._options.agentId;
     }
-    /** Whether the client is connected */
+    /** Whether the underlying connection is established (connected ≠ ready) */
     get connected() {
-        return this._connected;
+        return !this._detached && this._client.connected;
+    }
+    /** The injected core client (owned by the app, not the wrapper) */
+    get client() {
+        return this._client;
     }
     /** Map of joined rooms */
     get rooms() {
         return this._rooms;
     }
-    /** Connect to NoLag and join configured rooms */
-    async connect() {
-        this._log("connecting...");
-        this._client = NoLag(this._token, {
-            ...this._options.clientOptions,
-        });
-        this._appContext = this._client.setApp(this._options.appName);
-        this._client.on("connected", () => {
-            this._connected = true;
-            this._log("connected");
+    // ============ Lifecycle ============
+    /**
+     * Resolves once the wrapper's first setup completed (identity, configured
+     * rooms and — when configured — the lobby ready; equivalently, once
+     * 'connected' has fired). Rejects only if detach() is called before that.
+     * Client auth failures surface via the app's own `await client.connect()`.
+     */
+    ready() {
+        return this._readyPromise;
+    }
+    /**
+     * Detach from the client: remove every handler this wrapper added,
+     * unsubscribe its topics and lobby (when connected), clear state.
+     * Terminal and idempotent; never touches the socket. To use agents again,
+     * construct a new instance.
+     */
+    detach() {
+        if (this._detached)
+            return;
+        this._log("detaching...");
+        this._detached = true;
+        this._epoch++; // aborts any in-flight setup at its next checkpoint
+        if (this._lobbyRefreshTimer) {
+            clearTimeout(this._lobbyRefreshTimer);
+            this._lobbyRefreshTimer = null;
+        }
+        // Remove all client handlers by stored ref
+        this._client.off("connect", this._onConnectRef);
+        this._client.off("disconnect", this._onDisconnectRef);
+        this._client.off("reconnect", this._onReconnectRef);
+        this._client.off("error", this._onErrorRef);
+        this._client.off("presence:join", this._onPresenceJoinRef);
+        this._client.off("presence:leave", this._onPresenceLeaveRef);
+        this._client.off("presence:update", this._onPresenceUpdateRef);
+        this._client.off("lobbyPresence:join", this._onLobbyJoinRef);
+        this._client.off("lobbyPresence:leave", this._onLobbyLeaveRef);
+        this._client.off("lobbyPresence:update", this._onLobbyUpdateRef);
+        // Rooms: handler-specific off + connected-gated server unsubscribe
+        for (const name of [...this._rooms.keys()]) {
+            this._rooms.get(name)._cleanup();
+            this._rooms.delete(name);
+        }
+        // Lobby: server unsubscribe is best-effort and needs a live socket
+        if (this._lobby && this._client.connected) {
+            try {
+                this._lobby.unsubscribe();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        this._lobby = null;
+        releaseWrapper(this._client, this._options.appName);
+        if (!this._isReady) {
+            this._readyReject(new Error("NoLagAgents detached before ready"));
+        }
+    }
+    // ============ Private: Epoch Setup ============
+    _onConnect() {
+        this._epoch++;
+        void this._runSetup(this._epoch);
+    }
+    /**
+     * One setup pass per connection epoch. Serves both initial setup (epoch 1)
+     * and reconnect restore (epoch > 1). Aborts silently whenever a newer
+     * epoch started or the wrapper detached — checked after every await.
+     */
+    async _runSetup(epoch) {
+        const stale = () => epoch !== this._epoch || this._detached;
+        this._log(this._isReady ? "restoring after reconnect..." : "setting up...");
+        this._log("agentId:", this._options.agentId, "→ actorId:", this._client.actorId);
+        if (!this._isReady) {
+            // First successful setup: auto-join configured rooms.
+            for (const roomName of this._options.rooms) {
+                this._joinRoomInternal(roomName);
+            }
+        }
+        else {
+            // Reconnect: the core auto-restores topic subscriptions, but not
+            // room-scoped presence — re-apply each room's local presence.
+            for (const room of this._rooms.values()) {
+                room._updateLocalPresence();
+            }
+        }
+        // Lobby is OPTIONAL: only when configured. Subscribe every epoch
+        // (idempotent server-side) and diff-hydrate from the returned snapshot —
+        // one path for setup and reconnect restore.
+        if (this._options.lobby) {
+            if (!this._lobby) {
+                this._lobby = this._client.setApp(this._options.appName).setLobby(this._options.lobby);
+            }
+            try {
+                const state = await this._lobby.subscribe();
+                if (stale())
+                    return;
+                this._diffHydrateLobby(state);
+                this._log("lobby subscribed:", this._options.lobby);
+            }
+            catch (err) {
+                if (stale())
+                    return;
+                this._log("lobby subscription failed:", err);
+            }
+        }
+        if (stale())
+            return;
+        // Ready keys on the first setup that COMPLETES, not on epoch 1: an
+        // epoch aborted by a racing reconnect must not strand ready().
+        if (!this._isReady) {
+            this._isReady = true;
+            this._readyResolve();
             this.emit("connected");
-        });
-        this._client.on("disconnected", (reason) => {
-            this._connected = false;
-            this._log("disconnected:", reason);
-            this.emit("disconnected", reason);
-        });
-        this._client.on("reconnected", () => {
-            this._connected = true;
-            this._log("reconnected");
+        }
+        else {
             this.emit("reconnected");
-        });
-        this._client.on("error", (err) => {
-            this._log("error:", err.message);
-            this.emit("error", err);
-        });
-        await this._client.connect();
-        // Auto-join configured rooms
-        for (const roomName of this._options.rooms) {
-            this.room(roomName);
         }
-        // Auto-subscribe to lobby if configured (for cross-room presence observation)
+        // Deferred lobby refetch: catches agents who joined during the setup
+        // window (only when the lobby is configured).
         if (this._options.lobby) {
-            await this.subscribeLobby(this._options.lobby);
+            this._scheduleLobbyRefresh(epoch);
         }
     }
+    _scheduleLobbyRefresh(epoch) {
+        if (this._lobbyRefreshTimer)
+            clearTimeout(this._lobbyRefreshTimer);
+        this._lobbyRefreshTimer = setTimeout(() => {
+            this._lobbyRefreshTimer = null;
+            if (epoch !== this._epoch || this._detached || !this._client.connected || !this._lobby) {
+                return;
+            }
+            this._lobby
+                .fetchPresence()
+                .then((state) => {
+                if (epoch !== this._epoch || this._detached)
+                    return;
+                this._diffHydrateLobby(state);
+            })
+                .catch(() => {
+                /* best-effort */
+            });
+        }, LOBBY_REFRESH_DELAY_MS);
+    }
+    // ============ Room Management ============
+    /**
+     * Get or create an AgentRoom wrapper.
+     * If the room hasn't been joined yet, it will be joined automatically.
+     */
+    room(name) {
+        this._assertUsable();
+        const existing = this._rooms.get(name);
+        if (existing)
+            return existing;
+        return this._joinRoomInternal(name);
+    }
+    // ============ Lobby (cross-room presence observation) ============
     /**
-     * Subscribe to a lobby for cross-room presence observation.
-     * Lobby presence events are forwarded to all AgentRooms.
+     * Subscribe to a lobby for cross-room presence observation. Lobby presence
+     * events are forwarded into all AgentRooms. Prefer the `lobby` constructor
+     * option — this method is for on-demand subscription after ready.
      *
      * Returns the initial presence snapshot.
      */
     async subscribeLobby(lobbySlug) {
-        if (!this._appContext) {
-            throw new Error("Not connected. Call connect() before subscribing to lobbies.");
-        }
+        this._assertUsable();
         this._log(`subscribing to lobby: ${lobbySlug}`);
-        const lobby = this._appContext.setLobby(lobbySlug);
-        // Listen for lobby presence events on the client
-        // (lobby.on() uses lobby UUID internally which may not match)
-        this._client.on('lobbyPresence:join', (evt) => {
-            const id = evt?.actorId;
-            const data = evt?.data || {};
-            if (id) {
-                this._log(`lobby presence:join — ${data.name || id}`);
-                for (const room of this._rooms.values()) {
-                    const agents = room._agents;
-                    if (!agents.has(id)) {
-                        agents.set(id, {
-                            actorId: id,
-                            name: data.name || id,
-                            role: data.role || 'agent',
-                            capabilities: data.capabilities || [],
-                            metadata: data.metadata,
-                            connectedAt: Date.now(),
-                        });
-                    }
-                    room._emitPresence('presenceJoin', id, data);
-                }
-            }
-        });
-        this._client.on('lobbyPresence:leave', (evt) => {
-            const id = evt?.actorId;
-            if (id) {
-                this._log(`lobby presence:leave — ${id}`);
-                for (const room of this._rooms.values()) {
-                    const agents = room._agents;
-                    agents.delete(id);
-                    room._emitPresence('presenceLeave', id);
-                }
-            }
-        });
-        this._client.on('lobbyPresence:update', (evt) => {
-            const id = evt?.actorId;
-            const data = evt?.data || {};
-            if (id) {
-                for (const room of this._rooms.values()) {
-                    const agents = room._agents;
-                    const existing = agents.get(id);
-                    if (existing) {
-                        if (data.name)
-                            existing.name = data.name;
-                        if (data.role)
-                            existing.role = data.role;
-                        if (data.capabilities)
-                            existing.capabilities = data.capabilities;
-                        if (data.metadata)
-                            existing.metadata = data.metadata;
-                    }
-                    room._emitPresence('presenceUpdate', id, data);
-                }
-            }
-        });
+        this._options.lobby = lobbySlug;
+        if (!this._lobby) {
+            this._lobby = this._client.setApp(this._options.appName).setLobby(lobbySlug);
+        }
         try {
-            const initialState = await lobby.subscribe();
-            this._log(`lobby subscribed, initial state:`, Object.keys(initialState || {}));
-            return initialState || {};
+            const state = await this._lobby.subscribe();
+            if (!this._detached)
+                this._diffHydrateLobby(state);
+            return state || {};
         }
         catch (err) {
-            this._log(`lobby subscription failed:`, err);
+            this._log("lobby subscription failed:", err);
             return {};
         }
     }
-    /** Disconnect from NoLag */
-    disconnect() {
-        this._log("disconnecting...");
-        this._client?.disconnect();
-        this._rooms.clear();
-        this._client = null;
-        this._appContext = null;
-        this._connected = false;
+    // ============ Private: Guards ============
+    _assertUsable() {
+        if (this._detached) {
+            throw new Error("NoLagAgents has been detached — construct a new instance");
+        }
+        if (!this._isReady) {
+            throw new Error('NoLagAgents not ready — await ready() or the "connected" event');
+        }
+    }
+    // ============ Private: Room Setup ============
+    _joinRoomInternal(name) {
+        this._log(`joining room: ${name}`);
+        const roomContext = this._client.setApp(this._options.appName).setRoom(name);
+        const room = new AgentRoom(name, roomContext, createLogger(`AgentRoom:${name}`, this._options.debug), this._options.agentId, this._options.appName, () => this._client.connected, this._options.presence);
+        this._rooms.set(name, room);
+        return room;
     }
+    // ============ Private: Scope Filtering ============
     /**
-     * Get or create an AgentRoom wrapper.
-     * If the room hasn't been joined yet, it will be joined automatically.
+     * On a shared client, presence events from other apps' wrappers arrive on
+     * the same connection-level events. Wrappers stamp their presence with a
+     * `__scope` (their appName); a mismatched tag means another app's data.
+     * Untagged presence is accepted (older peers in this same app).
      */
-    room(name) {
-        let agentRoom = this._rooms.get(name);
-        if (agentRoom)
-            return agentRoom;
-        if (!this._appContext) {
-            throw new Error("Not connected. Call connect() before accessing rooms.");
+    _foreignScope(data) {
+        const scope = data?.__scope;
+        return typeof scope === "string" && scope !== this._options.appName;
+    }
+    // ============ Private: Room Presence → Rooms ============
+    _handleRoomPresenceJoin(data) {
+        if (data.actorTokenId === this._client.actorId)
+            return;
+        const presence = (data.presence || {});
+        if (this._foreignScope(presence))
+            return;
+        const roomId = data.roomId;
+        for (const room of this._targetRooms(roomId)) {
+            room._handlePresenceJoin(data.actorTokenId, presence);
+        }
+    }
+    _handleRoomPresenceLeave(data) {
+        if (data.actorTokenId === this._client.actorId)
+            return;
+        const roomId = data.roomId;
+        for (const room of this._targetRooms(roomId)) {
+            room._handlePresenceLeave(data.actorTokenId);
+        }
+    }
+    _handleRoomPresenceUpdate(data) {
+        if (data.actorTokenId === this._client.actorId)
+            return;
+        const presence = (data.presence || {});
+        if (this._foreignScope(presence))
+            return;
+        const roomId = data.roomId;
+        for (const room of this._targetRooms(roomId)) {
+            room._handlePresenceUpdate(data.actorTokenId, presence);
+        }
+    }
+    /** Rooms a presence event targets: the named room, or all when unscoped. */
+    _targetRooms(roomId) {
+        if (roomId && this._rooms.has(roomId))
+            return [this._rooms.get(roomId)];
+        if (roomId)
+            return [];
+        return [...this._rooms.values()];
+    }
+    // ============ Private: Lobby → Rooms ============
+    _handleLobbyJoin(event) {
+        const { actorId, data } = event;
+        if (actorId === this._client.actorId)
+            return;
+        const presence = (data || {});
+        if (this._foreignScope(presence))
+            return;
+        this._log(`lobby presence:join — ${presence.name || actorId}`);
+        for (const room of this._rooms.values()) {
+            room._handlePresenceJoin(actorId, presence);
         }
-        this._log(`joining room: ${name}`);
-        const roomContext = this._appContext.setRoom(name);
-        agentRoom = new AgentRoom(name, roomContext, this._client, this._log, this._options.agentId, this._options.presence);
-        this._rooms.set(name, agentRoom);
-        return agentRoom;
+    }
+    _handleLobbyLeave(event) {
+        const { actorId, data } = event;
+        if (actorId === this._client.actorId)
+            return;
+        const presence = (data || {});
+        if (this._foreignScope(presence))
+            return;
+        this._log(`lobby presence:leave — ${actorId}`);
+        for (const room of this._rooms.values()) {
+            room._handlePresenceLeave(actorId);
+        }
+    }
+    _handleLobbyUpdate(event) {
+        const { actorId, data } = event;
+        if (actorId === this._client.actorId)
+            return;
+        const presence = (data || {});
+        if (this._foreignScope(presence))
+            return;
+        for (const room of this._rooms.values()) {
+            room._handlePresenceUpdate(actorId, presence);
+        }
+    }
+    /**
+     * Reconcile the rooms' agent registries against a fresh lobby snapshot,
+     * routing each present actor in as a join. One path for initial hydration,
+     * reconnect restore, and the deferred refetch.
+     */
+    _diffHydrateLobby(state) {
+        for (const roomId of Object.keys(state)) {
+            const roomPresence = state[roomId];
+            for (const actorId of Object.keys(roomPresence)) {
+                if (actorId === this._client.actorId)
+                    continue;
+                const raw = roomPresence[actorId];
+                // Server returns full actor records with presence nested under .presence
+                const presence = (raw?.presence ?? raw);
+                if (this._foreignScope(presence))
+                    continue;
+                for (const room of this._rooms.values()) {
+                    room._handlePresenceJoin(actorId, presence);
+                }
+            }
+        }
+    }
+    // ============ Private: Helpers ============
+    /** Derive presence identity from name/role options when no presence given. */
+    _presenceFromIdentity(options) {
+        if (!options.name && !options.role)
+            return undefined;
+        return {
+            name: options.name ?? (options.agentId ?? "agent"),
+            role: options.role ?? "agent",
+        };
     }
 }
 
@@ -1139,10 +1435,20 @@ class Tools {
         this._agentId = agentId;
         // Wire response correlation
         this._room.on("toolResponse", (envelope) => {
+            if (!envelope || typeof envelope.correlationId !== "string")
+                return;
             this._correlations.resolve(envelope.correlationId, envelope);
         });
         // Wire request handling
         this._room.on("toolRequest", async (envelope) => {
+            // The tools topic is an open room surface: anything published there
+            // that is not a tool_response is classified as a request, including
+            // foreign or malformed payloads. A request with no toolName cannot be
+            // routed OR NACKed meaningfully — and it must never be able to crash
+            // the host (this listener is async, so an uncaught throw here becomes
+            // an unhandled rejection that terminates the process).
+            if (!envelope || typeof envelope.toolName !== "string")
+                return;
             const handler = this._handlers.get(envelope.toolName);
             // Direct the response back to the requester's filter sub-topic
             const replyTo = envelope.replyTo ?? envelope.requestedBy;
@@ -1191,6 +1497,9 @@ class Tools {
     /** True when this agent hosts handlers in the tool's namespace (prefix
      *  before the first '.'); unprefixed tools match any unprefixed handler. */
     _ownsNamespace(toolName) {
+        // Belt and braces: a nameless tool belongs to nobody.
+        if (typeof toolName !== "string")
+            return false;
         if (this._handlers.size === 0)
             return false;
         const ns = toolName.includes(".") ? toolName.slice(0, toolName.indexOf(".")) : null;