@nolag/agents 0.1.1 → 0.4.0

package/dist/index.cjs

@@ -68,6 +68,10 @@ const TOPIC_TOOLS = "tools";
 const TOPIC_APPROVAL = "approval";
 /** Default room for agent coordination */
 const DEFAULT_ROOM = "default-workflow";
+/** Agents-protocol version: 2 = directed replies (filter-routed results),
+ *  NO_HANDLER NACKs, presence protocol advertisement. Absent/1 = legacy
+ *  broadcast replies (pre-0.2.0 SDKs). */
+const AGENTS_PROTOCOL_VERSION = 2;
 
 /**
  * AgentRoom — wraps a RoomContext from @nolag/js-sdk.
@@ -100,10 +104,13 @@ class AgentRoom extends EventEmitter {
         this._presence = presence;
         this._wireTopicListeners();
         this._wirePresenceListeners();
-        // Set presence if provided
+        // Set presence if provided (with the SDK's protocol version advertised
+        // so counterparts can detect incompatible reply semantics)
         if (presence) {
-            this._log(`setting presence in room ${name}:`, presence);
-            this._roomContext.setPresence(presence);
+            const withProtocol = { protocol: AGENTS_PROTOCOL_VERSION, ...presence };
+            this._presence = withProtocol;
+            this._log(`setting presence in room ${name}:`, withProtocol);
+            this._roomContext.setPresence(withProtocol);
         }
         // Fetch initial presence snapshot
         this._fetchInitialPresence();
@@ -136,11 +143,12 @@ class AgentRoom extends EventEmitter {
     // ============================================================
     // PRESENCE
     // ============================================================
-    /** Update this agent's presence data */
+    /** Update this agent's presence data (protocol version auto-injected) */
     setPresence(data) {
-        this._presence = data;
+        const withProtocol = { protocol: AGENTS_PROTOCOL_VERSION, ...data };
+        this._presence = withProtocol;
         this._log(`updating presence in room ${this.name}`);
-        this._roomContext.setPresence(data);
+        this._roomContext.setPresence(withProtocol);
     }
     /** Fetch current presence snapshot for this room */
     async fetchPresence() {
@@ -178,13 +186,20 @@ class AgentRoom extends EventEmitter {
         }
         this._publish(TOPIC_TASKS, envelope);
     }
-    /** Publish to the results topic */
+    /** 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;
         }
-        this._publish(TOPIC_RESULTS, envelope);
+        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) {
@@ -206,8 +221,17 @@ class AgentRoom extends EventEmitter {
     publishInbox(data) {
         this._publish(TOPIC_INBOX, data);
     }
-    /** Publish to the tools topic */
+    /**
+     * 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) {
+        if (data?.type === "tool_response" && typeof data.replyTo === "string" && data.replyTo) {
+            this._publish(TOPIC_RESULTS, data, { filter: data.replyTo });
+            return;
+        }
         this._publish(TOPIC_TOOLS, data);
     }
     /** Publish to the approval topic (retained) */
@@ -235,6 +259,8 @@ class AgentRoom extends EventEmitter {
             capabilities: presence.capabilities || [],
             metadata: presence.metadata,
             connectedAt: actor.joinedAt || Date.now(),
+            protocol: typeof presence.protocol === 'number' ? presence.protocol : 1,
+            status: actor.status,
         };
     }
     async _fetchInitialPresence() {
@@ -270,6 +296,7 @@ class AgentRoom extends EventEmitter {
                         capabilities: data.capabilities || [],
                         metadata: data.metadata,
                         connectedAt: Date.now(),
+                        protocol: typeof data.protocol === 'number' ? data.protocol : 1,
                     };
                     this._agents.set(id, agent);
                     this._log(`agent joined room ${this.name}:`, agent.name, agent.capabilities);
@@ -301,6 +328,7 @@ class AgentRoom extends EventEmitter {
                         capabilities: data.capabilities || existing?.capabilities || [],
                         metadata: data.metadata || existing?.metadata,
                         connectedAt: existing?.connectedAt || Date.now(),
+                        protocol: typeof data.protocol === 'number' ? data.protocol : (existing?.protocol ?? 1),
                     };
                     this._agents.set(id, agent);
                     this.emit('presenceUpdate', id, data);
@@ -309,23 +337,33 @@ class AgentRoom extends EventEmitter {
         });
     }
     _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);
