@agentforge/patterns 0.16.91 → 0.17.0

package/README.md

@@ -84,7 +84,7 @@ The Multi-Agent pattern coordinates multiple specialized agents for complex task
 - Flexible routing strategies (LLM-based, skill-based, rule-based, round-robin, load-balanced)
 - Parallel execution support
 - Intelligent result aggregation
-- Dynamic worker registration
+- Fixed Worker topology construction before compilation
 - **22+ tests** - Comprehensive coverage
 
 ## Installation
@@ -418,6 +418,7 @@ import {
 ```typescript
 import {
   createMultiAgentSystem,
+  createWorkersRegistry,
   registerWorkers,
   createSupervisorNode,
   createWorkerNode,
@@ -428,7 +429,14 @@ import {
 **Main API**:
 - `createMultiAgentSystem(config)` - Create a complete Multi-Agent system
 - `MultiAgentSystemBuilder` - Builder for creating Multi-Agent systems with workers
-- `registerWorkers(system, workers)` - Update worker capabilities in state (Note: does not add worker nodes to compiled graphs; use builder or pass workers to createMultiAgentSystem)
+- `createWorkersRegistry(workers)` - Construct detached, normalized Worker registry records containing declared capabilities and invocation status without admitting Workers or creating graph topology
+- `registerWorkers(system, workers)` - Deprecated adapter that updates routing skills for known Workers; supplied tools must match the compiled executable tool set
+
+Worker identities and executable tools are fixed when the Multi-Agent System is
+compiled. The builder's `registerWorkers(workers)` method constructs that topology
+before `build()`. The deprecated `registerWorkers(system, workers)` adapter does
+not add executable Worker nodes: it may update routing skills for known Workers,
+and those updates are visible only to later executions.
 
 **Configuration**:
 ```typescript
@@ -540,4 +548,3 @@ pnpm typecheck
 ## License
 
 MIT © 2026 Tom Van Schoor
-

package/dist/index.cjs

@@ -71,6 +71,7 @@ __export(index_exports, {
   ToolCallSchema: () => ToolCallSchema,
   ToolResultSchema: () => ToolResultSchema,
   WorkerCapabilitiesSchema: () => WorkerCapabilitiesSchema,
+  WorkerLifecycleError: () => WorkerLifecycleError,
   buildDeduplicationMetrics: () => buildDeduplicationMetrics,
   calculateDeduplicationSavings: () => calculateDeduplicationSavings,
   createAggregatorNode: () => createAggregatorNode,
@@ -90,6 +91,7 @@ __export(index_exports, {
   createReviserNode: () => createReviserNode,
   createSupervisorNode: () => createSupervisorNode,
   createWorkerNode: () => createWorkerNode,
+  createWorkersRegistry: () => createWorkersRegistry,
   generateToolCallCacheKey: () => generateToolCallCacheKey,
   getRoutingStrategy: () => getRoutingStrategy,
   llmBasedRouting: () => llmBasedRouting,
@@ -431,9 +433,9 @@ function stringifyActionArguments(arguments_) {
 function getLatestThought(thoughts) {
   return thoughts[thoughts.length - 1]?.content ?? "";
 }
-function debugIfVerbose(logger6, verbose, message, data) {
+function debugIfVerbose(logger7, verbose, message, data) {
   if (verbose) {
-    logger6.debug(message, data);
+    logger7.debug(message, data);
   }
 }
 
@@ -2265,10 +2267,7 @@ var MultiAgentStateConfig = {
    */
   workers: {
     schema: import_zod13.z.record(import_zod13.z.string(), WorkerCapabilitiesSchema),
-    reducer: (left, right) => ({
-      ...left,
-      ...right
-    }),
+    reducer: (_left, right) => right,
     default: () => ({}),
     description: "Available worker agents and their capabilities"
   },
@@ -3477,163 +3476,295 @@ function createWorkerNode(config) {
 // src/multi-agent/agent-graph.ts
 var import_langgraph4 = require("@langchain/langgraph");
 
-// src/multi-agent/agent-workers.ts
-function getToolName(tool) {
-  if (!tool || typeof tool !== "object") {
-    return "unknown";
+// src/multi-agent/worker-lifecycle.ts
+var WorkerLifecycleError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "WorkerLifecycleError";
+    this.reason = reason;
   }
-  const candidate = tool;
-  if (typeof candidate.metadata?.name === "string") {
-    return candidate.metadata.name;
+};
+var workerLifecycles = /* @__PURE__ */ new WeakMap();
+function normalizeToolName(tool, workerId, index) {
+  const candidate = tool && typeof tool === "object" ? tool : void 0;
+  const rawName = candidate?.metadata?.name ?? candidate?.name;
+  const name = typeof rawName === "string" ? rawName.trim() : "";
+  if (!name) {
+    throw new WorkerLifecycleError(
+      "invalid-tool",
+      `Worker "${workerId}" has a nameless tool at index ${index}.`
+    );
   }
-  if (typeof candidate.name === "string") {
-    return candidate.name;
+  return name;
+}
+function normalizeWorkerToolNames(workerId, tools) {
+  const toolNames = (tools ?? []).map((tool, index) => normalizeToolName(tool, workerId, index));
+  const uniqueToolNames = new Set(toolNames);
+  if (uniqueToolNames.size !== toolNames.length) {
+    throw new WorkerLifecycleError(
+      "invalid-tool",
+      `Worker "${workerId}" has duplicate normalized tool names.`
+    );
   }
-  return "unknown";
+  return Object.freeze(toolNames);
 }
-function toWorkerCapabilities(worker) {
-  return {
-    skills: worker.capabilities,
-    tools: worker.tools?.map((tool) => getToolName(tool)) || [],
-    available: true,
-    currentWorkload: 0
-  };
+function validateIdentities(workers) {
+  for (const worker of workers) {
+    if (!worker.id || worker.id.trim() !== worker.id || worker.id.includes(",")) {
+      throw new WorkerLifecycleError(
+        "invalid-identity",
+        `Worker identity "${worker.id}" must be non-empty, trimmed, and comma-free.`
+      );
+    }
+  }
+  const identities = /* @__PURE__ */ new Set();
+  for (const worker of workers) {
+    if (identities.has(worker.id)) {
+      throw new WorkerLifecycleError(
+        "duplicate-identity",
+        `Worker identity "${worker.id}" appears more than once in the Worker batch.`
+      );
+    }
+    identities.add(worker.id);
+  }
 }
-function toWorkerConfig(worker, fallbackModel) {
+function normalizeWorkerDeclaredCapabilities(workerId, capabilities, tools) {
   return {
-    id: worker.name,
-    capabilities: toWorkerCapabilities(worker),
-    model: worker.model || fallbackModel,
-    tools: worker.tools,
-    systemPrompt: worker.systemPrompt
+    skills: Object.freeze([...capabilities.skills]),
+    tools: normalizeWorkerToolNames(workerId, tools)
   };
 }
-
-// src/multi-agent/agent-runtime.ts
-function mergeWorkers(input, workerCapabilities) {
+function normalizeWorkerStatus(capabilities) {
   return {
-    ...input,
-    workers: {
-      ...workerCapabilities,
-      ...input.workers || {}
-    }
+    available: capabilities.available,
+    currentWorkload: capabilities.currentWorkload
   };
 }
-function wrapCompiledSystem(system, workerCapabilities) {
-  const originalInvoke = system.invoke.bind(system);
-  system.invoke = (async function(input, config) {
-    return originalInvoke(
-      mergeWorkers(input, workerCapabilities),
-      config
-    );
+function normalizeWorkerRegistryRecord(workerId, capabilities, tools) {
+  return Object.freeze({
+    ...normalizeWorkerDeclaredCapabilities(workerId, capabilities, tools),
+    ...normalizeWorkerStatus(capabilities)
+  });
+}
+function asCompatibleWorkerCapabilities(record) {
+  return record;
+}
+function admitWorker(worker) {
+  const capabilities = asCompatibleWorkerCapabilities(
+    normalizeWorkerRegistryRecord(worker.id, worker.capabilities, worker.tools)
+  );
+  const tools = worker.tools ? Object.freeze([...worker.tools]) : void 0;
+  return Object.freeze({
+    ...worker,
+    capabilities,
+    ...tools ? { tools } : {}
   });
-  const originalStream = system.stream.bind(system);
-  system.stream = (async function(input, config) {
-    return originalStream(
-      mergeWorkers(input, workerCapabilities),
-      config
+}
+function admitWorkerTopology(workers) {
+  if (workers.length === 0) {
+    throw new WorkerLifecycleError(
+      "empty-topology",
+      "A Multi-Agent System requires at least one Worker."
     );
+  }
+  validateIdentities(workers);
+  const topology = Object.freeze(workers.map(admitWorker));
+  let workerCapabilities = Object.freeze(
+    Object.fromEntries(topology.map((worker) => [worker.id, worker.capabilities]))
+  );
+  return Object.freeze({
+    topology,
+    captureWorkerSnapshot: () => workerCapabilities,
+    updateRoutingSkills: (updates) => {
+      if (updates.length === 0) {
+        return;
+      }
+      validateIdentities(updates);
+      const replacements = updates.map((update) => {
+        const current = workerCapabilities[update.id];
+        if (!Object.hasOwn(workerCapabilities, update.id) || !current) {
+          throw new WorkerLifecycleError(
+            "unknown-worker",
+            `Cannot update unknown Worker "${update.id}" after compilation.`
+          );
+        }
+        if (update.assertedTools !== void 0) {
+          const assertedTools = [
+            ...normalizeWorkerToolNames(update.id, update.assertedTools)
+          ].sort();
+          const executableTools = [...current.tools].sort();
+          if (assertedTools.length !== executableTools.length || assertedTools.some((toolName, index) => toolName !== executableTools[index])) {
+            throw new WorkerLifecycleError(
+              "invalid-tool",
+              `Worker "${update.id}" tools do not match its compiled executable tools.`
+            );
+          }
+        }
+        return [
+          update.id,
+          asCompatibleWorkerCapabilities(
+            Object.freeze({
+              ...current,
+              skills: Object.freeze([...update.skills])
+            })
+          )
+        ];
+      });
+      workerCapabilities = Object.freeze({
+        ...workerCapabilities,
+        ...Object.fromEntries(replacements)
+      });
+    }
   });
-  return system;
 }
-function registerWorkerCapabilities(system, workers) {
-  if (!system._workerRegistry) {
-    system._workerRegistry = {};
+function associateWorkerLifecycle(system, lifecycle) {
+  workerLifecycles.set(system, lifecycle);
+}
+function resolveWorkerLifecycle(system) {
+  const lifecycle = workerLifecycles.get(system);
+  if (!lifecycle) {
+    throw new WorkerLifecycleError(
+      "unsupported-system",
+      "The compiled graph was not created by the Worker lifecycle."
+    );
   }
-  for (const worker of workers) {
-    system._workerRegistry[worker.name] = toWorkerCapabilities(worker);
-  }
-  if (!system._originalInvoke) {
-    system._originalInvoke = system.invoke.bind(system);
-    system.invoke = (async function(input, config) {
-      return system._originalInvoke(
-        mergeWorkers(input, system._workerRegistry || {}),
-        config
+  return lifecycle;
+}
+function createWorkerRegistryData(workers) {
+  validateIdentities(workers);
+  return Object.freeze(
+    Object.fromEntries(
+      workers.map((worker) => [
+        worker.id,
+        asCompatibleWorkerCapabilities(
+          normalizeWorkerRegistryRecord(
+            worker.id,
+            worker.capabilities,
+            worker.capabilities.tools.map((name) => ({ name }))
+          )
+        )
+      ])
+    )
+  );
+}
+
+// src/multi-agent/worker-initialization.ts
+var logger4 = createPatternLogger("agentforge:patterns:multi-agent:worker-initialization");
+function initializeWorkerState(topologyCapabilities, invocationWorkers) {
+  for (const workerId of Object.keys(invocationWorkers)) {
+    if (!Object.hasOwn(topologyCapabilities, workerId)) {
+      throw new WorkerLifecycleError(
+        "unknown-worker",
+        `Invocation state contains unknown Worker "${workerId}".`
       );
-    });
+    }
   }
-  if (!system._originalStream) {
-    system._originalStream = system.stream.bind(system);
-    system.stream = (async function(input, config) {
-      return system._originalStream(
-        mergeWorkers(input, system._workerRegistry || {}),
-        config
-      );
+  return Object.fromEntries(
+    Object.entries(topologyCapabilities).map(([workerId, capabilities]) => {
+      const status = Object.hasOwn(invocationWorkers, workerId) ? invocationWorkers[workerId] : capabilities;
+      return [
+        workerId,
+        {
+          skills: [...capabilities.skills],
+          tools: [...capabilities.tools],
+          available: status.available,
+          currentWorkload: status.currentWorkload
+        }
+      ];
+    })
+  );
+}
+function createWorkerInitializationNode(captureWorkerSnapshot) {
+  return async (state) => {
+    const topologyCapabilities = captureWorkerSnapshot();
+    logger4.info("Worker initialization started", {
+      workerCount: Object.keys(topologyCapabilities).length,
+      statusOverrideCount: Object.keys(state.workers).length
     });
-  }
+    let workers;
+    try {
+      workers = initializeWorkerState(topologyCapabilities, state.workers);
+    } catch (error) {
+      logger4.error("Worker initialization failed", {
+        error: error instanceof Error ? error.message : String(error),
+        invocationWorkerIds: Object.keys(state.workers),
+        topologyWorkerIds: Object.keys(topologyCapabilities)
+      });
+      throw error;
+    }
+    logger4.info("Worker initialization complete", {
+      workerCount: Object.keys(workers).length,
+      workerIds: Object.keys(workers)
+    });
+    return { workers };
+  };
 }
 
 // src/multi-agent/agent-graph.ts
-var logger4 = createPatternLogger("agentforge:patterns:multi-agent:system");
+var logger5 = createPatternLogger("agentforge:patterns:multi-agent:system");
 function createSupervisorRouter() {
   return (state) => {
-    logger4.debug("Supervisor router executing", {
+    logger5.debug("Supervisor router executing", {
       status: state.status,
       ...state.currentAgent ? { currentAgent: state.currentAgent } : {},
       iteration: state.iteration
     });
     if (state.status === "completed" || state.status === "failed") {
-      logger4.info("Supervisor router: ending workflow", { status: state.status });
+      logger5.info("Supervisor router: ending workflow", { status: state.status });
       return import_langgraph4.END;
     }
     if (state.status === "aggregating") {
-      logger4.info("Supervisor router: routing to aggregator");
+      logger5.info("Supervisor router: routing to aggregator");
       return "aggregator";
     }
     if (state.currentAgent && state.currentAgent !== "supervisor") {
       if (state.currentAgent.includes(",")) {
         const agents = state.currentAgent.split(",").map((agent) => agent.trim());
-        logger4.info("Supervisor router: parallel routing", {
+        logger5.info("Supervisor router: parallel routing", {
           agents,
           count: agents.length
         });
         return agents;
       }
-      logger4.info("Supervisor router: single agent routing", {
+      logger5.info("Supervisor router: single agent routing", {
         targetAgent: state.currentAgent
       });
       return state.currentAgent;
     }
-    logger4.debug("Supervisor router: staying at supervisor");
+    logger5.debug("Supervisor router: staying at supervisor");
     return "supervisor";
   };
 }
 function createWorkerRouter() {
   return (state) => {
-    logger4.debug("Worker router executing", {
+    logger5.debug("Worker router executing", {
       iteration: state.iteration,
       completedTasks: state.completedTasks.length
     });
-    logger4.debug("Worker router: returning to supervisor");
+    logger5.debug("Worker router: returning to supervisor");
     return "supervisor";
   };
 }
 function createAggregatorRouter() {
   return (state) => {
-    logger4.info("Aggregator router: ending workflow", {
+    logger5.info("Aggregator router: ending workflow", {
       completedTasks: state.completedTasks.length,
       status: state.status
     });
     return import_langgraph4.END;
   };
 }
-function createCompiledMultiAgentSystem(config) {
-  const {
-    supervisor,
-    workers,
-    aggregator,
-    maxIterations = 10,
-    verbose = false,
-    checkpointer
-  } = config;
+function createCompiledMultiAgentSystem(config, lifecycle = admitWorkerTopology(config.workers)) {
+  const { supervisor, aggregator, maxIterations = 10, verbose = false, checkpointer } = config;
   const workflow = new import_langgraph4.StateGraph(MultiAgentState);
   const workerIds = [];
-  const workerCapabilities = {};
   workflow.addNode(
-    "supervisor",
-    createSupervisorNode({ ...supervisor, maxIterations, verbose })
+    "initializeWorkers",
+    createWorkerInitializationNode(lifecycle.captureWorkerSnapshot)
   );
-  for (const workerConfig of workers) {
+  workflow.addNode("supervisor", createSupervisorNode({ ...supervisor, maxIterations, verbose }));
+  for (const workerConfig of lifecycle.topology) {
     workflow.addNode(
       workerConfig.id,
       createWorkerNode({
@@ -3642,7 +3773,6 @@ function createCompiledMultiAgentSystem(config) {
       })
     );
     workerIds.push(workerConfig.id);
-    workerCapabilities[workerConfig.id] = workerConfig.capabilities;
   }
   workflow.addNode(
     "aggregator",
@@ -3654,65 +3784,110 @@ function createCompiledMultiAgentSystem(config) {
   const supervisorRouter = createSupervisorRouter();
   const workerRouter = createWorkerRouter();
   const aggregatorRouter = createAggregatorRouter();
-  workflow.setEntryPoint("supervisor");
+  workflow.setEntryPoint("initializeWorkers");
+  workflow.addEdge("initializeWorkers", "supervisor");
   workflow.addConditionalEdges("supervisor", supervisorRouter, ["aggregator", import_langgraph4.END, ...workerIds]);
   for (const workerId of workerIds) {
     workflow.addConditionalEdges(workerId, workerRouter, ["supervisor"]);
   }
   workflow.addConditionalEdges("aggregator", aggregatorRouter, [import_langgraph4.END]);
-  const compiled = workflow.compile(
+  const system = workflow.compile(
     checkpointer ? { checkpointer } : void 0
   );
-  return wrapCompiledSystem(compiled, workerCapabilities);
+  associateWorkerLifecycle(system, lifecycle);
+  return system;
+}
+
+// src/multi-agent/agent-runtime.ts
+function registerWorkerCapabilities(system, workers) {
+  resolveWorkerLifecycle(system).updateRoutingSkills(
+    workers.map((worker) => ({
+      id: worker.name,
+      skills: worker.capabilities,
+      ...worker.tools === void 0 ? {} : { assertedTools: worker.tools }
+    }))
+  );
+}
+
+// src/multi-agent/agent-workers.ts
+function toWorkerConfig(worker, fallbackModel) {
+  return {
+    id: worker.name,
+    capabilities: {
+      skills: worker.capabilities,
+      tools: [],
+      available: true,
+      currentWorkload: 0
+    },
+    model: worker.model || fallbackModel,
+    tools: worker.tools,
+    systemPrompt: worker.systemPrompt
+  };
 }
 
 // src/multi-agent/agent-builder.ts
 var MultiAgentSystemBuilder = class {
   config;
-  additionalWorkers = [];
+  lifecycle;
   compiled = false;
   constructor(config) {
     this.config = {
       ...config,
-      workers: config.workers || []
+      workers: []
     };
+    this.lifecycle = config.workers?.length ? admitWorkerTopology(config.workers) : void 0;
   }
   registerWorkers(workers) {
     if (this.compiled) {
       throw new Error("Cannot register workers after the system has been compiled");
     }
-    for (const worker of workers) {
-      this.additionalWorkers.push(toWorkerConfig(worker, this.config.supervisor.model));
+    if (workers.length === 0) {
+      return this;
     }
+    const existingWorkers = this.lifecycle?.topology ?? [];
+    const pendingWorkers = workers.map(
+      (worker) => toWorkerConfig(worker, this.config.supervisor.model)
+    );
+    const lifecycle = admitWorkerTopology([...existingWorkers, ...pendingWorkers]);
+    this.lifecycle = lifecycle;
     return this;
   }
   build() {
     if (this.compiled) {
       throw new Error("System has already been compiled");
     }
-    const allWorkers = [...this.config.workers, ...this.additionalWorkers];
-    if (allWorkers.length === 0) {
-      throw new Error("At least one worker must be registered before building the system");
-    }
+    const lifecycle = this.lifecycle ?? admitWorkerTopology([]);
+    const system = createCompiledMultiAgentSystem(
+      {
+        ...this.config,
+        workers: [...lifecycle.topology]
+      },
+      lifecycle
+    );
     this.compiled = true;
-    return createCompiledMultiAgentSystem({
-      ...this.config,
-      workers: allWorkers
-    });
+    return system;
   }
 };
 
 // src/multi-agent/agent.ts
-var logger5 = createPatternLogger("agentforge:patterns:multi-agent:system");
+var logger6 = createPatternLogger("agentforge:patterns:multi-agent:system");
+var systemsWarnedAboutLegacyRegistration = /* @__PURE__ */ new WeakSet();
 function createMultiAgentSystem(config) {
-  return createCompiledMultiAgentSystem(config);
+  const lifecycle = admitWorkerTopology(config.workers);
+  return createCompiledMultiAgentSystem(config, lifecycle);
 }
 function registerWorkers(system, workers) {
-  logger5.warn(
-    "[AgentForge] registerWorkers() on a compiled system only updates worker capabilities in state.\nIt does NOT add worker nodes to the graph. Use MultiAgentSystemBuilder for proper worker registration.\nSee: https://github.com/TVScoundrel/agentforge/blob/main/packages/patterns/docs/multi-agent-pattern.md"
-  );
+  if (!systemsWarnedAboutLegacyRegistration.has(system)) {
+    systemsWarnedAboutLegacyRegistration.add(system);
+    logger6.warn(
+      "[AgentForge] registerWorkers() on a compiled system only updates routing skills for known Workers.\nIt does NOT add Worker nodes or change compiled tools. Use MultiAgentSystemBuilder before compilation.\nSee: https://github.com/TVScoundrel/agentforge/blob/main/packages/patterns/docs/multi-agent-pattern.md"
+    );
+  }
   registerWorkerCapabilities(system, workers);
 }
+function createWorkersRegistry(workers) {
+  return createWorkerRegistryData(workers);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentMessageSchema,
@@ -3766,6 +3941,7 @@ function registerWorkers(system, workers) {
   ToolCallSchema,
   ToolResultSchema,
   WorkerCapabilitiesSchema,
+  WorkerLifecycleError,
   buildDeduplicationMetrics,
   calculateDeduplicationSavings,
   createAggregatorNode,
@@ -3785,6 +3961,7 @@ function registerWorkers(system, workers) {
   createReviserNode,
   createSupervisorNode,
   createWorkerNode,
+  createWorkersRegistry,
   generateToolCallCacheKey,
   getRoutingStrategy,
   llmBasedRouting,