@nolag/agents 1.1.1 → 1.2.0

package/dist/index.mjs

@@ -58,6 +58,97 @@ class EventEmitter {
     }
 }
 
+/**
+ * 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) */
@@ -83,6 +174,19 @@ const LOBBY_REFRESH_DELAY_MS = 2000;
  *  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).
  *
@@ -109,13 +213,17 @@ const AGENTS_PROTOCOL_VERSION = 2;
  */
 class AgentRoom extends EventEmitter {
     /** @internal */
-    constructor(name, roomContext, log, agentId, appName, isConnected, presence) {
+    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;
@@ -123,6 +231,10 @@ class AgentRoom extends EventEmitter {
         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
@@ -187,12 +299,15 @@ class AgentRoom extends EventEmitter {
     // PUBLISH (with automatic agentId injection)
     // ============================================================
     /** Publish to the tasks topic */
-    publishTask(envelope) {
+    publishTask(envelope, opts) {
         // Auto-set createdBy if not set
         if (!envelope.createdBy) {
             envelope.createdBy = this.agentId;
         }
-        this._publish(TOPIC_TASKS, envelope);
+        // 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) {
@@ -210,24 +325,24 @@ class AgentRoom extends EventEmitter {
         }
     }
     /** Publish to the state topic (retained) */
-    publishState(data) {
+    publishState(data, opts) {
         // Auto-set updatedBy if not set
         if (!data.updatedBy) {
             data.updatedBy = this.agentId;
         }
-        this._publish(TOPIC_STATE, data, { retain: true });
+        this._publish(TOPIC_STATE, data, { retain: true, ...filterEmitOptions(opts) });
     }
     /** Publish to the events topic */
-    publishEvent(data) {
+    publishEvent(data, opts) {
         // Auto-set emittedBy if not set
         if (!data.emittedBy) {
             data.emittedBy = this.agentId;
         }
-        this._publish(TOPIC_EVENTS, data);
+        this._publish(TOPIC_EVENTS, data, filterEmitOptions(opts));
     }
     /** Publish to the inbox topic */
-    publishInbox(data) {
-        this._publish(TOPIC_INBOX, data);
+    publishInbox(data, opts) {
+        this._publish(TOPIC_INBOX, data, filterEmitOptions(opts));
     }
     /**
      * Publish a tool message.
@@ -235,16 +350,84 @@ class AgentRoom extends EventEmitter {
      * replicas). Responses are directed to the requester on the results topic
      * via filter — never load-balanced, never broadcast.
      */
-    publishTools(data) {
+    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);
+        this._publish(TOPIC_TOOLS, data, filterEmitOptions(opts));
     }
     /** Publish to the approval topic (retained) */
-    publishApproval(data) {
-        this._publish(TOPIC_APPROVAL, data, { retain: true });
+    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)
@@ -325,13 +508,24 @@ class AgentRoom extends EventEmitter {
     }
     _publish(topic, data, options) {
         this._log(`publish to ${topic} in room ${this.name}`);
-        if (options) {
+        // 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 {
@@ -367,8 +561,8 @@ class AgentRoom extends EventEmitter {
         // 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._roomContext.subscribe(TOPIC_TASKS);
-        this._roomContext.subscribe(TOPIC_TOOLS);
+        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
@@ -383,9 +577,13 @@ class AgentRoom extends EventEmitter {
         // 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 = [TOPIC_STATE, TOPIC_EVENTS, TOPIC_INBOX, TOPIC_APPROVAL];
-        for (const topic of broadcastTopics) {
-            this._roomContext.subscribe(topic, { loadBalance: false });
+        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 = [
@@ -436,58 +634,6 @@ class AgentRoom extends EventEmitter {
     }
 }
 
-/**
- * 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();
-}
-// ============ Wrapper registry ============
-// One wrapper instance per (client, appName): two wrappers sharing an app on
-// one connection would collide on topics, presence and the lobby.
-// Warn (not throw): HMR and tests legitimately construct before disposing.
-const wrapperRegistry = new WeakMap();
-/** Register a wrapper against a client + appName; warns on collision. */
-function registerWrapper(client, appName, wrapperName) {
-    let apps = wrapperRegistry.get(client);
-    if (!apps) {
-        apps = new Map();
-        wrapperRegistry.set(client, apps);
-    }
-    const existing = apps.get(appName);
-    if (existing) {
-        console.warn(`[${wrapperName}] Another wrapper (${existing}) is already attached to this client for app "${appName}". ` +
-            `Use one wrapper per (client, app) — detach the other instance first.`);
-    }
-    apps.set(appName, wrapperName);
-}
-/** Release a wrapper's (client, appName) registration on detach. */
-function releaseWrapper(client, appName) {
-    wrapperRegistry.get(client)?.delete(appName);
-}
-
 /**
  * NoLagAgents — high-level agent coordination SDK built on @nolag/js-sdk.
  *
@@ -759,12 +905,16 @@ class NoLagAgents extends EventEmitter {
      * Get or create an AgentRoom wrapper.
      * If the room hasn't been joined yet, it will be joined automatically.
      */
-    room(name) {
+    room(name, opts) {
         this._assertUsable();
         const existing = this._rooms.get(name);
-        if (existing)
+        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);
+        }
+        return this._joinRoomInternal(name, opts?.filters);
     }
     // ============ Lobby (cross-room presence observation) ============
     /**
@@ -802,10 +952,10 @@ class NoLagAgents extends EventEmitter {
         }
     }
     // ============ Private: Room Setup ============
-    _joinRoomInternal(name) {
+    _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);
+        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;
     }
@@ -1347,6 +1497,11 @@ class Blackboard {
  *
  * 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) {
@@ -1355,10 +1510,28 @@ class Observe {
     }
     /**
      * 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") {
+    emit(category, payload, severity = "info", opts) {
         const envelope = createEventEnvelope(category, this._emittedBy, payload, severity);
-        this._room.publishEvent(envelope);
+        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.