agent-swarm-kit 4.0.0 → 5.0.0

package/build/index.mjs

@@ -8,6 +8,7 @@ import * as path from 'path';
 import path__default, { join } from 'path';
 import crypto, { createHash } from 'crypto';
 import os from 'os';
+import { AsyncLocalStorage } from 'async_hooks';
 import { getMomentStamp, getTimeStamp } from 'get-moment-stamp';
 
 /**
@@ -3502,8 +3503,23 @@ const createToolCall = async (idx, tool, toolCalls, targetFn, reason, mode, outp
             // handles this late error (e.g. changeToAgent recursion guard thrown after
             // commitToolOutput). Without a recovery emission the pending waitForOutput
             // of the enclosing execution would hang forever.
-            const result = await self._resurrectModel(mode, `Late tool error after commit: name=${tool.function.name} error=${getErrorMessage(error)}`);
-            await self._emitOutput(mode, result, outputEpoch);
+            try {
+                const result = await self._resurrectModel(mode, `Late tool error after commit: name=${tool.function.name} error=${getErrorMessage(error)}`);
+                await self._emitOutput(mode, result, outputEpoch);
+            }
+            catch (recoveryError) {
+                // createToolCall is fired without await: a throwing recovery
+                // (_emitOutput throws by contract when validation fails twice) would
+                // be an unhandled rejection. Resolve the waiter directly instead.
+                console.error(`agent-swarm late tool error recovery failed functionName=${tool.function.name} error=${getErrorMessage(recoveryError)}`);
+                await errorSubject.next([
+                    self.params.clientId,
+                    recoveryError,
+                ]);
+                if (outputEpoch === self._outputEpoch) {
+                    await self._outputSubject.next(createPlaceholder());
+                }
+            }
         }
     }
     finally {
@@ -3568,7 +3584,7 @@ const RUN_FN = async (incoming, self) => {
         agentName: self.params.agentName,
         content: incoming,
         mode: "user",
-        role: "assistant",
+        role: "user",
     });
     const args = {
         clientId: self.params.clientId,
@@ -3667,19 +3683,29 @@ const EXECUTE_FN = async (incoming, mode, self) => {
         if (!toolCalls.length) {
             // maxToolCalls=0 dropped every call: the model wanted tools but none may
             // run. Emit the (tool-stripped) content as the answer instead of leaving
-            // the pending waitForOutput hanging forever.
-            const result = await self.params.transform(message.content, self.params.clientId, self.params.agentName);
+            // the pending waitForOutput hanging forever. _emitOutput owns the
+            // transform, so pass the raw content — transforming here too would
+            // apply a non-idempotent transform twice.
             await self.params.history.push({
                 ...message,
                 tool_calls: [],
                 agentName: self.params.agentName,
             });
-            await self._emitOutput(mode, result, outputEpoch);
+            await self._emitOutput(mode, message.content, outputEpoch);
             return;
         }
         {
-            const priorityTool = toolCalls.find((call) => swarm$1.navigationSchemaService.hasTool(call.function.name) ||
-                swarm$1.actionSchemaService.hasTool(call.function.name));
+            // Navigation/action tools are registered by toolName, while the model
+            // calls tools by function.name — check both, since they diverge for MCP
+            // tools (mcp_ prefix) and dynamic tool schemas.
+            const priorityTool = toolCalls.find((call) => {
+                const targetFn = toolList.find((t) => t.function.name === call.function.name);
+                return (swarm$1.navigationSchemaService.hasTool(call.function.name) ||
+                    swarm$1.actionSchemaService.hasTool(call.function.name) ||
+                    (targetFn &&
+                        (swarm$1.navigationSchemaService.hasTool(targetFn.toolName) ||
+                            swarm$1.actionSchemaService.hasTool(targetFn.toolName))));
+            });
             if (priorityTool) {
                 toolCalls = [priorityTool];
             }
@@ -3704,6 +3730,11 @@ const EXECUTE_FN = async (incoming, mode, self) => {
                 GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                     self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${result}`);
                 await self._emitOutput(mode, result, outputEpoch);
+                // The chain's .finally decrement is attached only after the loop, so
+                // an early return must roll the counter back itself — otherwise a
+                // late tool error would forever think a chain is still consuming
+                // events and skip its own recovery.
+                self._activeToolChains -= 1;
                 run(false);
                 return;
             }
@@ -3737,6 +3768,9 @@ const EXECUTE_FN = async (incoming, mode, self) => {
                 GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                     self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${result}`);
                 await self._emitOutput(mode, result, outputEpoch);
+                // See the "tool function not found" branch above: roll back the
+                // counter that the post-loop .finally would otherwise decrement.
+                self._activeToolChains -= 1;
                 run(false);
                 return;
             }
@@ -3768,6 +3802,12 @@ const EXECUTE_FN = async (incoming, mode, self) => {
                 if (lastStatus === TOOL_ERROR_SYMBOL) {
                     return lastStatus;
                 }
+                if (lastStatus === CANCEL_OUTPUT_SYMBOL) {
+                    // commitCancelOutput halts the chain exactly like stop/error/change:
+                    // without this guard the next tool would still run after the user
+                    // cancelled the output.
+                    return lastStatus;
+                }
                 GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                     self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} tool call executing`);
                 const statusAwaiter = Promise.race([
@@ -3793,39 +3833,53 @@ const EXECUTE_FN = async (incoming, mode, self) => {
                 if (status === MODEL_RESQUE_SYMBOL) {
                     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} the next tool execution stopped due to the model resque`);
-                    self.params.onAfterToolCalls &&
-                        self.params.onAfterToolCalls(self.params.clientId, self.params.agentName, toolCalls);
                 }
                 if (status === AGENT_CHANGE_SYMBOL) {
                     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} the next tool execution stopped due to the agent changed`);
-                    self.params.onAfterToolCalls &&
-                        self.params.onAfterToolCalls(self.params.clientId, self.params.agentName, toolCalls);
                 }
                 if (status === TOOL_STOP_SYMBOL) {
                     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} the next tool execution stopped due to the commitStopTools call`);
-                    self.params.onAfterToolCalls &&
-                        self.params.onAfterToolCalls(self.params.clientId, self.params.agentName, toolCalls);
                 }
                 if (status === CANCEL_OUTPUT_SYMBOL) {
                     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} the next tool execution stopped due to the commitCancelOutput call`);
-                    self.params.onAfterToolCalls &&
-                        self.params.onAfterToolCalls(self.params.clientId, self.params.agentName, toolCalls);
                 }
                 if (status === TOOL_ERROR_SYMBOL) {
                     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} functionName=${tool.function.name} the next tool execution stopped due to the call error`);
-                    const result = await self._resurrectModel(mode, `Function call failed with error: name=${tool.function.name} arguments=${JSON.stringify(tool.function.arguments)}`);
-                    GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
-                        self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${result}`);
-                    await self._emitOutput(mode, result, outputEpoch);
+                    try {
+                        const result = await self._resurrectModel(mode, `Function call failed with error: name=${tool.function.name} arguments=${JSON.stringify(tool.function.arguments)}`);
+                        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+                            self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${result}`);
+                        await self._emitOutput(mode, result, outputEpoch);
+                    }
+                    catch (recoveryError) {
+                        // Nobody awaits the status chain: a throwing recovery
+                        // (_emitOutput throws by contract when validation fails twice)
+                        // would reject it unhandled. Resolve the waiter directly instead.
+                        console.error(`agent-swarm tool error recovery failed functionName=${tool.function.name} error=${getErrorMessage(recoveryError)}`);
+                        await errorSubject.next([
+                            self.params.clientId,
+                            recoveryError,
+                        ]);
+                        if (outputEpoch === self._outputEpoch) {
+                            await self._outputSubject.next(createPlaceholder());
+                        }
+                    }
                 }
                 return status;
             });
         }
-        lastToolStatusRef.finally(() => {
+        lastToolStatusRef
+            .catch((error) => {
+            // The chain is fire-and-forget; a rejected link (e.g. a throwing
+            // params.map/bus adapter) must not surface as an unhandled rejection.
+            console.error(`agent-swarm tool status chain error agentName=${self.params.agentName} clientId=${self.params.clientId} error=${getErrorMessage(error)}`);
+            return null;
+        })
+            .finally(() => {
             self._activeToolChains -= 1;
             self.params.onAfterToolCalls &&
                 self.params.onAfterToolCalls(self.params.clientId, self.params.agentName, toolCalls);
@@ -3837,22 +3891,16 @@ const EXECUTE_FN = async (incoming, mode, self) => {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute no tool calls detected`);
     }
-    const result = await self.params.transform(message.content, self.params.clientId, self.params.agentName);
     await self.params.history.push({
         ...message,
         agentName: self.params.agentName,
     });
-    let validation = null;
-    if ((validation = await self.params.validate(result))) {
-        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
-            self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute invalid tool call detected: ${validation}`, { result });
-        const result1 = await self._resurrectModel(mode, `Invalid model output: ${result}`);
-        await self._emitOutput(mode, result1, outputEpoch);
-        return;
-    }
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
-        self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${result}`);
-    await self._emitOutput(mode, result, outputEpoch);
+        self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} execute end result=${message.content}`);
+    // _emitOutput owns transform + validate (with resurrect on failure), so the
+    // raw content goes straight through — transforming/validating here as well
+    // ran every transform twice per answer and broke non-idempotent transforms.
+    await self._emitOutput(mode, message.content, outputEpoch);
 };
 /**
  * Represents a client-side agent in the swarm system, implementing the IAgent interface.
@@ -3945,9 +3993,30 @@ class ClientAgent {
          */
         this.execute = queued(async (incoming, mode) => {
             this._activeExecutions += 1;
+            const outputEpoch = this._outputEpoch;
             try {
                 return await EXECUTE_FN(incoming, mode, this);
             }
+            catch (error) {
+                // EXECUTE_FN is fired without await from ClientSession.execute and
+                // queued() rejects internally: an unguarded rejection (e.g. a throwing
+                // completion in getCompletion) crashes the host process and leaves the
+                // pending waitForOutput hanging forever. Recover with the resque flow.
+                console.error(`agent-swarm execute error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+                await errorSubject.next([this.params.clientId, error]);
+                try {
+                    const result = await this._resurrectModel(mode, `Execution failed: ${getErrorMessage(error)}`);
+                    await this._emitOutput(mode, result, outputEpoch);
+                }
+                catch (recoveryError) {
+                    // Even the recovery failed (e.g. recomplete strategy hitting the same
+                    // broken completion): resolve the waiter directly so nothing hangs.
+                    console.error(`agent-swarm execute recovery error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(recoveryError)}`);
+                    if (outputEpoch === this._outputEpoch) {
+                        await this._outputSubject.next(createPlaceholder());
+                    }
+                }
+            }
             finally {
                 this._activeExecutions -= 1;
             }
@@ -3956,7 +4025,19 @@ class ClientAgent {
          * Runs a stateless completion for the incoming message, queued to prevent overlapping executions.
          * Implements IAgent.run, delegating to RUN_FN with queuing via functools-kit’s queued decorator.
           */
-        this.run = queued(async (incoming) => await RUN_FN(incoming, this));
+        this.run = queued(async (incoming) => {
+            try {
+                return await RUN_FN(incoming, this);
+            }
+            catch (error) {
+                // queued() rejects internally, so a throwing completion would raise an
+                // unhandled rejection besides failing the caller: degrade to an empty
+                // stateless result and surface the error through errorSubject.
+                console.error(`agent-swarm run error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+                await errorSubject.next([this.params.clientId, error]);
+                return "";
+            }
+        });
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} CTOR`, {
                 params,
@@ -3973,11 +4054,15 @@ class ClientAgent {
         const seen = new Set();
         const agentToolList = [];
         if (this.params.tools) {
-            await Promise.all(this.params.tools.map(async (tool) => {
+            // Resolve availability/dynamic schemas concurrently, but keep the RESULT
+            // in declaration order: pushing from within the concurrent map would order
+            // tools by resolution time, making the tool list, the seen-based dedup and
+            // the single-commit-action filter all non-deterministic across runs.
+            const resolvedTools = await Promise.all(this.params.tools.map(async (tool) => {
                 const { toolName, function: upperFn, isAvailable = TOOL_AVAILABLE_DEFAULT, ...other } = tool;
                 try {
                     if (await not(isAvailable(this.params.clientId, this.params.agentName, toolName))) {
-                        return;
+                        return null;
                     }
                 }
                 catch (error) {
@@ -3985,7 +4070,7 @@ class ClientAgent {
                     // hang the pending waitForOutput: treat it as "not available".
                     console.error(`agent-swarm isAvailable error toolName=${toolName} error=${getErrorMessage(error)}`);
                     await errorSubject.next([this.params.clientId, error]);
-                    return;
+                    return null;
                 }
                 let fn;
                 try {
@@ -3999,14 +4084,19 @@ class ClientAgent {
                     // the execution — the tool is skipped for this completion.
                     console.error(`agent-swarm dynamic tool function error toolName=${toolName} error=${getErrorMessage(error)}`);
                     await errorSubject.next([this.params.clientId, error]);
-                    return;
+                    return null;
                 }
-                agentToolList.push({
+                return {
                     ...other,
                     toolName,
                     function: fn,
-                });
+                };
             }));
+            for (const tool of resolvedTools) {
+                if (tool) {
+                    agentToolList.push(tool);
+                }
+            }
         }
         let mcpToolList = [];
         try {
@@ -4155,6 +4245,10 @@ class ClientAgent {
         }
         this.params.onOutput &&
             this.params.onOutput(this.params.clientId, this.params.agentName, result);
+        // Keep the callback surface symmetric with the resurrect branch above:
+        // the emitted output is an assistant message on both paths.
+        this.params.onAssistantMessage &&
+            this.params.onAssistantMessage(this.params.clientId, this.params.agentName, result);
         await this._outputSubject.next(result);
         await this.params.bus.emit(this.params.clientId, {
             type: "emit-output",
@@ -4209,7 +4303,21 @@ class ClientAgent {
             await this._resqueSubject.next(MODEL_RESQUE_SYMBOL);
             return placeholder;
         }
-        const rawMessage = await this.getCompletion(mode, []);
+        let rawMessage;
+        try {
+            rawMessage = await this.getCompletion(mode, []);
+        }
+        catch (error) {
+            // _resurrectModel IS the recovery path: if the resque completion itself
+            // rejects (e.g. the provider is down — often the very reason we are
+            // here), rethrowing would surface as an unhandled rejection from the
+            // fire-and-forget callers (createToolCall, tool status chain). Degrade
+            // to the placeholder instead.
+            console.error(`agent-swarm _resurrectModel completion error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+            await errorSubject.next([this.params.clientId, error]);
+            await this._resqueSubject.next(MODEL_RESQUE_SYMBOL);
+            return placeholder;
+        }
         if (rawMessage.tool_calls?.length) {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                 this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} _resurrectModel should not emit tool_calls`);
@@ -4698,6 +4806,21 @@ class OperatorSignal {
     sendMessage(message, next) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`OperatorSignal agentName=${this.params.agentName} clientId=${this.params.clientId} sendMessage`, { message });
+        // Dispose the previous signal before opening a new one: overwriting the
+        // ref leaks the pending signal, and its late answer would resolve the
+        // NEXT waitForOutput with a reply to the previous question.
+        if (this._disposeRef) {
+            const disposeRef = this._disposeRef;
+            this._disposeRef = null;
+            try {
+                disposeRef();
+            }
+            catch (error) {
+                // A throwing user dispose must not prevent the next signal from
+                // opening — the previous one is torn down on a best-effort basis.
+                console.error(`agent-swarm operator signal dispose error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+            }
+        }
         this._disposeRef = this._signalFactory(message, next);
     }
     /**
@@ -4709,7 +4832,14 @@ class OperatorSignal {
         if (this._disposeRef) {
             const disposeRef = this._disposeRef;
             this._disposeRef = null;
-            await disposeRef();
+            try {
+                await disposeRef();
+            }
+            catch (error) {
+                // dispose is awaited from waitForOutput's timeout path: a throwing
+                // user dispose would reject waitForOutput and hang the swarm race.
+                console.error(`agent-swarm operator signal dispose error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+            }
         }
     }
 }
@@ -4752,7 +4882,17 @@ class ClientOperator {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                 this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} execute tool mode forwarded to operator`);
         }
-        this._operatorSignal.sendMessage(input, this._outgoingSubject.next);
+        try {
+            this._operatorSignal.sendMessage(input, this._outgoingSubject.next);
+        }
+        catch (error) {
+            // execute is fired without await from ClientSession.execute: a throwing
+            // operator connector would surface as an unhandled rejection and crash
+            // the host process. Surface the error instead; the pending waitForOutput
+            // resolves through the operator timeout.
+            console.error(`agent-swarm operator connector error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+            await errorSubject.next([this.params.clientId, error]);
+        }
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} execute end`, { input, mode });
     }
@@ -5830,6 +5970,8 @@ class ClientHistory {
             // the error through errorSubject so the caller's complete() rejects.
             console.error(`agent-swarm history push error agentName=${this.params.agentName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
             await errorSubject.next([this.params.clientId, error]);
+            // The record was dropped: do not announce a successful push on the bus.
+            return;
         }
         await this.params.bus.emit(this.params.clientId, {
             type: "push",
@@ -6288,6 +6430,7 @@ class NoopAgent {
         const message = `called commitCancelOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
         this.logger.log(message);
         console.error(message);
+        return await this.defaultAgent.commitCancelOutput();
     }
     /**
      * Logs an attempt to run the missing agent and delegates to the default agent's run method.
@@ -6484,7 +6627,10 @@ class ClientSwarm {
     setBusy(isBusy) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientSwarm swarmName=${this.params.swarmName} clientId=${this.params.clientId} setBusy`, { isBusy });
-        this._isBusy += isBusy ? 1 : -1;
+        // Clamp at zero: an unmatched setBusy(false) (reachable through the public
+        // SwarmPublicService.setBusy) would drive the counter negative, and a
+        // negative counter reads as "busy" forever — deadlocking the session lock.
+        this._isBusy = Math.max(0, this._isBusy + (isBusy ? 1 : -1));
     }
     /**
      * Getter for the busy state of the swarm.
@@ -6715,7 +6861,14 @@ class ClientSwarm {
         });
         if (!result) {
             console.error(`agent-swarm ClientSwarm getAgent current agent is not in the swarm agentName=${agentName} clientId=${this.params.clientId} swarmName=${this.params.swarmName}`);
-            return new NoopAgent(this.params.clientId, this.params.swarmName, agentName, this.params.agentMap[this.params.defaultAgent], this.params.logger);
+            const defaultAgent = this.params.agentMap[this.params.defaultAgent];
+            if (!defaultAgent) {
+                // NoopAgent delegates every call to the default agent: with that one
+                // missing too the delegation would die with a bare TypeError instead
+                // of an actionable message.
+                throw new Error(`agent-swarm ClientSwarm getAgent default agent is not in the swarm either agentName=${agentName} defaultAgent=${this.params.defaultAgent} clientId=${this.params.clientId} swarmName=${this.params.swarmName}`);
+            }
+            return new NoopAgent(this.params.clientId, this.params.swarmName, agentName, defaultAgent, this.params.logger);
         }
         return result;
     }
@@ -10862,15 +11015,49 @@ class ClientStorage {
          */
         this._itemMap = new Map();
         /**
-         * Dispatches a storage action (upsert, remove, or clear) in a queued manner, delegating to DISPATCH_FN.
-         * Ensures sequential execution of storage operations, supporting thread-safe updates from ClientAgent or tools.
+         * Queued core of dispatch. The wrapped function must never reject: queued()
+         * chains every call on the previous promise, so a rejection inside the queue
+         * (e.g. a throwing createIndex/createEmbedding/setData) would reject every
+         * already-queued dispatch with this foreign error WITHOUT running it — a
+         * concurrent upsert/remove/clear would be silently dropped. Errors are boxed
+         * here and rethrown outside the queue, so only the failing caller observes them.
          */