+        // 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._roomContext.subscribe(TOPIC_TASKS);
+        this._roomContext.subscribe(TOPIC_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 = [TOPIC_STATE, TOPIC_EVENTS, TOPIC_INBOX, TOPIC_APPROVAL];
+        for (const topic of broadcastTopics) {
+            this._roomContext.subscribe(topic, { loadBalance: false });
         }
         // 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" },
@@ -336,6 +374,17 @@ class AgentRoom extends EventEmitter {
                 this.emit(event, data);
             });
         }
+        // Multiplexed: results topic carries task results AND tool responses,
+        // both filter-directed to this agent.
+        this._roomContext.on(TOPIC_RESULTS, (data) => {
+            this._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._roomContext.on(TOPIC_APPROVAL, (data) => {
             this._log(`received ${TOPIC_APPROVAL} in room ${this.name}`);
@@ -346,7 +395,9 @@ class AgentRoom extends EventEmitter {
                 this.emit("approvalRequest", data);
             }
         });
-        // Multiplexed: tools topic carries requests + responses
+        // Tools topic carries requests; tool_response is still accepted here for
+        // backward compatibility with responders on older SDK versions (their
+        // responses are only reliable when the requester is not load-balanced).
         this._roomContext.on(TOPIC_TOOLS, (data) => {
             this._log(`received ${TOPIC_TOOLS} in room ${this.name}`);
             if (data?.type === "tool_response") {
@@ -584,6 +635,24 @@ class NoLagAgents extends EventEmitter {
     }
 }
 
+/**
+ * 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.
@@ -596,13 +665,16 @@ class CorrelationManager {
      * Register a pending correlation. Returns a promise that resolves
      * when `resolve()` is called with the matching correlationId.
      */
-    register(correlationId, timeoutMs) {
+    register(correlationId, timeoutMs, context) {
         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`));
+                    // 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 });
@@ -660,6 +732,7 @@ class CorrelationManager {
 function createTaskEnvelope(capability, payload, options) {
     return {
         type: "task",
+        protocol: AGENTS_PROTOCOL_VERSION,
         taskId: generateId(),
         correlationId: generateId(),
         replyTo: options?.replyTo,
@@ -673,9 +746,10 @@ function createTaskEnvelope(capability, payload, options) {
         timeout: options?.timeout,
     };
 }
-function createResultEnvelope(taskId, correlationId, status, payload, error, completedBy) {
+function createResultEnvelope(taskId, correlationId, status, payload, error, completedBy, replyTo) {
     return {
         type: "result",
+        protocol: AGENTS_PROTOCOL_VERSION,
         correlationId,
         taskId,
         status,
@@ -683,11 +757,13 @@ function createResultEnvelope(taskId, correlationId, status, payload, error, com
         error,
         completedAt: createTimestamp(),
         completedBy,
+        replyTo,
     };
 }
 function createStateEnvelope(key, value, version, updatedBy) {
     return {
         type: "state",
+        protocol: AGENTS_PROTOCOL_VERSION,
         key,
         value,
         version,
@@ -698,6 +774,7 @@ function createStateEnvelope(key, value, version, updatedBy) {
 function createEventEnvelope(category, emittedBy, payload, severity = "info") {
     return {
         type: "event",
+        protocol: AGENTS_PROTOCOL_VERSION,
         eventId: generateId(),
         severity,
         category,
@@ -709,6 +786,7 @@ function createEventEnvelope(category, emittedBy, payload, severity = "info") {
 function createApprovalRequest(action, context, requestedBy, options) {
     return {
         type: "approval_request",
+        protocol: AGENTS_PROTOCOL_VERSION,
         requestId: generateId(),
         correlationId: generateId(),
         action,
@@ -722,6 +800,7 @@ function createApprovalRequest(action, context, requestedBy, options) {
 function createApprovalResponse(requestId, correlationId, decision, respondedBy, reason) {
     return {
         type: "approval_response",
+        protocol: AGENTS_PROTOCOL_VERSION,
         requestId,
         correlationId,
         decision,
@@ -733,6 +812,7 @@ function createApprovalResponse(requestId, correlationId, decision, respondedBy,
 function createToolRequest(toolName, args, requestedBy, options) {
     return {
         type: "tool_request",
+        protocol: AGENTS_PROTOCOL_VERSION,
         requestId: generateId(),
         correlationId: generateId(),
         replyTo: options?.replyTo,
@@ -742,9 +822,10 @@ function createToolRequest(toolName, args, requestedBy, options) {
         requestedAt: createTimestamp(),
     };
 }
-function createToolResponse(requestId, correlationId, status, result, error, respondedBy) {
+function createToolResponse(requestId, correlationId, status, result, error, respondedBy, replyTo) {
     return {
         type: "tool_response",
+        protocol: AGENTS_PROTOCOL_VERSION,
         requestId,
         correlationId,
         status,
@@ -752,6 +833,7 @@ function createToolResponse(requestId, correlationId, status, result, error, res
         error,
         respondedBy,
         respondedAt: createTimestamp(),
+        replyTo,
     };
 }
 
@@ -782,6 +864,7 @@ function createToolResponse(requestId, correlationId, status, result, error, res
 class Handoff {
     constructor(room) {
         this._correlations = new CorrelationManager();
+        this._warnedMixed = false;
         this._room = room;
         // Wire result correlation
         this._room.on("result", (envelope) => {
@@ -796,11 +879,16 @@ class Handoff {
      * agent is connected (unless `allowNoWorkers` is set).
      */
     async dispatch(capability, payload, options) {
-        // Service discovery: check if any agent can handle this capability
+        // 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);
-            if (capable.length === 0) {
-                throw new Error(`No agent with capability "${capability}" is connected. ` +
+            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.`);
@@ -808,32 +896,48 @@ class Handoff {
         }
         const envelope = createTaskEnvelope(capability, payload, {
             ...options,
-            createdBy: this._room.agentId,
+            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) {
-            return this._correlations.register(envelope.correlationId, options.timeout);
+            // 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`);
         }
     }
-    /**
-     * 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) {
+    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);
+                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);
@@ -1032,6 +1136,7 @@ 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
@@ -1041,18 +1146,40 @@ class Tools {
         // Wire request handling
         this._room.on("toolRequest", async (envelope) => {
             const handler = this._handlers.get(envelope.toolName);
-            if (!handler)
+            // 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);
+                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);
+                }, this._agentId, replyTo);
                 this._room.publishTools(response);
             }
         });
@@ -1063,13 +1190,57 @@ class Tools {
     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) {
+        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) {
-        const envelope = createToolRequest(toolName, args, this._agentId);
+        // 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);
-        return this._correlations.register(envelope.correlationId, options?.timeout);
+        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() {
@@ -1097,6 +1268,7 @@ function tag(prefix, value) {
     return `${prefix}:${value}`;
 }
 
+exports.AGENTS_PROTOCOL_VERSION = AGENTS_PROTOCOL_VERSION;
 exports.AgentRoom = AgentRoom;
 exports.Approve = Approve;
 exports.Blackboard = Blackboard;
@@ -1104,6 +1276,7 @@ exports.CorrelationManager = CorrelationManager;
 exports.EventEmitter = EventEmitter;
 exports.Handoff = Handoff;
 exports.Inbox = Inbox;
+exports.IncompatibleProtocolError = IncompatibleProtocolError;
 exports.NoLagAgents = NoLagAgents;
 exports.Observe = Observe;
 exports.TAG_FLAGS = TAG_FLAGS;