@nolag/agents 1.0.0 → 1.2.0

package/dist/react-native.js

@@ -0,0 +1,1752 @@
+/**
+ * Tiny typed event emitter — framework-agnostic base for NoLagAgents and AgentRoom.
+ *
+ * EventMap is a record of event name -> tuple of handler arguments.
+ * e.g. { task: [TaskEnvelope]; result: [ResultEnvelope] }
+ */
+class EventEmitter {
+    constructor() {
+        this._handlers = new Map();
+    }
+    on(event, handler) {
+        if (!this._handlers.has(event)) {
+            this._handlers.set(event, new Set());
+        }
+        this._handlers.get(event).add(handler);
+        return this;
+    }
+    off(event, handler) {
+        if (handler) {
+            this._handlers.get(event)?.delete(handler);
+        }
+        else {
+            this._handlers.delete(event);
+        }
+        return this;
+    }
+    removeAllListeners() {
+        this._handlers.clear();
+        return this;
+    }
+    emit(event, ...args) {
+        const handlers = this._handlers.get(event);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                // 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);
+            }
+        }
+    }
+    listenerCount(event) {
+        return this._handlers.get(event)?.size ?? 0;
+    }
+}
+
+/**
+ * Generate a unique ID.
+ * Uses crypto.randomUUID when available, falls back to a simple random string.
+ */
+function generateId() {
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return "xxxx-xxxx-xxxx-xxxx".replace(/x/g, () => Math.floor(Math.random() * 16).toString(16));
+}
+/**
+ * Create a debug logger that only logs when enabled.
+ */
+function createLogger(prefix, enabled) {
+    if (!enabled) {
+        return (..._args) => { };
+    }
+    return (...args) => {
+        console.log(`[${prefix}]`, ...args);
+    };
+}
+/**
+ * Create a Unix millisecond timestamp.
+ */
+function createTimestamp() {
+    return Date.now();
+}
+// ============ Filters ============
+/**
+ * Build the filter fragment of an emit options object.
+ *
+ * `filter` wins over `filters`: a publish is routed to exactly one topic, so
+ * honouring both would silently drop one of them.
+ */
+function filterEmitOptions(opts) {
+    if (opts?.filter)
+        return { filter: opts.filter };
+    if (opts?.filters && opts.filters.length > 0)
+        return { filters: opts.filters };
+    return {};
+}
+/**
+ * Merge OR terms into an existing filter set. AND groups (nested arrays) are
+ * preserved as-is — only plain string terms are deduplicated.
+ */
+function mergeFilters(existing, add) {
+    const simple = new Set();
+    const groups = [];
+    for (const f of existing) {
+        if (typeof f === 'string')
+            simple.add(f);
+        else
+            groups.push(f);
+    }
+    for (const v of add)
+        simple.add(v);
+    return [...simple, ...groups];
+}
+/**
+ * Drop OR terms from a filter set. AND groups are left untouched — remove
+ * those by calling `setFilters` with the set you want.
+ */
+function withoutFilters(existing, remove) {
+    const drop = new Set(remove);
+    return existing.filter((f) => typeof f !== 'string' || !drop.has(f));
+}
+// ============ 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);
+}
+
+/** Default app name for agent coordination */
+const DEFAULT_APP_NAME = "agents";
+/** Topic name for task dispatch (Handoff pattern) */
+const TOPIC_TASKS = "tasks";
+/** Topic name for task results */
+const TOPIC_RESULTS = "results";
+/** Topic name for shared state (Blackboard pattern) */
+const TOPIC_STATE = "state";
+/** Topic name for observability events (Observe pattern) */
+const TOPIC_EVENTS = "events";
+/** Topic name for per-agent inboxes (Inbox pattern) */
+const TOPIC_INBOX = "inbox";
+/** Topic name for tool invocations (Tools pattern) */
+const TOPIC_TOOLS = "tools";
+/** Topic name for human-in-the-loop approval (Approve pattern) */
+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;
+
+/**
+ * Maps the public topic names onto the wire topics. `results` is absent by
+ * design — it is reserved for directed replies keyed to this agent's id.
+ */
+const FILTER_TOPICS = {
+    tasks: TOPIC_TASKS,
+    tools: TOPIC_TOOLS,
+    state: TOPIC_STATE,
+    events: TOPIC_EVENTS,
+    inbox: TOPIC_INBOX,
+    approval: TOPIC_APPROVAL,
+};
+const ALL_FILTER_TOPICS = Object.keys(FILTER_TOPICS);
+/**
+ * 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.
+ *
+ * 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 connected = room.getConnectedAgents();
+ * const summarizers = room.findAgents('summarize');
+ *
+ * // Capability-filtered task handler
+ * room.on('task', (envelope) => console.log('New task:', envelope));
+ * ```
+ */
+class AgentRoom extends EventEmitter {
+    /** @internal */
+    constructor(name, roomContext, log, agentId, appName, isConnected, presence, filters) {
+        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 = [];
+        /** Filter values applied per topic. `results` is never included. */
+        this._filters = {
+            tasks: [], tools: [], state: [], events: [], inbox: [], approval: [],
+        };
+        this.name = name;
+        this.agentId = agentId;
+        this._roomContext = roomContext;
+        this._log = log;
+        this._appName = appName;
+        this._isConnected = isConnected;
+        this._presence = presence;
+        if (filters && filters.length > 0) {
+            for (const topic of ALL_FILTER_TOPICS)
+                this._filters[topic] = [...filters];
+        }
+        this._wireTopicListeners();
+        // Set presence if provided (with the SDK's protocol version advertised
+        // so counterparts can detect incompatible reply semantics, and a __scope
+        // tag so co-attached wrappers on other apps filter our presence out).
+        if (presence) {
+            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
+        void this._fetchInitialPresence();
+    }
+    // ============================================================
+    // SERVICE DISCOVERY
+    // ============================================================
+    /** Get all currently connected agents */
+    getConnectedAgents() {
+        return Array.from(this._agents.values());
+    }
+    /** Find agents that have a specific capability */
+    findAgents(capability) {
+        return Array.from(this._agents.values()).filter((a) => a.capabilities.includes(capability));
+    }
+    /** Check if any connected agent can handle a capability */
+    hasCapability(capability) {
+        return this.findAgents(capability).length > 0;
+    }
+    /** Get all capabilities available across connected agents */
+    getAvailableCapabilities() {
+        const caps = new Set();
+        for (const agent of this._agents.values()) {
+            for (const cap of agent.capabilities) {
+                caps.add(cap);
+            }
+        }
+        return Array.from(caps);
+    }
+    // ============================================================
+    // PRESENCE
+    // ============================================================
+    /** Update this agent's presence data (protocol version auto-injected) */
+    setPresence(data) {
+        this._presence = { protocol: AGENTS_PROTOCOL_VERSION, ...data };
+        this._log(`updating presence in room ${this.name}`);
+        this._roomContext.setPresence({ ...this._presence, __scope: this._appName });
+    }
+    /** Fetch current presence snapshot for this room */
+    async fetchPresence() {
+        try {
+            const actors = await this._roomContext.fetchPresence();
+            return (actors || []).map((a) => this._toConnectedAgent(a));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Get the underlying RoomContext for advanced usage */
+    get context() {
+        return this._roomContext;
+    }
+    // ============================================================
+    // PUBLISH (with automatic agentId injection)
+    // ============================================================
+    /** Publish to the tasks topic */
+    publishTask(envelope, opts) {
+        // Auto-set createdBy if not set
+        if (!envelope.createdBy) {
+            envelope.createdBy = this.agentId;
+        }
+        // Routing by capability (`{ filter: envelope.capability }`) is opt-in:
+        // it only reaches workers that filter on it, and mixing filtered and
+        // wildcard workers in one load-balance pool double-delivers.
+        this._publish(TOPIC_TASKS, envelope, filterEmitOptions(opts));
+    }
+    /** Publish to the results topic — directed to the dispatcher via filter when replyTo is set */
+    publishResult(envelope) {
+        // Auto-set completedBy if not set
+        if (!envelope.completedBy) {
+            envelope.completedBy = this.agentId;
+        }
+        if (envelope.replyTo) {
+            this._publish(TOPIC_RESULTS, envelope, { filter: envelope.replyTo });
+        }
+        else {
+            // Legacy: no reply address — unfiltered publish (only reaches
+            // wildcard subscribers, i.e. pre-0.2.0 SDKs)
+            this._publish(TOPIC_RESULTS, envelope);
+        }
+    }
+    /** Publish to the state topic (retained) */
+    publishState(data, opts) {
+        // Auto-set updatedBy if not set
+        if (!data.updatedBy) {
+            data.updatedBy = this.agentId;
+        }
+        this._publish(TOPIC_STATE, data, { retain: true, ...filterEmitOptions(opts) });
+    }
+    /** Publish to the events topic */
+    publishEvent(data, opts) {
+        // Auto-set emittedBy if not set
+        if (!data.emittedBy) {
+            data.emittedBy = this.agentId;
+        }
+        this._publish(TOPIC_EVENTS, data, filterEmitOptions(opts));
+    }
+    /** Publish to the inbox topic */
+    publishInbox(data, opts) {
+        this._publish(TOPIC_INBOX, data, filterEmitOptions(opts));
+    }
+    /**
+     * Publish a tool message.
+     * Requests go to the tools topic (load-balanced one-of-N across server
+     * replicas). Responses are directed to the requester on the results topic
+     * via filter — never load-balanced, never broadcast.
+     */
+    publishTools(data, opts) {
+        if (data?.type === "tool_response" && typeof data.replyTo === "string" && data.replyTo) {
+            // Responses stay keyed to the requester; a caller filter must not
+            // redirect them away from the agent waiting on the correlation.
+            this._publish(TOPIC_RESULTS, data, { filter: data.replyTo });
+            return;
+        }
+        this._publish(TOPIC_TOOLS, data, filterEmitOptions(opts));
+    }
+    /** Publish to the approval topic (retained) */
+    publishApproval(data, opts) {
+        this._publish(TOPIC_APPROVAL, data, { retain: true, ...filterEmitOptions(opts) });
+    }
+    // ============================================================
+    // FILTERS
+    // ============================================================
+    /** The filter values currently applied to this room, by topic. */
+    get filters() {
+        return {
+            tasks: [...this._filters.tasks],
+            tools: [...this._filters.tools],
+            state: [...this._filters.state],
+            events: [...this._filters.events],
+            inbox: [...this._filters.inbox],
+            approval: [...this._filters.approval],
+        };
+    }
+    /**
+     * Replace this room's filters — only messages published with one of these
+     * values are delivered. Applies to every filterable topic unless scoped with
+     * `{ topic }`.
+     *
+     * The usual case is a worker declaring its capabilities on `tasks`, so the
+     * broker routes only work it can do instead of every worker receiving every
+     * task and discarding the rest. Pair it with
+     * `publishTask(envelope, { filter: capability })` on the dispatcher.
+     *
+     * `results` is never filtered here: it carries directed replies keyed to
+     * this agent's id, and repointing it would strand pending results.
+     *
+     * With load balancing on, keep a worker pool uniform — the broker treats a
+     * wildcard and a filtered subscription as separate share groups, so a mixed
+     * pool delivers each task twice.
+     *
+     * Passing an empty array clears filtering and restores the wildcard
+     * subscription, which receives everything.
+     *
+     * @example
+     * ```ts
+     * room.setFilters(['ocr', 'translate'], { topic: 'tasks' });
+     * room.setFilters([]);  // everything
+     * ```
+     */
+    setFilters(values, opts) {
+        for (const topic of this._targetTopics(opts)) {
+            this._filters[topic] = [...values];
+            // The core types filters as `string[]`, but both its implementation and
+            // the wire protocol accept AND groups (nested arrays).
+            this._roomContext.setFilters(FILTER_TOPICS[topic], values);
+        }
+    }
+    /** Add filter values to the existing set. Existing AND groups are kept. */
+    addFilters(values, opts) {
+        for (const topic of this._targetTopics(opts)) {
+            this.setFilters(mergeFilters(this._filters[topic], values), { topic });
+        }
+    }
+    /**
+     * Remove filter values from the existing set. Removing the last value
+     * restores the wildcard subscription.
+     */
+    removeFilters(values, opts) {
+        for (const topic of this._targetTopics(opts)) {
+            this.setFilters(withoutFilters(this._filters[topic], values), { topic });
+        }
+    }
+    _targetTopics(opts) {
+        return opts?.topic ? [opts.topic] : ALL_FILTER_TOPICS;
+    }
+    // ============================================================
+    // 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}`);
+        // An empty options object is dropped rather than forwarded: publishing
+        // without filters should look exactly as it did before filters existed.
+        if (options && Object.keys(options).length > 0) {
+            this._roomContext.emit(topic, data, options);
+        }
+        else {
+            this._roomContext.emit(topic, data);
+        }
+    }
+    /** @internal Subscribe honouring the topic's filter set. */
+    _subscribeFiltered(topic, values) {
+        if (values.length > 0) {
+            this._roomContext.subscribe(topic, { filters: values });
+        }
+        else {
+            this._roomContext.subscribe(topic);
+        }
+    }
+    _toConnectedAgent(actor) {
+        const presence = (actor.presence || actor.data || {});
+        return {
+            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,
+            status: actor.status,
+        };
+    }
+    async _fetchInitialPresence() {
+        try {
+            const actors = await this._roomContext.fetchPresence();
+            if (Array.isArray(actors)) {
+                for (const actor of actors) {
+                    const connected = this._toConnectedAgent(actor);
+                    if (connected.actorId) {
+                        this._agents.set(connected.actorId, connected);
+                    }
+                }
+                this._log(`discovered ${this._agents.size} agents in room ${this.name}`);
+            }
+        }
+        catch {
+            // fetchPresence may not be available yet
+        }
+    }
+    _wireTopicListeners() {
+        // Work distribution topics honour the connection-level loadBalance
+        // setting, so a pool shares each message one-of-N (no double handling):
+        //  - tasks: each task goes to exactly one worker in the group
+        //  - tools: each tool REQUEST goes to exactly one tool-server replica
+        this._subscribeFiltered(TOPIC_TASKS, this._filters.tasks);
+        this._subscribeFiltered(TOPIC_TOOLS, this._filters.tools);
+        // Replies are DIRECTED, not broadcast: the results topic carries task
+        // results and tool responses published with `filter: <recipient agentId>`,
+        // and each agent subscribes only to its own filter sub-topic. The broker
+        // routes each reply straight to the requester — no fan-out waste, and
+        // immune to load-balance groups (a broadcast or LB'd reply could land on
+        // a group member that doesn't hold the pending correlation, timing out
+        // the requester even though the responder did the work).
+        this._roomContext.subscribe(TOPIC_RESULTS, {
+            loadBalance: false,
+            filters: [this.agentId],
+        });
+        // Broadcast topics must always fan out, even when the connection enables
+        // loadBalance for work distribution: state/events are broadcasts by
+        // nature; inbox and approval messages are claimed client-side.
+        const broadcastTopics = ["state", "events", "inbox", "approval"];
+        for (const key of broadcastTopics) {
+            const values = this._filters[key];
+            this._roomContext.subscribe(FILTER_TOPICS[key], {
+                loadBalance: false,
+                ...(values.length > 0 ? { filters: values } : {}),
+            });
+        }
+        // Simple 1:1 mappings
+        const simpleMap = [
+            { topic: TOPIC_TASKS, event: "task" },
+            { topic: TOPIC_STATE, event: "stateChange" },
+            { topic: TOPIC_EVENTS, event: "event" },
+            { topic: TOPIC_INBOX, event: "inbox" },
+        ];
+        for (const { topic, event } of simpleMap) {
+            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._on(TOPIC_RESULTS, (data) => {
+            this._log(`received ${TOPIC_RESULTS} in room ${this.name}`);
+            if (data?.type === "tool_response") {
+                this.emit("toolResponse", data);
+            }
+            else {
+                this.emit("result", data);
+            }
+        });
+        // Multiplexed: approval topic carries requests + responses
+        this._on(TOPIC_APPROVAL, (data) => {
+            this._log(`received ${TOPIC_APPROVAL} in room ${this.name}`);
+            if (data?.type === "approval_response") {
+                this.emit("approvalResponse", data);
+            }
+            else {
+                this.emit("approvalRequest", data);
+            }
+        });
+        // 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._on(TOPIC_TOOLS, (data) => {
+            this._log(`received ${TOPIC_TOOLS} in room ${this.name}`);
+            if (data?.type === "tool_response") {
+                this.emit("toolResponse", data);
+            }
+            else {
+                this.emit("toolRequest", data);
+            }
+        });
+    }
+}
+
+/**
+ * NoLagAgents — high-level agent coordination SDK built on @nolag/js-sdk.
+ *
+ * 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 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 client.connect();   // the app owns the connection
+ * await agents.ready();     // wrapper setup done (identity, rooms, lobby)
+ *
+ * const room = agents.room('default-workflow');
+ * 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(options) {
+        super();
+        this._rooms = new Map();
+        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 ?? 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 underlying connection is established (connected ≠ ready) */
+    get 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;
+    }
+    // ============ 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");
+        }
+        else {
+            this.emit("reconnected");
+        }
+        // Deferred lobby refetch: catches agents who joined during the setup
+        // window (only when the lobby is configured).
+        if (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, opts) {
+        this._assertUsable();
+        const existing = this._rooms.get(name);
+        if (existing) {
+            // Already joined — re-point its filters rather than ignoring them.
+            if (opts?.filters)
+                existing.setFilters(opts.filters);
+            return existing;
+        }
+        return this._joinRoomInternal(name, opts?.filters);
+    }
+    // ============ Lobby (cross-room presence observation) ============
+    /**
+     * 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) {
+        this._assertUsable();
+        this._log(`subscribing to lobby: ${lobbySlug}`);
+        this._options.lobby = lobbySlug;
+        if (!this._lobby) {
+            this._lobby = this._client.setApp(this._options.appName).setLobby(lobbySlug);
+        }
+        try {
+            const state = await this._lobby.subscribe();
+            if (!this._detached)
+                this._diffHydrateLobby(state);
+            return state || {};
+        }
+        catch (err) {
+            this._log("lobby subscription failed:", err);
+            return {};
+        }
+    }
+    // ============ 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, filters) {
+        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, filters);
+        this._rooms.set(name, room);
+        return room;
+    }
+    // ============ Private: Scope Filtering ============
+    /**
+     * 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).
+     */
+    _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);
+        }
+    }
+    _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",
+        };
+    }
+}
+
+/**
+ * IncompatibleProtocolError — thrown when an operation would deterministically
+ * fail because every relevant counterpart runs an older agents-protocol
+ * (pre-directed-replies). Failing fast beats burning the correlation timeout.
+ */
+class IncompatibleProtocolError extends Error {
+    constructor(operation, agents) {
+        const list = agents.map((a) => `${a.name} (protocol ${a.protocol})`).join(", ");
+        super(`${operation} cannot succeed: every relevant agent advertises agents-protocol < 2 ` +
+            `[${list}]. Protocol >= 2 responders direct replies to the requester; older ones ` +
+            `broadcast and their replies never reach this SDK's filtered subscription. ` +
+            `Upgrade the responders to @nolag/agents >= 0.2.0 / nolag-agents >= 0.3.0. ` +
+            `NOTE: 0.2.x/0.3.0 responders DO have directed replies but do not yet advertise ` +
+            `protocol — if your responders run those versions, pass { allowLegacyResponders: true }.`);
+        this.name = "IncompatibleProtocolError";
+    }
+}
+
+/**
+ * CorrelationManager — maps correlationIds to pending promises with timeout.
+ * Used by Handoff and Tools patterns for request/response correlation.
+ */
+class CorrelationManager {
+    constructor() {
+        this._pending = new Map();
+    }
+    /**
+     * Register a pending correlation. Returns a promise that resolves
+     * when `resolve()` is called with the matching correlationId.
+     */
+    register(correlationId, timeoutMs, context) {
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            if (timeoutMs && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    this._pending.delete(correlationId);
+                    // Context turns an opaque correlation id into an actionable error —
+                    // callers supply what they were waiting for and the likely causes.
+                    const what = context ?? `Correlation ${correlationId}`;
+                    reject(new Error(`${what} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            this._pending.set(correlationId, { resolve, reject, timer });
+        });
+    }
+    /**
+     * Resolve a pending correlation with a value.
+     * Returns true if the correlationId was found and resolved.
+     */
+    resolve(correlationId, value) {
+        const entry = this._pending.get(correlationId);
+        if (!entry)
+            return false;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        this._pending.delete(correlationId);
+        entry.resolve(value);
+        return true;
+    }
+    /**
+     * Reject a pending correlation with an error.
+     */
+    reject(correlationId, error) {
+        const entry = this._pending.get(correlationId);
+        if (!entry)
+            return false;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        this._pending.delete(correlationId);
+        entry.reject(error);
+        return true;
+    }
+    /**
+     * Check if a correlationId is pending.
+     */
+    has(correlationId) {
+        return this._pending.has(correlationId);
+    }
+    /**
+     * Cancel all pending correlations.
+     */
+    clear() {
+        for (const [id, entry] of this._pending) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            entry.reject(new Error(`Correlation ${id} cancelled`));
+        }
+        this._pending.clear();
+    }
+    get size() {
+        return this._pending.size;
+    }
+}
+
+function createTaskEnvelope(capability, payload, options) {
+    return {
+        type: "task",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        taskId: generateId(),
+        correlationId: generateId(),
+        replyTo: options?.replyTo,
+        capability,
+        payload,
+        tags: options?.tags,
+        priority: options?.priority ?? "medium",
+        metadata: options?.metadata,
+        createdAt: createTimestamp(),
+        createdBy: options?.createdBy,
+        timeout: options?.timeout,
+    };
+}
+function createResultEnvelope(taskId, correlationId, status, payload, error, completedBy, replyTo) {
+    return {
+        type: "result",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        correlationId,
+        taskId,
+        status,
+        payload,
+        error,
+        completedAt: createTimestamp(),
+        completedBy,
+        replyTo,
+    };
+}
+function createStateEnvelope(key, value, version, updatedBy) {
+    return {
+        type: "state",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        key,
+        value,
+        version,
+        updatedBy,
+        updatedAt: createTimestamp(),
+    };
+}
+function createEventEnvelope(category, emittedBy, payload, severity = "info") {
+    return {
+        type: "event",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        eventId: generateId(),
+        severity,
+        category,
+        emittedBy,
+        payload,
+        timestamp: createTimestamp(),
+    };
+}
+function createApprovalRequest(action, context, requestedBy, options) {
+    return {
+        type: "approval_request",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        requestId: generateId(),
+        correlationId: generateId(),
+        action,
+        context,
+        urgency: options?.urgency ?? "medium",
+        requestedBy,
+        requestedAt: createTimestamp(),
+        expiresAt: options?.expiresAt,
+    };
+}
+function createApprovalResponse(requestId, correlationId, decision, respondedBy, reason) {
+    return {
+        type: "approval_response",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        requestId,
+        correlationId,
+        decision,
+        respondedBy,
+        reason,
+        respondedAt: createTimestamp(),
+    };
+}
+function createToolRequest(toolName, args, requestedBy, options) {
+    return {
+        type: "tool_request",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        requestId: generateId(),
+        correlationId: generateId(),
+        replyTo: options?.replyTo,
+        toolName,
+        arguments: args,
+        requestedBy,
+        requestedAt: createTimestamp(),
+    };
+}
+function createToolResponse(requestId, correlationId, status, result, error, respondedBy, replyTo) {
+    return {
+        type: "tool_response",
+        protocol: AGENTS_PROTOCOL_VERSION,
+        requestId,
+        correlationId,
+        status,
+        result,
+        error,
+        respondedBy,
+        respondedAt: createTimestamp(),
+        replyTo,
+    };
+}
+
+/**
+ * Handoff pattern — dispatch tasks to agents and receive results.
+ *
+ * Orchestrators use `dispatch()` to send work. The SDK checks if any
+ * connected agent has the requested capability (via presence-based
+ * service discovery) before dispatching.
+ *
+ * Workers use `onTask()` with a capabilities filter — they only receive
+ * tasks matching their registered capabilities.
+ *
+ * @example
+ * ```typescript
+ * // Orchestrator
+ * const handoff = new Handoff(room);
+ * const result = await handoff.dispatch('summarize', { text }, { waitForResult: true });
+ *
+ * // Worker
+ * const handoff = new Handoff(room);
+ * handoff.onTask(['summarize', 'translate'], async (task, respond) => {
+ *   const output = await processTask(task);
+ *   respond('success', { output });
+ * });
+ * ```
+ */
+class Handoff {
+    constructor(room) {
+        this._correlations = new CorrelationManager();
+        this._warnedMixed = false;
+        this._room = room;
+        // Wire result correlation
+        this._room.on("result", (envelope) => {
+            this._correlations.resolve(envelope.correlationId, envelope);
+        });
+    }
+    /**
+     * Dispatch a task to agents with the given capability.
+     *
+     * Uses presence-based service discovery to verify at least one agent
+     * can handle the capability before dispatching. Throws if no capable
+     * agent is connected (unless `allowNoWorkers` is set).
+     */
+    async dispatch(capability, payload, options) {
+        // Service discovery: check if any agent can handle this capability.
+        // Persistent Presence: findAgents includes offline persistent agents, which
+        // the broker wakes on publish — so they satisfy the gate unless requireOnline.
+        if (!options?.allowNoWorkers) {
+            const capable = this._room.findAgents(capability);
+            const usable = options?.requireOnline
+                ? capable.filter((a) => a.status === undefined || a.status === "online")
+                : capable;
+            if (usable.length === 0) {
+                throw new Error(`No ${options?.requireOnline ? "online " : ""}agent with capability "${capability}" is available. ` +
+                    `Available capabilities: [${this._room.getAvailableCapabilities().join(', ')}]. ` +
+                    `Connected agents: ${this._room.getConnectedAgents().length}. ` +
+                    `Use { allowNoWorkers: true } to dispatch anyway.`);
+            }
+        }
+        const envelope = createTaskEnvelope(capability, payload, {
+            ...options,
+            createdBy: options?.createdBy ?? this._room.agentId,
+            // Reply address: workers publish the result filter-directed to this
+            // room's results subscription
+            replyTo: options?.replyTo ?? this._room.agentId,
+        });
+        this._room.publishTask(envelope);
+        if (options?.waitForResult) {
+            // Fail fast when the outcome is deterministic: if capable workers are
+            // visible and ALL advertise agents-protocol < 2, their results cannot
+            // reach this dispatcher's filtered subscription. Mixed pools proceed
+            // with a warning (presence is eventually consistent).
+            const capable = this._room.findAgents(capability);
+            if (!options?.allowLegacyResponders && capable.length > 0) {
+                const modern = capable.filter((a) => a.protocol >= 2);
+                if (modern.length === 0) {
+                    throw new IncompatibleProtocolError(`Task '${capability}' dispatch with waitForResult`, capable.map((a) => ({ name: a.name, protocol: a.protocol })));
+                }
+                if (modern.length < capable.length && !this._warnedMixed) {
+                    this._warnedMixed = true;
+                    console.warn(`[nolag-agents] Capability '${capability}' has workers on agents-protocol < 2: ` +
+                        capable.filter((a) => a.protocol < 2).map((a) => a.name).join(", ") +
+                        ". Their results may not be delivered — upgrade them.");
+                }
+            }
+            return this._correlations.register(envelope.correlationId, options.timeout, `Task '${capability}' dispatch (${capable.length} capable worker${capable.length === 1 ? "" : "s"} visible). ` +
+                `Likely causes: worker crashed mid-task, worker on agents-protocol < 2 ` +
+                `(results not directed), or the room is not deliverable`);
+        }
+    }
+    onTask(capabilitiesOrHandler, maybeHandler) {
+        // Single-arg form: onTask(handler) receives all tasks
+        const capabilities = typeof capabilitiesOrHandler === "function" ? '*' : capabilitiesOrHandler;
+        const handler = typeof capabilitiesOrHandler === "function" ? capabilitiesOrHandler : maybeHandler;
+        this._room.on("task", (task) => {
+            // Filter by capability unless wildcard
+            if (capabilities !== '*' && !capabilities.includes(task.capability)) {
+                return;
+            }
+            const respond = (status, payload, error) => {
+                const result = createResultEnvelope(task.taskId, task.correlationId, status, payload, error, this._room.agentId, 
+                // Direct the result to the dispatcher's filter sub-topic
+                task.replyTo ?? task.createdBy);
+                this._room.publishResult(result);
+            };
+            handler(task, respond);
+        });
+    }
+    /**
+     * Get agents capable of handling a specific task type.
+     * Delegates to the room's presence-based service discovery.
+     */
+    getCapableAgents(capability) {
+        return this._room.findAgents(capability);
+    }
+    /** Cancel all pending correlations */
+    dispose() {
+        this._correlations.clear();
+    }
+}
+
+/**
+ * Inbox pattern — per-agent durable message queues.
+ *
+ * Agents send direct messages to other agents via their inbox.
+ * Messages are persisted and replayed on reconnect (requires persistent sessions).
+ */
+class Inbox {
+    constructor(room, agentId) {
+        this._room = room;
+        this._agentId = agentId;
+    }
+    /**
+     * Send a message to another agent's inbox.
+     */
+    send(to, payload) {
+        const message = {
+            messageId: generateId(),
+            from: this._agentId,
+            to,
+            payload,
+            createdAt: createTimestamp(),
+        };
+        this._room.publishInbox(message);
+    }
+    /**
+     * Register a handler for incoming inbox messages.
+     */
+    onMessage(handler) {
+        this._room.on("inbox", (envelope) => {
+            const msg = envelope;
+            if (msg.to === this._agentId) {
+                handler(msg);
+            }
+        });
+    }
+}
+
+/**
+ * Blackboard pattern — shared state across agents.
+ *
+ * Agents read and write key-value pairs visible to all room participants.
+ * Uses retained messages so state is available on join.
+ */
+class Blackboard {
+    constructor(room, agentId) {
+        this._state = new Map();
+        this._room = room;
+        this._agentId = agentId;
+        this._room.on("stateChange", (envelope) => {
+            this._state.set(envelope.key, envelope);
+        });
+    }
+    /**
+     * Set a shared state value.
+     */
+    set(key, value) {
+        const existing = this._state.get(key);
+        const version = existing ? existing.version + 1 : 1;
+        const envelope = createStateEnvelope(key, value, version, this._agentId);
+        this._state.set(key, envelope);
+        this._room.publishState(envelope);
+    }
+    /**
+     * Get a shared state value.
+     */
+    get(key) {
+        return this._state.get(key)?.value;
+    }
+    /**
+     * Get the full state envelope for a key.
+     */
+    getEnvelope(key) {
+        return this._state.get(key);
+    }
+    /**
+     * Get all state entries.
+     */
+    getAll() {
+        return this._state;
+    }
+    /**
+     * Register a handler for state changes on a specific key.
+     */
+    onChange(key, handler) {
+        this._room.on("stateChange", (envelope) => {
+            if (envelope.key === key) {
+                handler(envelope);
+            }
+        });
+    }
+}
+
+/**
+ * Observe pattern — emit and listen to observability events.
+ *
+ * Agents emit structured events; observers/dashboards subscribe to the stream.
+ * Events have severity, category, and emittedBy for filtering.
+ *
+ * `on(handler, filter)` discards non-matching events after they arrive, which
+ * is fine for a quiet room and wasteful for a loud one. `setFilters` moves the
+ * same selection to the broker, so an observer is only sent the categories it
+ * asked for. Emit with a matching `filter` for that to work — see `emit`.
+ */
+class Observe {
+    constructor(room, emittedBy) {
+        this._room = room;
+        this._emittedBy = emittedBy;
+    }
+    /**
+     * Emit an observability event.
+     *
+     * Pass `{ filter: category }` to route it server-side, so observers that
+     * called `setFilters` receive only the categories they subscribed to.
+     * Observers with no filters still receive it either way, so tagging is safe
+     * to adopt without coordinating with them.
+     */
+    emit(category, payload, severity = "info", opts) {
+        const envelope = createEventEnvelope(category, this._emittedBy, payload, severity);
+        this._room.publishEvent(envelope, opts);
+    }
+    /**
+     * Replace the observer's server-side event filters.
+     *
+     * Scoped to the events topic, so it never disturbs the room's other
+     * subscriptions — notably `inbox`, whose messages are published unfiltered
+     * and would stop arriving if this were applied room-wide.
+     *
+     * An empty array restores the wildcard subscription, which receives every
+     * event on the room.
+     */
+    setFilters(values) {
+        this._room.setFilters(values, { topic: "events" });
+    }
+    /**
+     * Listen for events, optionally filtered by category or severity.
+     */
+    on(handler, filter) {
+        this._room.on("event", (envelope) => {
+            if (filter?.category && envelope.category !== filter.category)
+                return;
+            if (filter?.severity && envelope.severity !== filter.severity)
+                return;
+            handler(envelope);
+        });
+    }
+}
+
+/**
+ * Approve pattern — human-in-the-loop approval gates.
+ *
+ * Agents request approval before taking actions; humans (or other agents)
+ * approve or reject via the approval topic.
+ */
+class Approve {
+    constructor(room, agentId) {
+        this._correlations = new CorrelationManager();
+        this._room = room;
+        this._agentId = agentId;
+        // Wire approval response correlation
+        this._room.on("approvalResponse", (envelope) => {
+            this._correlations.resolve(envelope.correlationId, envelope);
+        });
+    }
+    /**
+     * Request approval for an action. Returns the approval response.
+     */
+    async request(action, context, options) {
+        const envelope = createApprovalRequest(action, context, this._agentId, {
+            urgency: options?.urgency,
+            expiresAt: options?.expiresAt,
+        });
+        this._room.publishApproval(envelope);
+        return this._correlations.register(envelope.correlationId, options?.timeout);
+    }
+    /**
+     * Register a handler for incoming approval requests.
+     * The handler receives the request and a respond function.
+     */
+    onRequest(handler) {
+        this._room.on("approvalRequest", (request) => {
+            const respond = (decision, reason) => {
+                const response = createApprovalResponse(request.requestId, request.correlationId, decision, this._agentId, reason);
+                this._room.publishApproval(response);
+            };
+            handler(request, respond);
+        });
+    }
+    /** Cancel all pending correlations */
+    dispose() {
+        this._correlations.clear();
+    }
+}
+
+/**
+ * Tools pattern — typed RPC over pub/sub for tool invocations.
+ *
+ * Agents register tool handlers; callers invoke tools and receive
+ * correlated responses.
+ */
+class Tools {
+    constructor(room, agentId) {
+        this._correlations = new CorrelationManager();
+        this._handlers = new Map();
+        this._warnedMixed = false;
+        this._room = room;
+        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;
+            if (!handler) {
+                // Tool requests are load-balanced to EVERY group in the room, so
+                // agents legitimately receive requests meant for other tool servers.
+                // Stay silent unless this agent plausibly owns the tool:
+                //  - pure requesters (zero handlers) never answer
+                //  - servers answer only within their own namespace (the prefix
+                //    before the first '.', e.g. 'backend.*', 'chemistry.*') — a
+                //    'backend.*' server NACKing 'chemistry.analyze' would race and
+                //    beat the real chemistry server's response
+                if (!this._ownsNamespace(envelope.toolName))
+                    return;
+                // A tool SERVER missing a handler in ITS OWN namespace NACKs instead
+                // of silently ignoring — silence means the requester burns its full
+                // timeout. (Requires homogeneous tool sets within a loadBalanceGroup
+                // — see AGENTS-PROTOCOL.md.)
+                const nack = createToolResponse(envelope.requestId, envelope.correlationId, "error", null, {
+                    code: "NO_HANDLER",
+                    message: `Agent '${this._agentId}' has no handler for tool '${envelope.toolName}'`,
+                }, this._agentId, replyTo);
+                this._room.publishTools(nack);
+                return;
+            }
+            try {
+                const result = await handler(envelope.arguments);
+                const response = createToolResponse(envelope.requestId, envelope.correlationId, "success", result, undefined, this._agentId, replyTo);
+                this._room.publishTools(response);
+            }
+            catch (err) {
+                const response = createToolResponse(envelope.requestId, envelope.correlationId, "error", null, {
+                    code: "TOOL_ERROR",
+                    message: err instanceof Error ? err.message : String(err),
+                }, this._agentId, replyTo);
+                this._room.publishTools(response);
+            }
+        });
+    }
+    /**
+     * Register a tool handler.
+     */
+    register(toolName, handler) {
+        this._handlers.set(toolName, handler);
+    }
+    /** 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;
+        for (const name of this._handlers.keys()) {
+            const handlerNs = name.includes(".") ? name.slice(0, name.indexOf(".")) : null;
+            if (handlerNs === ns)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Invoke a remote tool and wait for the response.
+     */
+    async invoke(toolName, args, options) {
+        // Fail fast when the outcome is deterministic: tool servers are visible
+        // in presence; if some exist and ALL advertise protocol < 2, their
+        // replies cannot reach this requester. Mixed pools proceed with a
+        // warning (presence is eventually consistent — hard-failing on one
+        // stale entry would flake).
+        const servers = this._room
+            .getConnectedAgents()
+            .filter((a) => a.role === "tool-server");
+        if (!options?.allowLegacyResponders && servers.length > 0) {
+            const modern = servers.filter((a) => a.protocol >= 2);
+            if (modern.length === 0) {
+                throw new IncompatibleProtocolError(`Tool '${toolName}' invocation`, servers.map((a) => ({ name: a.name, protocol: a.protocol })));
+            }
+            if (modern.length < servers.length && !this._warnedMixed) {
+                this._warnedMixed = true;
+                console.warn(`[nolag-agents] Room '${this._room.name}' has tool servers on agents-protocol < 2: ` +
+                    servers.filter((a) => a.protocol < 2).map((a) => a.name).join(", ") +
+                    ". Their replies may not be delivered — upgrade them.");
+            }
+        }
+        // replyTo is the room's agentId — the filter sub-topic this room's
+        // results subscription listens on. (this._agentId may differ when a
+        // caller attributes requests to a logical agent; delivery must use the
+        // address that is actually subscribed.)
+        const envelope = createToolRequest(toolName, args, this._agentId, {
+            replyTo: this._room.agentId,
+        });
+        this._room.publishTools(envelope);
+        const serverCount = servers.length;
+        return this._correlations.register(envelope.correlationId, options?.timeout, `Tool '${toolName}' invocation in room '${this._room.name}' ` +
+            `(${serverCount} tool-server${serverCount === 1 ? "" : "s"} visible). ` +
+            `Likely causes: no agent has this tool registered (pre-0.3.0 responders ` +
+            `don't NACK), the responder is offline, or the room is not deliverable ` +
+            `(watch the room 'error' events)`);
+    }
+    /** Cancel all pending correlations */
+    dispose() {
+        this._correlations.clear();
+        this._handlers.clear();
+    }
+}
+
+/** Standard tag prefixes for agent coordination */
+const TAG_PREFIX = {
+    CAPABILITY: "capability",
+    PRIORITY: "priority",
+    ROLE: "role",
+    SEVERITY: "severity",
+    URGENCY: "urgency",
+    TENANT: "tenant",
+};
+/** Boolean flags (used as standalone tags, no prefix) */
+const TAG_FLAGS = {
+    REQUIRES_HUMAN: "requires_human",
+    REQUIRES_AUDIT: "requires_audit",
+};
+/** Helper to create prefixed tags */
+function tag(prefix, value) {
+    return `${prefix}:${value}`;
+}
+
+export { AGENTS_PROTOCOL_VERSION, AgentRoom, Approve, Blackboard, CorrelationManager, EventEmitter, Handoff, Inbox, IncompatibleProtocolError, NoLagAgents, Observe, TAG_FLAGS, TAG_PREFIX, Tools, createApprovalRequest, createApprovalResponse, createEventEnvelope, createResultEnvelope, createStateEnvelope, createTaskEnvelope, createToolRequest, createToolResponse, tag };
+//# sourceMappingURL=react-native.js.map