-        this.dispatch = queued(async (action, payload) => await DISPATCH_FN$1(action, this, payload));
+        this._dispatchQueue = queued(async (action, payload) => {
+            try {
+                await DISPATCH_FN$1(action, this, payload);
+                return null;
+            }
+            catch (error) {
+                return { error };
+            }
+        });
+        /**
+         * Dispatches a storage action (upsert, remove, or clear) through the serialized
+         * queue, delegating to DISPATCH_FN. Ensures sequential execution of storage
+         * operations, supporting thread-safe updates from ClientAgent or tools.
+         */
+        this.dispatch = async (action, payload) => {
+            const result = await this._dispatchQueue(action, payload);
+            if (result) {
+                throw result.error;
+            }
+        };
         /**
          * Creates embeddings for the given item, memoized by item ID to avoid redundant calculations via CREATE_EMBEDDING_FN.
          * Caches results for efficiency, cleared on upsert/remove to ensure freshness, supporting EmbeddingSchemaService.
           */
-        this._createEmbedding = memoize(([{ id }]) => id, async (item) => await CREATE_EMBEDDING_FN(item, this));
+        this._createEmbedding = memoize(([{ id }]) => id, async (item) => {
+            try {
+                return await CREATE_EMBEDDING_FN(item, this);
+            }
+            catch (error) {
+                // Never cache a rejected embedding: the memoized promise would keep
+                // this item permanently broken (every take re-throwing the same
+                // error) even after the embedding provider recovers.
+                this._createEmbedding.clear(item.id);
+                throw error;
+            }
+        });
         /**
          * Waits for the initialization of the storage, loading initial data and creating embeddings via WAIT_FOR_INIT_FN.
          * Ensures initialization happens only once using singleshot, supporting StorageConnectionService’s lifecycle.
@@ -11750,6 +11937,13 @@ const WAIT_FOR_INIT_FN = async (self) => {
  * SwarmConnectionService (swarm-level state), and BusService (event emission).
 */
 class ClientState {
+    /**
+     * True only while the caller runs inside the async context of an active
+     * dispatch on this instance (i.e. a reentrant call from within a dispatchFn).
+     */
+    get _inDispatch() {
+        return this._dispatchContext.getStore() === true;
+    }
     /**
      * Constructs a ClientState instance with the provided parameters.
      * Invokes the onInit callback if provided and logs construction if debugging is enabled.
@@ -11758,29 +11952,50 @@ class ClientState {
         this.params = params;
         this.stateChanged = new Subject();
         /**
-         * True while a queued dispatch (read/write) is executing for this instance.
-         * getState checks it to serve reentrant reads (getState inside a setState
-         * dispatchFn) without re-entering the queue, which would deadlock.
+         * Marks the async execution context of a running dispatch (read/write).
+         * getState checks it to serve reentrant reads (getState called from INSIDE a
+         * setState dispatchFn/middleware) without re-entering the queue, which would
+         * deadlock. Scoping this per async-context — instead of a plain instance flag —
+         * ensures an UNRELATED concurrent getState still queues and observes writes in
+         * order, rather than reading a stale field while some other write is in flight.
          */
-        this._inDispatch = false;
+        this._dispatchContext = new AsyncLocalStorage();
         /**
          * The current state data, initialized as null and set during waitForInit.
          * Updated by setState and clearState, persisted via params.setState if provided.
          */
         this._state = null;
         /**
-         * Queued dispatch function to read or write the state, delegating to DISPATCH_FN.
-         * Ensures thread-safe state operations, supporting concurrent access from ClientAgent or tools.
+         * Queued core of dispatch. The wrapped function must never reject: queued()
+         * chains every call on the previous promise, so a rejection inside the queue
+         * would reject every already-queued dispatch with this foreign error WITHOUT
+         * running it — a concurrent setState would be silently dropped. Errors (e.g.
+         * a throwing user dispatchFn or middleware) are boxed here and rethrown
+         * outside the queue, so only the caller whose operation failed observes them.
          */
-        this.dispatch = queued(async (action, payload) => {
-            this._inDispatch = true;
+        this._dispatchQueue = queued(async (action, payload) => {
             try {
-                return await DISPATCH_FN(action, this, payload);
+                return {
+                    ok: true,
+                    state: await this._dispatchContext.run(true, async () => await DISPATCH_FN(action, this, payload)),
+                };
             }
-            finally {
-                this._inDispatch = false;
+            catch (error) {
+                return { ok: false, error };
             }
         });
+        /**
+         * Dispatches a read or write of the state through the serialized queue,
+         * delegating to DISPATCH_FN. Ensures thread-safe state operations, supporting
+         * concurrent access from ClientAgent or tools.
+         */
+        this.dispatch = async (action, payload) => {
+            const result = await this._dispatchQueue(action, payload);
+            if ("error" in result) {
+                throw result.error;
+            }
+            return result.state;
+        };
         /**
          * Waits for the state to initialize via WAIT_FOR_INIT_FN, ensuring it’s only called once using singleshot.
          * Loads the initial state into _state, supporting StateConnectionService’s lifecycle management.
@@ -11810,8 +12025,18 @@ class ClientState {
         });
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientState stateName=${this.params.stateName} clientId=${this.params.clientId} shared=${this.params.shared} setState output`, { pendingState: this._state });
-        this.params.setState &&
-            this.params.setState(this._state, this.params.clientId, this.params.stateName);
+        if (this.params.setState) {
+            try {
+                await this.params.setState(this._state, this.params.clientId, this.params.stateName);
+            }
+            catch (error) {
+                // Persistence was fired without await before: a rejecting adapter
+                // raised an unhandled rejection. Keep the in-memory state and surface
+                // the error to the caller through errorSubject instead.
+                console.error(`agent-swarm state persist error stateName=${this.params.stateName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+                await errorSubject.next([this.params.clientId, error]);
+            }
+        }
         if (this.params.callbacks?.onWrite) {
             this.params.callbacks.onWrite(this._state, this.params.clientId, this.params.stateName);
         }
@@ -11843,8 +12068,17 @@ class ClientState {
         });
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientState stateName=${this.params.stateName} clientId=${this.params.clientId} shared=${this.params.shared} clearState output`, { pendingState: this._state });
-        this.params.setState &&
-            this.params.setState(this._state, this.params.clientId, this.params.stateName);
+        if (this.params.setState) {
+            try {
+                await this.params.setState(this._state, this.params.clientId, this.params.stateName);
+            }
+            catch (error) {
+                // See setState above: a rejecting persistence adapter must not raise
+                // an unhandled rejection.
+                console.error(`agent-swarm state persist error stateName=${this.params.stateName} clientId=${this.params.clientId} error=${getErrorMessage(error)}`);
+                await errorSubject.next([this.params.clientId, error]);
+            }
+        }
         if (this.params.callbacks?.onWrite) {
             this.params.callbacks.onWrite(this._state, this.params.clientId, this.params.stateName);
         }
@@ -14909,7 +15143,6 @@ class PolicyPublicService {
     }
 }
 
-const BAN_NEED_FETCH = Symbol("ban-need-fetch");
 /**
  * Class representing a client policy in the swarm system, implementing the IPolicy interface.
  * Manages client bans, input/output validation, and restrictions, with lazy-loaded ban lists and event emission via BusService.
@@ -14918,6 +15151,32 @@ const BAN_NEED_FETCH = Symbol("ban-need-fetch");
  * Supports auto-banning on validation failure and customizable ban messages, ensuring swarm security and compliance.
 */
 class ClientPolicy {
+    /**
+     * Returns the ban set of the given swarm, fetching it on first access.
+     * Re-checks the map after the await: a ban committed through _banQueue while
+     * the fetch was in flight must not be overwritten by the stale fetch result.
+     */
+    async _getBanSet(swarmName) {
+        const existing = this._banSetBySwarm.get(swarmName);
+        if (existing) {
+            return existing;
+        }
+        const fetched = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
+        if (!this._banSetBySwarm.has(swarmName)) {
+            this._banSetBySwarm.set(swarmName, fetched);
+        }
+        return this._banSetBySwarm.get(swarmName);
+    }
+    /**
+     * Runs a ban-set mutation through _banQueue, rethrowing its boxed error
+     * outside the queue so only the failing caller observes it.
+     */
+    async _runBanQueue(fn) {
+        const result = await this._banQueue(fn);
+        if (result) {
+            throw result.error;
+        }
+    }
     /**
      * Constructs a ClientPolicy instance with the provided parameters.
      * Invokes the onInit callback if defined and logs construction if debugging is enabled.
@@ -14925,11 +15184,13 @@ class ClientPolicy {
     constructor(params) {
         this.params = params;
         /**
-         * Set of banned client IDs or a symbol indicating the ban list needs to be fetched.
-         * Initialized as BAN_NEED_FETCH, lazily populated via params.getBannedClients on first use in hasBan, validateInput, etc.
-         * Updated by banClient and unbanClient, persisted if params.setBannedClients is provided.
+         * Ban sets keyed by swarm name, lazily populated via params.getBannedClients.
+         * A ClientPolicy instance is memoized per policyName and shared by every swarm
+         * that lists the policy, while bans are persisted per (policy, swarm) — a
+         * single shared set would leak bans of one swarm into another and persist
+         * the mixed set into the wrong store.
          */
-        this._banSet = BAN_NEED_FETCH;
+        this._banSetBySwarm = new Map();
         /**
          * Serializes the read-modify-write of _banSet shared by banClient/unbanClient.
          * Without it two concurrent bans of different clients both read the same ban
@@ -14937,8 +15198,23 @@ class ClientPolicy {
          * the earlier one — one ban is silently lost in memory and in the persisted
          * store. queued() runs the mutations one at a time so each observes the result
          * of the previous one.
-         */
-        this._banQueue = queued(async (fn) => await fn());
+         *
+         * The wrapped function must never reject: queued() chains every call on the
+         * previous promise, so a rejection inside the queue (e.g. a throwing
+         * setBannedClients adapter) would reject every already-queued ban/unban with
+         * this foreign error WITHOUT running it — a concurrent ban of another client
+         * would be silently lost. Errors are boxed here and rethrown by the caller
+         * outside the queue.
+         */
+        this._banQueue = queued(async (fn) => {
+            try {
+                await fn();
+                return null;
+            }
+            catch (error) {
+                return { error };
+            }
+        });
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientPolicy policyName=${this.params.policyName} CTOR`, {
                 params,
@@ -14957,10 +15233,8 @@ class ClientPolicy {
                 clientId,
                 swarmName,
             });
-        if (this._banSet === BAN_NEED_FETCH) {
-            this._banSet = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
-        }
-        return this._banSet.has(clientId);
+        const banSet = await this._getBanSet(swarmName);
+        return banSet.has(clientId);
     }
     /**
      * Retrieves the ban message for a client, using a custom getBanMessage function if provided or falling back to params.banMessage.
@@ -15009,10 +15283,8 @@ class ClientPolicy {
             },
             clientId,
         });
-        if (this._banSet === BAN_NEED_FETCH) {
-            this._banSet = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
-        }
-        if (this._banSet.has(clientId)) {
+        const banSet = await this._getBanSet(swarmName);
+        if (banSet.has(clientId)) {
             return false;
         }
         if (!this.params.validateInput) {
@@ -15054,10 +15326,8 @@ class ClientPolicy {
             },
             clientId,
         });
-        if (this._banSet === BAN_NEED_FETCH) {
-            this._banSet = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
-        }
-        if (this._banSet.has(clientId)) {
+        const banSet = await this._getBanSet(swarmName);
+        if (banSet.has(clientId)) {
             return false;
         }
         if (!this.params.validateOutput) {
@@ -15082,31 +15352,32 @@ class ClientPolicy {
                 clientId,
                 swarmName,
             });
-        if (this.params.callbacks?.onBanClient) {
-            this.params.callbacks.onBanClient(clientId, swarmName, this.params.policyName);
-        }
-        await this.params.bus.emit(clientId, {
-            type: "ban-client",
-            source: "policy-bus",
-            input: {},
-            output: {},
-            context: {
-                policyName: this.params.policyName,
-                swarmName,
-            },
-            clientId,
-        });
-        await this._banQueue(async () => {
-            if (this._banSet === BAN_NEED_FETCH) {
-                this._banSet = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
-            }
-            if (this._banSet.has(clientId)) {
+        await this._runBanQueue(async () => {
+            const banSet = await this._getBanSet(swarmName);
+            if (banSet.has(clientId)) {
+                // Already banned: skip the mutation AND the notifications, matching
+                // the documented "skips if already banned" contract — otherwise every
+                // redundant ban re-fires onBanClient and the bus event.
                 return;
             }
-            this._banSet = new Set(this._banSet).add(clientId);
+            this._banSetBySwarm.set(swarmName, new Set(banSet).add(clientId));
             if (this.params.setBannedClients) {
-                await this.params.setBannedClients([...this._banSet], this.params.policyName, swarmName);
+                await this.params.setBannedClients([...this._banSetBySwarm.get(swarmName)], this.params.policyName, swarmName);
+            }
+            if (this.params.callbacks?.onBanClient) {
+                this.params.callbacks.onBanClient(clientId, swarmName, this.params.policyName);
             }
+            await this.params.bus.emit(clientId, {
+                type: "ban-client",
+                source: "policy-bus",
+                input: {},
+                output: {},
+                context: {
+                    policyName: this.params.policyName,
+                    swarmName,
+                },
+                clientId,
+            });
         });
     }
     /**
@@ -15120,35 +15391,35 @@ class ClientPolicy {
                 clientId,
                 swarmName,
             });
-        if (this.params.callbacks?.onUnbanClient) {
-            this.params.callbacks.onUnbanClient(clientId, swarmName, this.params.policyName);
-        }
-        await this.params.bus.emit(clientId, {
-            type: "unban-client",
-            source: "policy-bus",
-            input: {},
-            output: {},
-            context: {
-                policyName: this.params.policyName,
-                swarmName,
-            },
-            clientId,
-        });
-        await this._banQueue(async () => {
-            if (this._banSet === BAN_NEED_FETCH) {
-                this._banSet = new Set(await this.params.getBannedClients(this.params.policyName, swarmName));
-            }
-            if (!this._banSet.has(clientId)) {
+        await this._runBanQueue(async () => {
+            const banSet = await this._getBanSet(swarmName);
+            if (!banSet.has(clientId)) {
+                // Not banned: skip the mutation and the notifications, matching the
+                // documented "skips if not banned" contract.
                 return;
             }
             {
-                const banSet = new Set(this._banSet);
-                banSet.delete(clientId);
-                this._banSet = banSet;
+                const nextBanSet = new Set(banSet);
+                nextBanSet.delete(clientId);
+                this._banSetBySwarm.set(swarmName, nextBanSet);
             }
             if (this.params.setBannedClients) {
-                await this.params.setBannedClients([...this._banSet], this.params.policyName, swarmName);
+                await this.params.setBannedClients([...this._banSetBySwarm.get(swarmName)], this.params.policyName, swarmName);
+            }
+            if (this.params.callbacks?.onUnbanClient) {
+                this.params.callbacks.onUnbanClient(clientId, swarmName, this.params.policyName);
             }
+            await this.params.bus.emit(clientId, {
+                type: "unban-client",
+                source: "policy-bus",
+                input: {},
+                output: {},
+                context: {
+                    policyName: this.params.policyName,
+                    swarmName,
+                },
+                clientId,
+            });
         });
     }
 }