@nolag/agents 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1121 @@
+'use strict';
+
+var jsSdk = require('@nolag/js-sdk');
+
+/**
+ * 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 {
+                handler(...args);
+            }
+            catch (e) {
+                console.error(`Error in ${String(event)} handler:`, e);
+            }
+        }
+    }
+    listenerCount(event) {
+        return this._handlers.get(event)?.size ?? 0;
+    }
+}
+
+/** 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";
+
+/**
+ * AgentRoom — wraps a RoomContext from @nolag/js-sdk.
+ *
+ * Provides typed pub/sub for agent coordination topics,
+ * presence-based service discovery, and capability routing.
+ *
+ * @example
+ * ```typescript
+ * const room = agents.room('default-workflow');
+ *
+ * // Service discovery - see who's connected
+ * const agents = room.getConnectedAgents();
+ * const summarizers = room.findAgents('summarize');
+ *
+ * // Capability-filtered task handler
+ * room.on('task', (envelope) => console.log('New task:', envelope));
+ * ```
+ */
+class AgentRoom extends EventEmitter {
+    constructor(name, roomContext, client, log, agentId, presence) {
+        super();
+        /** Registry of connected agents discovered via presence */
+        this._agents = new Map();
+        this.name = name;
+        this.agentId = agentId;
+        this._roomContext = roomContext;
+        this._client = client;
+        this._log = log;
+        this._presence = presence;
+        this._wireTopicListeners();
+        this._wirePresenceListeners();
+        // Set presence if provided
+        if (presence) {
+            this._log(`setting presence in room ${name}:`, presence);
+            this._roomContext.setPresence(presence);
+        }
+        // Fetch initial presence snapshot
+        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 */
+    setPresence(data) {
+        this._presence = data;
+        this._log(`updating presence in room ${this.name}`);
+        this._roomContext.setPresence(data);
+    }
+    /** 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 [];
+        }
+    }
+    /**
+     * @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 to the tasks topic */
+    publishTask(envelope) {
+        // Auto-set createdBy if not set
+        if (!envelope.createdBy) {
+            envelope.createdBy = this.agentId;
+        }
+        this._publish(TOPIC_TASKS, envelope);
+    }
+    /** Publish to the results topic */
+    publishResult(envelope) {
+        // Auto-set completedBy if not set
+        if (!envelope.completedBy) {
+            envelope.completedBy = this.agentId;
+        }
+        this._publish(TOPIC_RESULTS, envelope);
+    }
+    /** Publish to the state topic (retained) */
+    publishState(data) {
+        // Auto-set updatedBy if not set
+        if (!data.updatedBy) {
+            data.updatedBy = this.agentId;
+        }
+        this._publish(TOPIC_STATE, data, { retain: true });
+    }
+    /** Publish to the events topic */
+    publishEvent(data) {
+        // Auto-set emittedBy if not set
+        if (!data.emittedBy) {
+            data.emittedBy = this.agentId;
+        }
+        this._publish(TOPIC_EVENTS, data);
+    }
+    /** Publish to the inbox topic */
+    publishInbox(data) {
+        this._publish(TOPIC_INBOX, data);
+    }
+    /** Publish to the tools topic */
+    publishTools(data) {
+        this._publish(TOPIC_TOOLS, data);
+    }
+    /** Publish to the approval topic (retained) */
+    publishApproval(data) {
+        this._publish(TOPIC_APPROVAL, data, { retain: true });
+    }
+    // ============================================================
+    // INTERNALS
+    // ============================================================
+    _publish(topic, data, options) {
+        this._log(`publish to ${topic} in room ${this.name}`);
+        if (options) {
+            this._roomContext.emit(topic, data, options);
+        }
+        else {
+            this._roomContext.emit(topic, data);
+        }
+    }
+    _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(),
+        };
+    }
+    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
+        }
+    }
+    _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(),
+                    };
+                    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(),
+                    };
+                    this._agents.set(id, agent);
+                    this.emit('presenceUpdate', id, data);
+                }
+            }
+        });
+    }
+    _wireTopicListeners() {
+        // All topics that need broker subscriptions
+        const allTopics = [
+            TOPIC_TASKS,
+            TOPIC_RESULTS,
+            TOPIC_STATE,
+            TOPIC_EVENTS,
+            TOPIC_INBOX,
+            TOPIC_TOOLS,
+            TOPIC_APPROVAL,
+        ];
+        for (const topic of allTopics) {
+            this._roomContext.subscribe(topic);
+        }
+        // Simple 1:1 mappings
+        const simpleMap = [
+            { topic: TOPIC_TASKS, event: "task" },
+            { topic: TOPIC_RESULTS, event: "result" },
+            { topic: TOPIC_STATE, event: "stateChange" },
+            { topic: TOPIC_EVENTS, event: "event" },
+            { topic: TOPIC_INBOX, event: "inbox" },
+        ];
+        for (const { topic, event } of simpleMap) {
+            this._roomContext.on(topic, (data) => {
+                this._log(`received ${topic} in room ${this.name}`);
+                this.emit(event, data);
+            });
+        }
+        // Multiplexed: approval topic carries requests + responses
+        this._roomContext.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);
+            }
+        });
+        // Multiplexed: tools topic carries requests + responses
+        this._roomContext.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);
+            }
+        });
+    }
+}
+
+/**
+ * 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();
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { NoLagAgents } from '@nolag/agents';
+ *
+ * const agents = new NoLagAgents(token, {
+ *   appName: 'my-workflow',
+ *   agentId: 'worker-1',
+ *   presence: { name: 'worker-1', role: 'agent', capabilities: ['summarize'] },
+ * });
+ * await agents.connect();
+ *
+ * const room = agents.room('default-workflow');
+ * room.handoff.onTask(['summarize'], async (task, respond) => {
+ *   const result = await summarize(task.payload);
+ *   respond('success', { result });
+ * });
+ * ```
+ */
+class NoLagAgents extends EventEmitter {
+    constructor(token, options = {}) {
+        super();
+        this._client = null;
+        this._appContext = null;
+        this._rooms = new Map();
+        this._connected = false;
+        this._token = token;
+        this._options = {
+            appName: options.appName ?? DEFAULT_APP_NAME,
+            agentId: options.agentId ?? generateId(),
+            debug: options.debug ?? false,
+            rooms: options.rooms ?? [DEFAULT_ROOM],
+            lobby: options.lobby,
+            presence: options.presence,
+            clientOptions: options.clientOptions,
+        };
+        this._log = createLogger("NoLagAgents", this._options.debug);
+    }
+    /** The agent's unique ID */
+    get agentId() {
+        return this._options.agentId;
+    }
+    /** Whether the client is connected */
+    get connected() {
+        return this._connected;
+    }
+    /** Map of joined rooms */
+    get rooms() {
+        return this._rooms;
+    }
+    /** Connect to NoLag and join configured rooms */
+    async connect() {
+        this._log("connecting...");
+        this._client = jsSdk.NoLag(this._token, {
+            ...this._options.clientOptions,
+        });
+        this._appContext = this._client.setApp(this._options.appName);
+        this._client.on("connected", () => {
+            this._connected = true;
+            this._log("connected");
+            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");
+            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)
+        if (this._options.lobby) {
+            await this.subscribeLobby(this._options.lobby);
+        }
+    }
+    /**
+     * Subscribe to a lobby for cross-room presence observation.
+     * Lobby presence events are forwarded to all AgentRooms.
+     *
+     * Returns the initial presence snapshot.
+     */
+    async subscribeLobby(lobbySlug) {
+        if (!this._appContext) {
+            throw new Error("Not connected. Call connect() before subscribing to lobbies.");
+        }
+        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);
+                }
+            }
+        });
+        try {
+            const initialState = await lobby.subscribe();
+            this._log(`lobby subscribed, initial state:`, Object.keys(initialState || {}));
+            return initialState || {};
+        }
+        catch (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;
+    }
+    /**
+     * Get or create an AgentRoom wrapper.
+     * If the room hasn't been joined yet, it will be joined automatically.
+     */
+    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.");
+        }
+        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;
+    }
+}
+
+/**
+ * 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) {
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            if (timeoutMs && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    this._pending.delete(correlationId);
+                    reject(new Error(`Correlation ${correlationId} 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",
+        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) {
+    return {
+        type: "result",
+        correlationId,
+        taskId,
+        status,
+        payload,
+        error,
+        completedAt: createTimestamp(),
+        completedBy,
+    };
+}
+function createStateEnvelope(key, value, version, updatedBy) {
+    return {
+        type: "state",
+        key,
+        value,
+        version,
+        updatedBy,
+        updatedAt: createTimestamp(),
+    };
+}
+function createEventEnvelope(category, emittedBy, payload, severity = "info") {
+    return {
+        type: "event",
+        eventId: generateId(),
+        severity,
+        category,
+        emittedBy,
+        payload,
+        timestamp: createTimestamp(),
+    };
+}
+function createApprovalRequest(action, context, requestedBy, options) {
+    return {
+        type: "approval_request",
+        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",
+        requestId,
+        correlationId,
+        decision,
+        respondedBy,
+        reason,
+        respondedAt: createTimestamp(),
+    };
+}
+function createToolRequest(toolName, args, requestedBy, options) {
+    return {
+        type: "tool_request",
+        requestId: generateId(),
+        correlationId: generateId(),
+        replyTo: options?.replyTo,
+        toolName,
+        arguments: args,
+        requestedBy,
+        requestedAt: createTimestamp(),
+    };
+}
+function createToolResponse(requestId, correlationId, status, result, error, respondedBy) {
+    return {
+        type: "tool_response",
+        requestId,
+        correlationId,
+        status,
+        result,
+        error,
+        respondedBy,
+        respondedAt: createTimestamp(),
+    };
+}
+
+/**
+ * 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._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
+        if (!options?.allowNoWorkers) {
+            const capable = this._room.findAgents(capability);
+            if (capable.length === 0) {
+                throw new Error(`No agent with capability "${capability}" is connected. ` +
+                    `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: this._room.agentId,
+        });
+        this._room.publishTask(envelope);
+        if (options?.waitForResult) {
+            return this._correlations.register(envelope.correlationId, options.timeout);
+        }
+    }
+    /**
+     * Register a handler for incoming tasks, filtered by capabilities.
+     *
+     * Only tasks whose `capability` field matches one of the provided
+     * capabilities will be delivered to the handler. Non-matching tasks
+     * are silently ignored.
+     *
+     * @param capabilities - Array of capabilities this worker handles.
+     *                       Pass `'*'` to receive all tasks.
+     * @param handler - Async handler called with the task and a respond function.
+     */
+    onTask(capabilities, handler) {
+        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);
+                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.
+ */
+class Observe {
+    constructor(room, emittedBy) {
+        this._room = room;
+        this._emittedBy = emittedBy;
+    }
+    /**
+     * Emit an observability event.
+     */
+    emit(category, payload, severity = "info") {
+        const envelope = createEventEnvelope(category, this._emittedBy, payload, severity);
+        this._room.publishEvent(envelope);
+    }
+    /**
+     * 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._room = room;
+        this._agentId = agentId;
+        // Wire response correlation
+        this._room.on("toolResponse", (envelope) => {
+            this._correlations.resolve(envelope.correlationId, envelope);
+        });
+        // Wire request handling
+        this._room.on("toolRequest", async (envelope) => {
+            const handler = this._handlers.get(envelope.toolName);
+            if (!handler)
+                return;
+            try {
+                const result = await handler(envelope.arguments);
+                const response = createToolResponse(envelope.requestId, envelope.correlationId, "success", result, undefined, this._agentId);
+                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);
+                this._room.publishTools(response);
+            }
+        });
+    }
+    /**
+     * Register a tool handler.
+     */
+    register(toolName, handler) {
+        this._handlers.set(toolName, handler);
+    }
+    /**
+     * Invoke a remote tool and wait for the response.
+     */
+    async invoke(toolName, args, options) {
+        const envelope = createToolRequest(toolName, args, this._agentId);
+        this._room.publishTools(envelope);
+        return this._correlations.register(envelope.correlationId, options?.timeout);
+    }
+    /** 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}`;
+}
+
+exports.AgentRoom = AgentRoom;
+exports.Approve = Approve;
+exports.Blackboard = Blackboard;
+exports.CorrelationManager = CorrelationManager;
+exports.EventEmitter = EventEmitter;
+exports.Handoff = Handoff;
+exports.Inbox = Inbox;
+exports.NoLagAgents = NoLagAgents;
+exports.Observe = Observe;
+exports.TAG_FLAGS = TAG_FLAGS;
+exports.TAG_PREFIX = TAG_PREFIX;
+exports.Tools = Tools;
+exports.createApprovalRequest = createApprovalRequest;
+exports.createApprovalResponse = createApprovalResponse;
+exports.createEventEnvelope = createEventEnvelope;
+exports.createResultEnvelope = createResultEnvelope;
+exports.createStateEnvelope = createStateEnvelope;
+exports.createTaskEnvelope = createTaskEnvelope;
+exports.createToolRequest = createToolRequest;
+exports.createToolResponse = createToolResponse;
+exports.tag = tag;
+//# sourceMappingURL=index.cjs.map