@oni.bot/core 0.6.3 → 1.0.0

package/dist/swarm/graph.js

@@ -16,6 +16,7 @@ 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(() => ({})),
@@ -72,6 +73,8 @@ export class SwarmGraph {
             rules: config.supervisor.rules,
             systemPrompt: config.supervisor.systemPrompt,
             maxRounds: config.supervisor.maxRounds,
+            deadlineMs: config.supervisor.deadlineMs,
+            autoRecover: config.supervisor.autoRecover,
         });
         return swarm;
     }
@@ -82,29 +85,66 @@ export class SwarmGraph {
      */
     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.addAgent(agentDef);
+            swarm.registry.register(agentDef);
+            swarm.agentIds.add(agentDef.id);
         }
-        // Fan-out node: passthrough that triggers conditional edges with Send
-        const agentIds = config.agents.map((a) => a.id);
-        swarm.inner.addNode("__fanout__", (_state) => {
-            // No state mutation — the conditional edge handles fan-out via Send
-            return {};
-        });
-        // Reducer node: collects agentResults and applies user reducer
-        swarm.inner.addNode("__reducer__", (state) => {
-            return config.reducer(state.agentResults ?? {});
+        // 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 };
         });
-        // Wiring: START → __fanout__
-        swarm.inner.addEdge(START, "__fanout__");
-        // __fanout__ → Send to all agents in parallel
-        swarm.inner.addConditionalEdges("__fanout__", ((state) => agentIds.map((id) => new Send(id, { ...state }))));
-        // Each agent → __reducer__
-        for (const id of agentIds) {
-            swarm.inner.addEdge(id, "__reducer__");
-        }
-        // __reducer__ → END
-        swarm.inner.addEdge("__reducer__", END);
+        swarm.inner.addEdge(START, "__fanout_runner__");
+        swarm.inner.addEdge("__fanout_runner__", END);
         return swarm;
     }
     // ---- Static factory: pipeline template ----
@@ -220,6 +260,8 @@ export class SwarmGraph {
         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;
@@ -234,21 +276,61 @@ export class SwarmGraph {
             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".`,
+                        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.",
             });
-            const isConsensus = response.content.includes(consensusKeyword);
+            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
-            // (round 0 is kick-off only, so chat is called maxRounds times)
             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"}` }],
             };
         });
@@ -364,6 +446,248 @@ export class SwarmGraph {
         });
         return swarm;
     }
