@oni.bot/core 1.0.2 → 1.1.0

package/dist/swarm/graph.js

@@ -8,37 +8,26 @@
 //   - compile()          returns a full ONISkeleton
 // ============================================================
 import { StateGraph } from "../graph.js";
-import { START, END, appendList, lastValue, mergeObject } from "../types.js";
-import { Command, Send } from "../types.js";
-import { Handoff } from "./types.js";
+import { START, END } from "../types.js";
 import { AgentRegistry } from "./registry.js";
+import { baseSwarmChannels } from "./config.js";
 import { createSupervisorNode } from "./supervisor.js";
-import { getInbox } from "./mailbox.js";
 import { RequestReplyBroker } from "../coordination/request-reply.js";
 import { PubSub } from "../coordination/pubsub.js";
-import { runWithTimeout } from "../internal/timeout.js";
-export const baseSwarmChannels = {
-    task: lastValue(() => ""),
-    context: mergeObject(() => ({})),
-    agentResults: mergeObject(() => ({})),
-    messages: appendList(() => []),
-    swarmMessages: appendList(() => []),
-    supervisorRound: lastValue(() => 0),
-    currentAgent: lastValue(() => null),
-    done: lastValue(() => false),
-    handoffHistory: appendList(() => []),
-};
+import { createAgentNode } from "./agent-node.js";
+import { buildSwarmExtensions } from "./compile-ext.js";
+import { buildHierarchical, buildFanOut, buildPipeline, buildPeerNetwork, buildMapReduce, buildDebate, buildHierarchicalMesh, buildRace, buildDag, buildPool, buildCompose, } from "./factories.js";
 // ----------------------------------------------------------------
 // SwarmGraph
 // ----------------------------------------------------------------
 export class SwarmGraph {
-    inner;
-    registry;
-    channels;
-    agentIds = new Set();
-    supervisorNodeName = "__supervisor__";
-    hasSupervisor = false;
-    onErrorPolicy = "fallback";
+    /** @internal */ inner;
+    /** @internal */ registry;
+    /** @internal */ channels;
+    /** @internal */ agentIds = new Set();
+    /** @internal */ supervisorNodeName = "__supervisor__";
+    /** @internal */ hasSupervisor = false;
+    /** @internal */ onErrorPolicy = "fallback";
     _broker;
     _pubsub;
     get broker() {
@@ -62,23 +51,7 @@ export class SwarmGraph {
      * ready-to-compile SwarmGraph.
      */
     static hierarchical(config) {
-        const swarm = new SwarmGraph(config.channels);
-        for (const agentDef of config.agents) {
-            swarm.addAgent(agentDef);
-        }
-        swarm.addSupervisor({
-            model: config.supervisor.model,
-            strategy: config.supervisor.strategy,
-            taskField: "task",
-            contextField: "context",
-            rules: config.supervisor.rules,
-            systemPrompt: config.supervisor.systemPrompt,
-            maxRounds: config.supervisor.maxRounds,
-            deadlineMs: config.supervisor.deadlineMs,
-            autoRecover: config.supervisor.autoRecover,
-        });
-        swarm.onErrorPolicy = config.onError ?? "fallback";
-        return swarm;
+        return buildHierarchical(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: fan-out template ----
     /**
@@ -86,68 +59,7 @@ export class SwarmGraph {
      * and collects results through a reducer node.
      */
     static fanOut(config) {
-        const swarm = new SwarmGraph(config.channels);
-        const agentIds = config.agents.map((a) => a.id);
-        const maxConcurrency = config.maxConcurrency;
-        const timeoutMs = config.timeoutMs;
-        const weights = config.weights;
-        // Register agents in registry (but don't use addAgent — we wire manually)
-        for (const agentDef of config.agents) {
-            swarm.registry.register(agentDef);
-            swarm.agentIds.add(agentDef.id);
-        }
-        // Single orchestrator node that runs agents with concurrency/timeout control
-        swarm.inner.addNode("__fanout_runner__", async (state, cfg) => {
-            const agentMap = new Map(config.agents.map((a) => [a.id, a]));
-            async function runAgent(id) {
-                const agent = agentMap.get(id);
-                try {
-                    await agent.hooks?.onStart?.(id, state);
-                    const result = await runWithTimeout(() => agent.skeleton.invoke({ ...state }, { ...cfg, agentId: id }), timeoutMs, () => new Error(`Agent "${id}" timed out after ${timeoutMs}ms`));
-                    await agent.hooks?.onComplete?.(id, result);
-                    return { id, result, error: null };
-                }
-                catch (err) {
-                    await agent.hooks?.onError?.(id, err);
-                    return { id, result: null, error: err };
-                }
-            }
-            let allResults;
-            if (maxConcurrency != null && maxConcurrency > 0) {
-                // Batched execution with concurrency limit
-                allResults = [];
-                const remaining = [...agentIds];
-                while (remaining.length > 0) {
-                    const batch = remaining.splice(0, maxConcurrency);
-                    const batchResults = await Promise.all(batch.map(runAgent));
-                    allResults.push(...batchResults);
-                }
-            }
-            else {
-                // All in parallel
-                allResults = await Promise.all(agentIds.map(runAgent));
-            }
-            // Collect results
-            const agentResults = { ...(state.agentResults ?? {}) };
-            for (const { id, result, error } of allResults) {
-                if (error) {
-                    agentResults[id] = {
-                        _error: true,
-                        agent: id,
-                        error: String(error instanceof Error ? error.message : error),
-                    };
-                }
-                else {
-                    agentResults[id] = result;
-                }
-            }
-            // Run reducer with weights
-            const reduced = config.reducer(agentResults, weights);
-            return { ...reduced, agentResults };
-        });
-        swarm.inner.addEdge(START, "__fanout_runner__");
-        swarm.inner.addEdge("__fanout_runner__", END);
-        return swarm;
+        return buildFanOut(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: pipeline template ----
     /**
@@ -156,35 +68,7 @@ export class SwarmGraph {
      * transition (e.g. loop back for review cycles).
      */
     static pipeline(config) {
-        if (config.stages.length === 0) {
-            throw new Error("SwarmGraph.pipeline: stages must contain at least one agent.");
-        }
-        const swarm = new SwarmGraph(config.channels);
-        const ids = config.stages.map((a) => a.id);
-        for (const agentDef of config.stages) {
-            swarm.addAgent(agentDef);
-        }
-        // Wire: START → first stage
-        swarm.inner.addEdge(START, ids[0]);
-        // Wire each stage to the next (or conditional)
-        for (let i = 0; i < ids.length - 1; i++) {
-            const id = ids[i];
-            if (config.transitions?.[id]) {
-                swarm.addConditionalHandoff(id, config.transitions[id]);
-            }
-            else {
-                swarm.inner.addEdge(id, ids[i + 1]);
-            }
-        }
-        // Wire last stage
-        const lastId = ids[ids.length - 1];
-        if (config.transitions?.[lastId]) {
-            swarm.addConditionalHandoff(lastId, config.transitions[lastId]);
-        }
-        else {
-            swarm.inner.addEdge(lastId, END);
-        }
-        return swarm;
+        return buildPipeline(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: peer network template ----
     /**
@@ -192,17 +76,7 @@ export class SwarmGraph {
      * via conditional handoffs, with no supervisor.
      */
     static peerNetwork(config) {
-        const swarm = new SwarmGraph(config.channels);
-        for (const agentDef of config.agents) {
-            swarm.addAgent(agentDef);
-        }
-        // Wire: START → entrypoint
-        swarm.inner.addEdge(START, config.entrypoint);
-        // Wire each agent's conditional handoff
-        for (const [agentId, handoffFn] of Object.entries(config.handoffs)) {
-            swarm.addConditionalHandoff(agentId, handoffFn);
-        }
-        return swarm;
+        return buildPeerNetwork(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: map-reduce template ----
     /**
@@ -210,74 +84,7 @@ export class SwarmGraph {
      * fan-out via Send, and collect results through a reducer node.
      */
     static mapReduce(config) {
-        const poolSize = config.poolSize ?? 1;
-        if (poolSize < 1) {
-            throw new Error("SwarmGraph.mapReduce: poolSize must be at least 1.");
-        }
-        const swarm = new SwarmGraph(config.channels);
-        // Register poolSize copies of the mapper agent
-        const mapperIds = [];
-        for (let i = 0; i < poolSize; i++) {
-            const id = poolSize === 1 ? config.mapper.id : `${config.mapper.id}_${i}`;
-            mapperIds.push(id);
-            swarm.addAgent({
-                ...config.mapper,
-                id,
-            });
-        }
-        // Splitter node: passthrough — the conditional edge handles fan-out via Send
-        swarm.inner.addNode("__splitter__", (_state) => {
-            return {};
-        });
-        // Reducer node: collects agentResults and applies user reducer
-        swarm.inner.addNode("__reducer__", (state) => {
-            return config.reducer(state.agentResults ?? {});
-        });
-        // Wiring: START → __splitter__
-        swarm.inner.addEdge(START, "__splitter__");
-        // __splitter__ → Send to mapper agents using the configured poolStrategy
-        const inputField = config.inputField;
-        const strategy = config.poolStrategy ?? "round-robin";
-        swarm.inner.addConditionalEdges("__splitter__", ((state) => {
-            const items = state[inputField];
-            if (!Array.isArray(items) || items.length === 0) {
-                return "__reducer__";
-            }
-            // Per-batch assignment counts — used by least-busy strategy
-            const assignCounts = new Map(mapperIds.map((id) => [id, 0]));
-            return items.map((item, idx) => {
-                let targetId;
-                if (strategy === "random") {
-                    targetId = mapperIds[Math.floor(Math.random() * mapperIds.length)];
-                }
-                else if (strategy === "least-busy") {
-                    // Pick the mapper with fewest assignments in this batch so far
-                    let minCount = Infinity;
-                    let minId = mapperIds[0];
-                    for (const id of mapperIds) {
-                        const c = assignCounts.get(id) ?? 0;
-                        if (c < minCount) {
-                            minCount = c;
-                            minId = id;
-                        }
-                    }
-                    targetId = minId;
-                }
-                else {
-                    // round-robin (default)
-                    targetId = mapperIds[idx % mapperIds.length];
-                }
-                assignCounts.set(targetId, (assignCounts.get(targetId) ?? 0) + 1);
-                return new Send(targetId, { ...state, task: String(item) });
-            });
-        }));
-        // Each mapper → __reducer__
-        for (const id of mapperIds) {
-            swarm.inner.addEdge(id, "__reducer__");
-        }
-        // __reducer__ → END
-        swarm.inner.addEdge("__reducer__", END);
-        return swarm;
+        return buildMapReduce(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: debate template ----
     /**
@@ -286,108 +93,7 @@ export class SwarmGraph {
      * and decides whether consensus has been reached.
      */
     static debate(config) {
-        if (config.debaters.length === 0) {
-            throw new Error("SwarmGraph.debate: debaters must contain at least one agent.");
-        }
-        const swarm = new SwarmGraph(config.channels);
-        const debaterIds = config.debaters.map((d) => d.id);
-        const consensusKeyword = config.judge.consensusKeyword ?? "CONSENSUS";
-        for (const debater of config.debaters) {
-            swarm.addAgent(debater);
-        }
-        const scoreDebaters = config.judge.scoreDebaters ?? false;
-        const consensusThreshold = config.judge.consensusThreshold;
-        // Judge node: evaluates arguments, decides continue or consensus
-        swarm.inner.addNode("__judge__", async (state) => {
-            const round = state.supervisorRound ?? 0;
-            // If no agent results yet (first round), just kick off debaters
-            const results = state.agentResults ?? {};
-            if (round === 0 && Object.keys(results).length === 0) {
-                return {
-                    supervisorRound: round + 1,
-                };
-            }
-            // Evaluate arguments via judge model
-            const argsText = Object.entries(results)
-                .map(([id, r]) => `${id}: ${JSON.stringify(r)}`)
-                .join("\n\n");
-            const scoreInstruction = scoreDebaters
-                ? `\nAlso provide a JSON object with scores for each debater and a verdict. Format: {"scores": {"debater_id": score}, "verdict": "CONTINUE" or "${consensusKeyword}"}`
-                : "";
-            const response = await config.judge.model.chat({
-                messages: [{
-                        role: "user",
-                        content: `Round ${round}. Evaluate these arguments:\n\n${argsText}\n\nRespond "${consensusKeyword}" if consensus reached, otherwise "CONTINUE".${scoreInstruction}`,
-                    }],
-                systemPrompt: config.judge.systemPrompt ?? "You are a debate judge.",
-            });
-            let isConsensus = false;
-            let roundScores;
-            const existingScores = (state.context.debateScores ?? []);
-            // Try to parse structured response (JSON with scores + verdict)
-            if (scoreDebaters) {
-                try {
-                    const parsed = JSON.parse(response.content);
-                    if (parsed.scores) {
-                        roundScores = parsed.scores;
-                    }
-                    if (parsed.verdict) {
-                        isConsensus = parsed.verdict.includes(consensusKeyword);
-                    }
-                }
-                catch {
-                    // Fallback to keyword detection
-                    isConsensus = response.content.includes(consensusKeyword);
-                }
-                // Check consensus threshold if scores available
-                if (!isConsensus && roundScores && consensusThreshold != null) {
-                    const scoreValues = Object.values(roundScores);
-                    if (scoreValues.length >= 2) {
-                        const spread = Math.max(...scoreValues) - Math.min(...scoreValues);
-                        if (spread <= consensusThreshold) {
-                            isConsensus = true;
-                        }
-                    }
-                }
-            }
-            else {
-                isConsensus = response.content.includes(consensusKeyword);
-            }
-            const nextRound = round + 1;
-            // Force done if consensus or max rounds exhausted
-            const isDone = isConsensus || nextRound > config.judge.maxRounds;
-            const updatedScores = roundScores
-                ? [...existingScores, { round, scores: roundScores }]
-                : existingScores;
-            return {
-                done: isDone,
-                supervisorRound: nextRound,
-                context: {
-                    ...(state.context ?? {}),
-                    ...(scoreDebaters ? { debateScores: updatedScores } : {}),
-                },
-                messages: [{ role: "system", content: `Judge round ${round}: ${isDone ? "Consensus" : "Continue"}` }],
-            };
-        });
-        // Fan-out node: passthrough — conditional edges handle the Send dispatch
-        swarm.inner.addNode("__fanout__", (_state) => {
-            return {};
-        });
-        // Wiring: START → __judge__
-        swarm.inner.addEdge(START, "__judge__");
-        // __judge__ → conditional (done → END, else → __fanout__)
-        swarm.inner.addConditionalEdges("__judge__", (state) => {
-            if (state.done)
-                return END;
-            return "__fanout__";
-        });
-        // __fanout__ → Send to all debaters in parallel
-        swarm.inner.addConditionalEdges("__fanout__", ((state) => debaterIds.map((id) => new Send(id, { ...state }))));
-        // Each debater → __judge__
-        for (const id of debaterIds) {
-            swarm.inner.addEdge(id, "__judge__");
-        }
-        return swarm;
+        return buildDebate(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: hierarchical mesh template ----
     /**
@@ -396,108 +102,7 @@ export class SwarmGraph {
      * and compiled into a single node in the outer graph.
      */
     static hierarchicalMesh(config) {
-        const swarm = new SwarmGraph(config.channels);
-        const teamIds = Object.keys(config.teams);
-        const maxRounds = config.coordinator.maxRounds ?? 10;
-        // Build each team as a compiled sub-skeleton and mount as a node
-        for (const [teamId, teamConfig] of Object.entries(config.teams)) {
-            let teamSwarm;
-            if (teamConfig.topology === "pipeline") {
-                teamSwarm = SwarmGraph.pipeline({ stages: teamConfig.agents });
-            }
-            else {
-                teamSwarm = SwarmGraph.peerNetwork({
-                    agents: teamConfig.agents,
-                    entrypoint: teamConfig.agents[0].id,
-                    handoffs: teamConfig.handoffs ?? {},
-                });
-            }
-            const teamSkeleton = teamSwarm.compile();
-            // Mount team as a single node in the outer graph.
-            // Spread all top-level fields from teamResult (including done, context)
-            // so they propagate to the outer coordinator state.
-            swarm.inner.addNode(teamId, async (state, cfg) => {
-                const teamResult = await teamSkeleton.invoke(state, cfg);
-                return {
-                    ...teamResult,
-                    agentResults: {
-                        ...(state.agentResults ?? {}),
-                        [teamId]: teamResult,
-                    },
-                };
-            });
-        }
-        // Coordinator node: routes to teams
-        swarm.inner.addNode("__coordinator__", async (state) => {
-            const round = state.supervisorRound ?? 0;
-            if (round >= maxRounds || state.done) {
-                return { done: true };
-            }
-            if (config.coordinator.strategy === "llm" && config.coordinator.model) {
-                const teamList = teamIds.map((id) => `- ${id}`).join("\n");
-                const response = await config.coordinator.model.chat({
-                    messages: [{
-                            role: "user",
-                            content: `Task: ${state.task}\n\nAvailable teams:\n${teamList}\n\nRespond with the team name to route to, or "DONE" if complete.`,
-                        }],
-                    systemPrompt: config.coordinator.systemPrompt ?? "You coordinate teams.",
-                });
-                const picked = response.content.trim();
-                if (picked === "DONE" || !teamIds.includes(picked)) {
-                    return { done: true, supervisorRound: round + 1 };
-                }
-                return new Command({
-                    update: { supervisorRound: round + 1, currentAgent: picked },
-                    goto: picked,
-                });
-            }
-            // Round-robin strategy: route to teams in order, mark done after all visited
-            if (config.coordinator.strategy === "round-robin") {
-                const target = teamIds[round % teamIds.length];
-                if (round >= teamIds.length) {
-                    return { done: true };
-                }
-                return new Command({
-                    update: { supervisorRound: round + 1 },
-                    goto: target,
-                });
-            }
-            // Rule-based strategy: evaluate rules in order, route to the first match
-            if (config.coordinator.strategy === "rule") {
-                const rules = config.coordinator.rules ?? [];
-                const task = String(state.task ?? "");
-                const ctx = (state.context ?? {});
-                for (const rule of rules) {
-                    if (rule.condition(task, ctx)) {
-                        return new Command({
-                            update: { supervisorRound: round + 1, currentAgent: rule.agentId },
-                            goto: rule.agentId,
-                        });
-                    }
-                }
-                // No matching rule — done
-                return { done: true, supervisorRound: round + 1 };
-            }
-            return { done: true };
-        });
-        // Wiring: START → coordinator
-        swarm.inner.addEdge(START, "__coordinator__");
-        // Each team → coordinator (loop back unless done)
-        for (const teamId of teamIds) {
-            swarm.inner.addConditionalEdges(teamId, (state) => {
-                if (state.done)
-                    return END;
-                return "__coordinator__";
-            });
-        }
-        // Coordinator → conditional (done → END, else handled by Command.goto)
-        swarm.inner.addConditionalEdges("__coordinator__", (state) => {
-            if (state.done)
-                return END;
-            // Command.goto handles routing — this is the fallback
-            return END;
-        });
-        return swarm;
+        return buildHierarchicalMesh(config, new SwarmGraph(config.channels), (ch) => new SwarmGraph(ch));
     }
     // ---- Static factory: race template ----
     /**
@@ -505,67 +110,7 @@ export class SwarmGraph {
      * Optionally filter results with an `accept` predicate.
      */
     static race(config) {
-        const swarm = new SwarmGraph(config.channels);
-        const agentIds = config.agents.map((a) => a.id);
-        const accept = config.accept ?? (() => true);
-        const timeoutMs = config.timeoutMs;
-        // Register agents so they appear in the registry
-        for (const agentDef of config.agents) {
-            swarm.registry.register(agentDef);
-            swarm.agentIds.add(agentDef.id);
-        }
-        // Single node that races all agents — resolves as soon as one produces
-        // an acceptable result (true Promise.race semantics, not Promise.all).
-        swarm.inner.addNode("__race__", async (state, cfg) => {
-            const agentPromises = config.agents.map((agent) => {
-                const p = agent.skeleton
-                    .invoke({ ...state }, { ...cfg, agentId: agent.id })
-                    .then((result) => ({ id: agent.id, result, error: null }), (err) => ({ id: agent.id, result: null, error: err }));
-                if (timeoutMs != null) {
-                    return Promise.race([
-                        p,
-                        new Promise((resolve) => setTimeout(() => resolve({ id: agent.id, result: null, error: new Error("timeout") }), timeoutMs)),
-                    ]);
-                }
-                return p;
-            });
-            // Resolve as soon as the first acceptable result arrives.
-            const winner = await new Promise((resolve) => {
-                let remaining = agentPromises.length;
-                if (remaining === 0) {
-                    resolve(null);
-                    return;
-                }
-                for (const p of agentPromises) {
-                    p.then((r) => {
-                        if (!r.error && accept(r.result)) {
-                            resolve(r);
-                        }
-                        else {
-                            remaining--;
-                            if (remaining === 0)
-                                resolve(null);
-                        }
-                    });
-                }
-            });
-            if (winner) {
-                return {
-                    agentResults: { [winner.id]: winner.result },
-                    context: { ...(state.context ?? {}), raceWinner: winner.id },
-                };
-            }
-            // No acceptable result
-            return {
-                context: {
-                    ...(state.context ?? {}),
-                    raceError: "No agent produced an acceptable result",
-                },
-            };
-        });
-        swarm.inner.addEdge(START, "__race__");
-        swarm.inner.addEdge("__race__", END);
-        return swarm;
+        return buildRace(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: dag template ----
     /**
@@ -573,82 +118,7 @@ export class SwarmGraph {
      * Agents with no dependencies run in parallel.
      */
     static dag(config) {
-        const agentMap = new Map(config.agents.map((a) => [a.id, a]));
-        // Validate dependencies
-        for (const [node, deps] of Object.entries(config.dependencies)) {
-            for (const dep of deps) {
-                if (!agentMap.has(dep)) {
-                    throw new Error(`Dependency "${dep}" not found in agents list.`);
-                }
-            }
-        }
-        // Cycle detection via topological sort
-        const visited = new Set();
-        const visiting = new Set();
-        const sorted = [];
-        function visit(id) {
-            if (visited.has(id))
-                return;
-            if (visiting.has(id))
-                throw new Error(`Cycle detected involving "${id}".`);
-            visiting.add(id);
-            for (const dep of config.dependencies[id] ?? []) {
-                visit(dep);
-            }
-            visiting.delete(id);
-            visited.add(id);
-            sorted.push(id);
-        }
-        for (const agent of config.agents) {
-            visit(agent.id);
-        }
-        // Build a standard swarm with wiring based on topological sort
-        const swarm = new SwarmGraph(config.channels);
-        for (const agent of config.agents) {
-            swarm.addAgent(agent);
-        }
-        // Group agents into layers based on dependencies
-        const deps = config.dependencies;
-        const rootIds = config.agents.filter((a) => !deps[a.id]?.length).map((a) => a.id);
-        const nonRootIds = config.agents.filter((a) => deps[a.id]?.length).map((a) => a.id);
-        // For DAG execution: use a single orchestrator node
-        swarm.inner.addNode("__dag_runner__", async (state, cfg) => {
-            const results = {};
-            const completed = new Set();
-            // Process in topological order
-            // Group into parallel batches
-            const remaining = new Set(sorted);
-            while (remaining.size > 0) {
-                // Find all nodes whose deps are satisfied
-                const ready = [];
-                for (const id of remaining) {
-                    const idDeps = deps[id] ?? [];
-                    if (idDeps.every((d) => completed.has(d))) {
-                        ready.push(id);
-                    }
-                }
-                // Execute ready nodes in parallel
-                const batchResults = await Promise.all(ready.map(async (id) => {
-                    const agent = agentMap.get(id);
-                    const result = await agent.skeleton.invoke({ ...state, agentResults: { ...(state.agentResults ?? {}), ...results } }, { ...cfg, agentId: id });
-                    return { id, result };
-                }));
-                for (const { id, result } of batchResults) {
-                    results[id] = result;
-                    completed.add(id);
-                    remaining.delete(id);
-                }
-            }
-            return {
-                agentResults: { ...(state.agentResults ?? {}), ...results },
-            };
-        });
-        // Wire: START → __dag_runner__ → END
-        // Remove any edges added by addAgent
-        swarm.inner.edges = [];
-        swarm.inner.addEdge(START, "__dag_runner__");
-        swarm.inner.addEdge("__dag_runner__", END);
-        return swarm;
+        return buildDag(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: pool template ----
     /**
@@ -656,90 +126,7 @@ export class SwarmGraph {
      * then reduce all results.
      */
     static pool(config) {
-        const swarm = new SwarmGraph(config.channels);
-        const poolSize = config.poolSize;
-        // Create pool copies
-        const poolIds = [];
-        for (let i = 0; i < poolSize; i++) {
-            const id = poolSize === 1 ? config.agent.id : `${config.agent.id}_${i}`;
-            poolIds.push(id);
-            swarm.addAgent({ ...config.agent, id });
-        }
-        // Orchestrator node: dispatches items to pool agents and reduces
-        swarm.inner.addNode("__pool_runner__", async (state, cfg) => {
-            const items = state[config.inputField];
-            if (!Array.isArray(items) || items.length === 0) {
-                return config.reducer({});
-            }
-            // Semaphore for concurrency control
-            let running = 0;
-            const results = {};
-            const queue = items.map((item, idx) => ({
-                item,
-                idx,
-                targetId: poolIds[idx % poolIds.length],
-            }));
-            await new Promise((resolve, reject) => {
-                let completed = 0;
-                const total = queue.length;
-                function processNext() {
-                    while (running < poolSize && queue.length > 0) {
-                        const work = queue.shift();
-                        // Respect removeAgent() — if the assigned slot was removed, redirect
-                        // to an active pool slot; if none remain, mark the item as failed.
-                        let agentDef = swarm.registry.getDef(work.targetId);
-                        if (!agentDef) {
-                            const activeIds = poolIds.filter((id) => !!swarm.registry.getDef(id));
-                            if (activeIds.length > 0) {
-                                work.targetId = activeIds[work.idx % activeIds.length];
-                                agentDef = swarm.registry.getDef(work.targetId);
-                            }
-                            else {
-                                results[`item_${work.idx}`] = { _error: `Pool slot removed; no active agents remain` };
-                                completed++;
-                                if (completed === total)
-                                    resolve();
-                                continue;
-                            }
-                        }
-                        running++;
-                        // Use the full wrapped agentNode (hooks, retries, timeout) stored
-                        // by addAgent() in swarm.inner.nodes rather than raw skeleton.invoke.
-                        const wrappedFn = swarm.inner.nodes.get(work.targetId)?.fn;
-                        const invocation = wrappedFn
-                            ? wrappedFn({ ...state, task: String(work.item) }, { ...cfg, agentId: work.targetId })
-                            : agentDef.skeleton.invoke({ ...state, task: String(work.item) }, { ...cfg, agentId: work.targetId });
-                        invocation.then((result) => {
-                            results[`item_${work.idx}`] = result;
-                            running--;
-                            completed++;
-                            if (completed === total)
-                                resolve();
-                            else
-                                processNext();
-                        }, (err) => {
-                            results[`item_${work.idx}`] = { _error: String(err) };
-                            running--;
-                            completed++;
-                            if (completed === total)
-                                resolve();
-                            else
-                                processNext();
-                        });
-                    }
-                }
-                if (total === 0)
-                    resolve();
-                else
-                    processNext();
-            });
-            return config.reducer(results);
-        });
-        // Wire: START → __pool_runner__ → END (bypass agent edges)
-        swarm.inner.edges = [];
-        swarm.inner.addEdge(START, "__pool_runner__");
-        swarm.inner.addEdge("__pool_runner__", END);
-        return swarm;
+        return buildPool(config, new SwarmGraph(config.channels));
     }
     // ---- Static factory: compose template ----
     /**
@@ -747,179 +134,13 @@ export class SwarmGraph {
      * Each stage runs a compiled sub-swarm, passing state through.
      */
     static compose(config) {
-        if (config.stages.length === 0) {
-            throw new Error("SwarmGraph.compose: stages must contain at least one sub-swarm.");
-        }
-        const swarm = new SwarmGraph(config.channels);
-        const stageIds = config.stages.map((s) => s.id);
-        for (const stage of config.stages) {
-            const compiled = stage.swarm.compile();
-            swarm.inner.addNode(stage.id, async (state, cfg) => {
-                const stageResult = await compiled.invoke(state, cfg);
-                return {
-                    ...stageResult,
-                    agentResults: {
-                        ...(state.agentResults ?? {}),
-                        [stage.id]: stageResult,
-                    },
-                };
-            });
-        }
-        // Wire pipeline: START → stage1 → stage2 → ... → END
-        swarm.inner.addEdge(START, stageIds[0]);
-        for (let i = 0; i < stageIds.length - 1; i++) {
-            swarm.inner.addEdge(stageIds[i], stageIds[i + 1]);
-        }
-        swarm.inner.addEdge(stageIds[stageIds.length - 1], END);
-        return swarm;
+        return buildCompose(config, new SwarmGraph(config.channels));
     }
     // ---- Agent registration ----
     addAgent(def) {
         this.registry.register(def);
         this.agentIds.add(def.id);
-        // Wrap the agent's skeleton as a node
-        // The node executes the agent's skeleton and handles Handoff returns
-        const agentNode = async (state, config) => {
-            this.registry.markBusy(def.id);
-            // Fire onStart hook
-            await def.hooks?.onStart?.(def.id, state);
-            const maxRetries = def.maxRetries ?? 2;
-            const retryDelayMs = def.retryDelayMs ?? 0;
-            let lastError;
-            let lastAttempt = 0;
-            for (let attempt = 0; attempt <= maxRetries; attempt++) {
-                lastAttempt = attempt;
-                try {
-                    // Get inbox and filter out already-consumed messages
-                    const consumedIds = (state.context?.__consumedMsgIds ?? []);
-                    const consumedSet = new Set(consumedIds);
-                    const allInbox = getInbox(state.swarmMessages ?? [], def.id);
-                    const inbox = allInbox.filter((m) => !consumedSet.has(m.id));
-                    // Track consumed message IDs
-                    const newConsumedIds = [...consumedIds, ...inbox.map((m) => m.id)];
-                    const agentInput = {
-                        ...state,
-                        context: {
-                            ...(state.context ?? {}),
-                            inbox,
-                            __consumedMsgIds: newConsumedIds,
-                        },
-                    };
-                    let effectiveTimeout = def.timeout;
-                    // Clamp agent timeout to remaining deadline (if set)
-                    const deadlineAbs = state.context?.__deadlineAbsolute;
-                    if (deadlineAbs != null) {
-                        const remaining = deadlineAbs - Date.now();
-                        if (remaining <= 0) {
-                            throw new Error(`Agent "${def.id}" deadline expired`);
-                        }
-                        if (effectiveTimeout == null || remaining < effectiveTimeout) {
-                            effectiveTimeout = remaining;
-                        }
-                    }
-                    const result = await runWithTimeout(() => def.skeleton.invoke(agentInput, {
-                        ...config,
-                        agentId: def.id,
-                    }), effectiveTimeout, () => new Error(`Agent "${def.id}" timed out after ${effectiveTimeout}ms`));
-                    this.registry.markIdle(def.id);
-                    // ---- Handoff detection ----
-                    if (result instanceof Handoff || (result && result.isHandoff)) {
-                        const handoff = result instanceof Handoff
-                            ? result
-                            : new Handoff(result.opts);
-                        // Fire onComplete for handoffs too
-                        await def.hooks?.onComplete?.(def.id, result);
-                        return new Command({
-                            update: {
-                                context: { ...(state.context ?? {}), ...(handoff.context ?? {}) },
-                                handoffHistory: [{
-                                        from: def.id,
-                                        to: handoff.to,
-                                        message: handoff.message,
-                                        step: state.supervisorRound ?? 0,
-                                        timestamp: Date.now(),
-                                        resume: handoff.resume,
-                                    }],
-                                currentAgent: handoff.to,
-                            },
-                            goto: handoff.to,
-                        });
-                    }
-                    // Fire onComplete hook
-                    await def.hooks?.onComplete?.(def.id, result);
-                    // ---- Normal result ----
-                    return {
-                        ...result,
-                        context: {
-                            ...(result.context ?? {}),
-                            __consumedMsgIds: newConsumedIds,
-                        },
-                        agentResults: {
-                            ...(state.agentResults ?? {}),
-                            [def.id]: result,
-                        },
-                        handoffHistory: [
-                            ...(state.handoffHistory ?? []),
-                            {
-                                from: def.id,
-                                to: "__completed__",
-                                message: "Agent completed",
-                                step: state.supervisorRound ?? 0,
-                                timestamp: Date.now(),
-                            },
-                        ],
-                    };
-                }
-                catch (err) {
-                    lastError = err;
-                    this.registry.markError(def.id);
-                    if (attempt < maxRetries) {
-                        // Backoff delay between retries — clamped to remaining deadline
-                        if (retryDelayMs > 0) {
-                            let delay = retryDelayMs;
-                            const dl = state.context?.__deadlineAbsolute;
-                            if (dl != null) {
-                                const remaining = dl - Date.now();
-                                if (remaining <= 0)
-                                    break; // deadline expired, stop retrying
-                                delay = Math.min(delay, remaining);
-                            }
-                            await new Promise((r) => setTimeout(r, delay));
-                        }
-                        continue; // retry
-                    }
-                }
-            }
-            // All retries exhausted — fire onError hook
-            await def.hooks?.onError?.(def.id, lastError);
-            // Keep agent in error status (don't reset to idle)
-            // Build structured error context
-            const errStr = String(lastError instanceof Error ? lastError.message : lastError);
-            const errType = errStr.includes("timeout") ? "timeout" :
-                errStr.includes("model") ? "model_error" :
-                    errStr.includes("tool") ? "tool_error" :
-                        "unknown";
-            if (this.hasSupervisor && this.onErrorPolicy !== "throw") {
-                return new Command({
-                    update: {
-                        context: {
-                            ...(state.context ?? {}),
-                            lastAgentError: {
-                                agent: def.id,
-                                error: errStr,
-                                type: errType,
-                                attempt: lastAttempt,
-                                maxRetries,
-                            },
-                        },
-                    },
-                    goto: this.supervisorNodeName,
-                });
-            }
-            // No supervisor, or onError: "throw" — rethrow
-            throw lastError;
-        };
-        this.inner.addNode(def.id, agentNode);
+        this.inner.addNode(def.id, createAgentNode(def, this.registry, this));
         return this;
     }
     // ---- Supervisor ----
@@ -976,7 +197,8 @@ export class SwarmGraph {
             return issues;
         // For non-supervised swarms, check that every agent has at least one incoming edge
         const edgeTargets = new Set();
-        for (const edge of this.inner.edges) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const edge of this.inner.edges) { // SAFE: external boundary — accessing private StateGraph.edges for topology validation
             if (edge.type === "static") {
                 edgeTargets.add(edge.to);
             }
@@ -1011,99 +233,18 @@ export class SwarmGraph {
     // ---- Compile ----
     compile(opts = {}) {
         const skeleton = this.inner.compile({
-            ...(opts.checkpointer ? { checkpointer: opts.checkpointer } : {}),
-            ...(opts.interruptBefore ? { interruptBefore: opts.interruptBefore } : {}),
-            ...(opts.interruptAfter ? { interruptAfter: opts.interruptAfter } : {}),
-        });
-        const registry = this.registry;
-        const inner = this.inner;
-        const hasSupervisor = this.hasSupervisor;
-        const supervisorNodeName = this.supervisorNodeName;
-        const self = this;
-        // Attach swarm-specific extensions
-        const extensions = {
-            registry,
-            agentStats: () => registry.stats(),
-            toMermaid: () => inner.toMermaid(),
-            spawnAgent(def) {
-                // spawnAgent requires a supervisor to route the spawned agent back into the graph.
-                // In unsupervised topologies there is no return path, so the agent would never execute.
-                if (!hasSupervisor) {
-                    throw new Error(`spawnAgent() requires a supervisor node. ` +
-                        `Use SwarmGraph.hierarchical() to add a supervisor, or call addAgent() before compile() for static topologies.`);
-                }
-                // Register in the registry
-                registry.register(def);
-                // Create the agent node function (same logic as addAgent)
-                const agentNode = async (state, config) => {
-                    registry.markBusy(def.id);
-                    await def.hooks?.onStart?.(def.id, state);
-                    const maxRetries = def.maxRetries ?? 2;
-                    let lastError;
-                    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-                        try {
-                            const result = await def.skeleton.invoke({ ...state, context: { ...(state.context ?? {}), inbox: getInbox(state.swarmMessages ?? [], def.id) } }, { ...config, agentId: def.id });
-                            registry.markIdle(def.id);
-                            await def.hooks?.onComplete?.(def.id, result);
-                            return {
-                                ...result,
-                                agentResults: { ...(state.agentResults ?? {}), [def.id]: result },
-                            };
-                        }
-                        catch (err) {
-                            lastError = err;
-                            registry.markError(def.id);
-                            if (attempt < maxRetries)
-                                continue;
-                        }
-                    }
-                    await def.hooks?.onError?.(def.id, lastError);
-                    // Keep agent in error status (don't reset to idle)
-                    if (hasSupervisor) {
-                        return new Command({
-                            update: { context: { ...(state.context ?? {}), lastAgentError: { agent: def.id, error: String(lastError) } } },
-                            goto: supervisorNodeName,
-                        });
-                    }
-                    throw lastError;
-                };
-                // Add node to the compiled runner's nodes map
-                const runner = skeleton._runner;
-                if (runner?.nodes) {
-                    runner.nodes.set(def.id, { name: def.id, fn: agentNode });
-                }
-                // In supervised swarms, add a conditional return edge so the runner
-                // knows to send this agent's output back to the supervisor (or END).
-                if (hasSupervisor && runner) {
-                    const returnEdge = {
-                        type: "conditional",
-                        from: def.id,
-                        condition: (st) => st.done ? END : supervisorNodeName,
-                    };
-                    const edgesBySource = runner._edgesBySource;
-                    const list = edgesBySource.get(def.id) ?? [];
-                    list.push(returnEdge);
-                    edgesBySource.set(def.id, list);
-                }
-            },
-            removeAgent(agentId) {
-                registry.deregister(agentId);
-                const runner = skeleton._runner;
-                if (runner?.nodes)
-                    runner.nodes.delete(agentId);
-                // Remove stale edges pointing TO the removed agent so Pregel doesn't try to route to it.
-                // Also remove edges FROM the agent (it won't execute, but keeps _edgesBySource clean).
-                if (runner?._edgesBySource) {
-                    const edgesBySource = runner._edgesBySource;
-                    for (const [from, edges] of edgesBySource) {
-                        const filtered = edges.filter((e) => !(e.type === "static" && e.to === agentId));
-                        if (filtered.length !== edges.length)
-                            edgesBySource.set(from, filtered);
-                    }
-                    edgesBySource.delete(agentId);
-                }
-            },
-        };
+            ...(opts.checkpointer !== undefined ? { checkpointer: opts.checkpointer } : {}),
+            ...(opts.interruptBefore !== undefined ? { interruptBefore: opts.interruptBefore } : {}),
+            ...(opts.interruptAfter !== undefined ? { interruptAfter: opts.interruptAfter } : {}),
+            ...(opts.store !== undefined ? { store: opts.store } : {}),
+            ...(opts.guardrails !== undefined ? { guardrails: opts.guardrails } : {}),
+            ...(opts.listeners !== undefined ? { listeners: opts.listeners } : {}),
+            ...(opts.defaults !== undefined ? { defaults: opts.defaults } : {}),
+            ...(opts.deadLetterQueue !== undefined ? { deadLetterQueue: opts.deadLetterQueue } : {}),
+            ...(opts.tracer !== undefined ? { tracer: opts.tracer } : {}),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }); // SAFE: CompileOptions conditional spread — TypeScript can't narrow the intersection type
+        const extensions = buildSwarmExtensions(skeleton, this.registry, this.inner, this.hasSupervisor, this.supervisorNodeName, this.onErrorPolicy);
         return Object.assign(skeleton, extensions);
     }
 }
@@ -1134,4 +275,5 @@ export function quickAgent(id, fn, opts) {
         retryDelayMs: opts?.retryDelayMs,
     };
 }
+export { baseSwarmChannels } from "./config.js";
 //# sourceMappingURL=graph.js.map