+    // ---- Static factory: race template ----
+    /**
+     * Race all agents in parallel — first acceptable result wins.
+     * 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
+        swarm.inner.addNode("__race__", async (state, cfg) => {
+            const promises = config.agents.map(async (agent) => {
+                try {
+                    const result = await agent.skeleton.invoke({ ...state }, { ...cfg, agentId: agent.id });
+                    return { id: agent.id, result, error: null };
+                }
+                catch (err) {
+                    return { id: agent.id, result: null, error: err };
+                }
+            });
+            let allResults;
+            if (timeoutMs != null) {
+                // Wrap each promise with a timeout
+                const timedPromises = promises.map((p) => Promise.race([
+                    p,
+                    new Promise((resolve) => setTimeout(() => resolve({ id: "?", result: null, error: new Error("timeout") }), timeoutMs)),
+                ]));
+                allResults = await Promise.all(timedPromises);
+            }
+            else {
+                allResults = await Promise.all(promises);
+            }
+            // Find the first acceptable result (in order of agent definition)
+            for (const { id, result, error } of allResults) {
+                if (!error && accept(result)) {
+                    return {
+                        agentResults: { [id]: result },
+                        context: { ...(state.context ?? {}), raceWinner: 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;
+    }
+    // ---- Static factory: dag template ----
+    /**
+     * Execute agents in dependency order (directed acyclic graph).
+     * 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;
+    }
+    // ---- Static factory: pool template ----
+    /**
+     * Distribute N input items across poolSize copies of a single agent,
+     * 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();
+                        running++;
+                        const agent = swarm.registry.getDef(work.targetId)
+                            ?? config.agent;
+                        const skeleton = agent.skeleton;
+                        skeleton.invoke({ ...state, task: String(work.item) }, { ...cfg, agentId: work.targetId }).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;
+    }
+    // ---- Static factory: compose template ----
+    /**
+     * Compose multiple sub-swarms as pipeline stages.
+     * Each stage runs a compiled sub-swarm, passing state through.
+     */
+    static compose(config) {
+        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;
+    }
     // ---- Agent registration ----
     addAgent(def) {
         this.registry.register(def);
@@ -371,30 +695,55 @@ export class SwarmGraph {
         // Wrap the agent's skeleton as a node
         // The node executes the agent's skeleton and handles Handoff returns
         const agentNode = async (state, config) => {
-            console.log(`[swarm] agent="${def.id}" (${def.role}) starting`);
             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: getInbox(state.swarmMessages ?? [], def.id),
+                            inbox,
+                            __consumedMsgIds: newConsumedIds,
                         },
                     };
-                    const result = await def.skeleton.invoke(agentInput, {
+                    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);
-                    console.log(`[swarm] agent="${def.id}" completed`);
                     // ---- 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 ?? {}) },
@@ -411,9 +760,15 @@ export class SwarmGraph {
                             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,
@@ -433,21 +788,44 @@ export class SwarmGraph {
                 catch (err) {
                     lastError = err;
                     this.registry.markError(def.id);
-                    console.warn(`[swarm] agent="${def.id}" attempt ${attempt + 1}/${maxRetries + 1} failed: ${err}`);
                     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 — fallback to supervisor if one exists
-            console.warn(`[swarm] agent="${def.id}" exhausted retries, falling back`);
-            this.registry.markIdle(def.id);
+            // 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) {
                 return new Command({
                     update: {
                         context: {
                             ...(state.context ?? {}),
-                            lastAgentError: { agent: def.id, error: String(lastError) },
+                            lastAgentError: {
+                                agent: def.id,
+                                error: errStr,
+                                type: errType,
+                                attempt: lastAttempt,
+                                maxRetries,
+                            },
                         },
                     },
                     goto: this.supervisorNodeName,
@@ -501,6 +879,32 @@ export class SwarmGraph {
         this.inner.addEdge(from, to);
         return this;
     }
+    // ---- Topology validation ----
+    /**
+     * Check the swarm topology for common issues like orphan agents.
+     * Returns an array of issue strings (empty = valid).
+     */
+    validateTopology() {
+        const issues = [];
+        // In supervised swarms, all agents are reachable via Command.goto
+        if (this.hasSupervisor)
+            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) {
+            if (edge.type === "static") {
+                edgeTargets.add(edge.to);
+            }
+            // Conditional edges: the 'from' node is reachable if it has incoming edges
+            edgeTargets.add(edge.from);
+        }
+        for (const agentId of this.agentIds) {
+            if (!edgeTargets.has(agentId)) {
+                issues.push(`Agent "${agentId}" is an orphan — no edges connect to or from it.`);
+            }
+        }
+        return issues;
+    }
     // ---- Pipeline shorthand ----
     /**
      * Wire agents as a linear pipeline: A → B → C → END
@@ -522,13 +926,90 @@ export class SwarmGraph {
             ...(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: this.registry,
-            agentStats: () => this.registry.stats(),
-            toMermaid: () => this.inner.toMermaid(),
+            registry,
+            agentStats: () => registry.stats(),
+            toMermaid: () => inner.toMermaid(),
+            spawnAgent(def) {
+                // 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 });
+                }
+            },
+            removeAgent(agentId) {
+                registry.deregister(agentId);
+            },
         };
         return Object.assign(skeleton, extensions);
     }
 }
+// ----------------------------------------------------------------
+// quickAgent — convenience factory for tests and simple swarms
+// ----------------------------------------------------------------
+/**
+ * Create a SwarmAgentDef from just an id and a handler function.
+ * Builds a single-node StateGraph internally so the agent is fully
+ * functional in any SwarmGraph topology.
+ */
+export function quickAgent(id, fn, opts) {
+    const g = new StateGraph({ channels: baseSwarmChannels });
+    g.addNode("work", async (state) => fn(state));
+    g.addEdge(START, "work");
+    g.addEdge("work", END);
+    const skeleton = g.compile();
+    return {
+        id,
+        role: opts?.role ?? id,
+        capabilities: opts?.capabilities ?? [],
+        skeleton: skeleton,
+        hooks: opts?.hooks,
+        maxRetries: opts?.maxRetries,
+        maxConcurrency: opts?.maxConcurrency,
+        systemPrompt: opts?.systemPrompt,
+        timeout: opts?.timeout,
+        retryDelayMs: opts?.retryDelayMs,
+    };
+}
 //# sourceMappingURL=graph.js.map