@open-multi-agent/core 1.4.0

package/dist/agent/loop-detector.js

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Sliding-window loop detector for the agent conversation loop.
+ *
+ * Tracks tool-call signatures and text outputs across turns to detect when an
+ * agent is stuck repeating the same actions. Used by {@link AgentRunner} when
+ * {@link LoopDetectionConfig} is provided.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively sort object keys so that `{b:1, a:2}` and `{a:2, b:1}` produce
+ * the same JSON string.
+ */
+function sortKeys(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+// ---------------------------------------------------------------------------
+// LoopDetector
+// ---------------------------------------------------------------------------
+export class LoopDetector {
+    maxRepeats;
+    windowSize;
+    toolSignatures = [];
+    textOutputs = [];
+    constructor(config = {}) {
+        this.maxRepeats = config.maxRepetitions ?? 3;
+        const requestedWindow = config.loopDetectionWindow ?? 4;
+        // Window must be >= threshold, otherwise detection can never trigger.
+        this.windowSize = Math.max(requestedWindow, this.maxRepeats);
+    }
+    /**
+     * Record a turn's tool calls. Returns detection info when a loop is found.
+     */
+    recordToolCalls(blocks) {
+        if (blocks.length === 0)
+            return null;
+        const signature = this.computeToolSignature(blocks);
+        this.push(this.toolSignatures, signature);
+        const count = this.consecutiveRepeats(this.toolSignatures);
+        if (count >= this.maxRepeats) {
+            const names = blocks.map(b => b.name).join(', ');
+            return {
+                kind: 'tool_repetition',
+                repetitions: count,
+                detail: `Tool call "${names}" with identical arguments has repeated ` +
+                    `${count} times consecutively. The agent appears to be stuck in a loop.`,
+            };
+        }
+        return null;
+    }
+    /**
+     * Record a turn's text output. Returns detection info when a loop is found.
+     */
+    recordText(text) {
+        const normalised = text.trim().replace(/\s+/g, ' ');
+        if (normalised.length === 0)
+            return null;
+        this.push(this.textOutputs, normalised);
+        const count = this.consecutiveRepeats(this.textOutputs);
+        if (count >= this.maxRepeats) {
+            return {
+                kind: 'text_repetition',
+                repetitions: count,
+                detail: `The agent has produced the same text response ${count} times ` +
+                    `consecutively. It appears to be stuck in a loop.`,
+            };
+        }
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    /**
+     * Deterministic JSON signature for a set of tool calls.
+     * Sorts calls by name (for multi-tool turns) and keys within each input.
+     */
+    computeToolSignature(blocks) {
+        const items = blocks
+            .map(b => ({ name: b.name, input: sortKeys(b.input) }))
+            .sort((a, b) => {
+            const cmp = a.name.localeCompare(b.name);
+            if (cmp !== 0)
+                return cmp;
+            return JSON.stringify(a.input).localeCompare(JSON.stringify(b.input));
+        });
+        return JSON.stringify(items);
+    }
+    /** Push an entry and trim the buffer to `windowSize`. */
+    push(buffer, entry) {
+        buffer.push(entry);
+        while (buffer.length > this.windowSize) {
+            buffer.shift();
+        }
+    }
+    /**
+     * Count how many consecutive identical entries exist at the tail of `buffer`.
+     * Returns 1 when the last entry is unique.
+     */
+    consecutiveRepeats(buffer) {
+        if (buffer.length === 0)
+            return 0;
+        const last = buffer[buffer.length - 1];
+        let count = 0;
+        for (let i = buffer.length - 1; i >= 0; i--) {
+            if (buffer[i] === last)
+                count++;
+            else
+                break;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=loop-detector.js.map

package/dist/agent/loop-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detector.js","sourceRoot":"","sources":["../../src/agent/loop-detector.ts"],"names":[],"mappings":"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"}

package/dist/agent/pool.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Agent pool for managing and scheduling multiple agents.
+ *
+ * {@link AgentPool} is a registry + scheduler that:
+ *  - Holds any number of named {@link Agent} instances
+ *  - Enforces a concurrency cap across parallel runs via {@link Semaphore}
+ *  - Provides `runParallel` for fan-out and `runAny` for round-robin dispatch
+ *  - Reports aggregate pool health via `getStatus()`
+ *
+ * @example
+ * ```ts
+ * const pool = new AgentPool(3)
+ * pool.add(researchAgent)
+ * pool.add(writerAgent)
+ *
+ * const results = await pool.runParallel([
+ *   { agent: 'researcher', prompt: 'Find recent AI papers.' },
+ *   { agent: 'writer',     prompt: 'Draft an intro section.' },
+ * ])
+ * ```
+ */
+import type { AgentRunResult, StreamEvent } from '../types.js';
+import type { RunOptions } from './runner.js';
+import type { Agent } from './agent.js';
+export { Semaphore } from '../utils/semaphore.js';
+export interface PoolStatus {
+    /** Total number of agents registered in the pool. */
+    readonly total: number;
+    /** Agents currently in `idle` state. */
+    readonly idle: number;
+    /** Agents currently in `running` state. */
+    readonly running: number;
+    /** Agents currently in `completed` state. */
+    readonly completed: number;
+    /** Agents currently in `error` state. */
+    readonly error: number;
+}
+/**
+ * Registry and scheduler for a collection of {@link Agent} instances.
+ *
+ * Thread-safety note: Node.js is single-threaded, so the semaphore approach
+ * is safe — no atomics or mutex primitives are needed. The semaphore gates
+ * concurrent async operations, not CPU threads.
+ */
+export declare class AgentPool {
+    private readonly maxConcurrency;
+    private readonly agents;
+    private readonly semaphore;
+    /**
+     * Per-agent mutex (Semaphore(1)) to serialize concurrent runs on the same
+     * Agent instance.  Without this, two tasks assigned to the same agent could
+     * race on mutable instance state (`status`, `messages`, `tokenUsage`).
+     *
+     * @see https://github.com/anthropics/open-multi-agent/issues/72
+     */
+    private readonly agentLocks;
+    /** Cursor used by `runAny` for round-robin dispatch. */
+    private roundRobinIndex;
+    /**
+     * @param maxConcurrency - Maximum number of agent runs allowed at the same
+     *                         time across the whole pool. Defaults to `5`.
+     */
+    constructor(maxConcurrency?: number);
+    /**
+     * Pool semaphore slots not currently held (`maxConcurrency - active`).
+     * Used to avoid deadlocks when a nested `run()` would wait forever for a slot
+     * held by the parent run. Best-effort only if multiple nested runs start in
+     * parallel after the same synchronous check.
+     */
+    get availableRunSlots(): number;
+    /**
+     * Register an agent with the pool.
+     *
+     * @throws {Error} If an agent with the same name is already registered.
+     */
+    add(agent: Agent): void;
+    /**
+     * Unregister an agent by name.
+     *
+     * @throws {Error} If the agent is not found.
+     */
+    remove(name: string): void;
+    /**
+     * Retrieve a registered agent by name, or `undefined` if not found.
+     */
+    get(name: string): Agent | undefined;
+    /**
+     * Return all registered agents in insertion order.
+     */
+    list(): Agent[];
+    /**
+     * Run a single prompt on the named agent, respecting the pool concurrency
+     * limit.
+     *
+     * @throws {Error} If the agent name is not found.
+     */
+    run(agentName: string, prompt: string, runOptions?: Partial<RunOptions>, streamCallback?: (event: StreamEvent) => void): Promise<AgentRunResult>;
+    /**
+     * Run a prompt on a caller-supplied Agent instance, acquiring only the pool
+     * semaphore — no per-agent lock, no registry lookup.
+     *
+     * Designed for delegation: each delegated call should use a **fresh** Agent
+     * instance (matching `delegate_to_agent`'s "runs in a fresh conversation"
+     * semantics), so the per-agent mutex used by {@link run} would be dead
+     * weight and, worse, a deadlock vector for mutual delegation (A→B while
+     * B→A, each caller holding its own `run`'s agent lock).
+     *
+     * The caller is responsible for constructing the Agent; {@link AgentPool}
+     * does not register or track it.
+     */
+    runEphemeral(agent: Agent, prompt: string, runOptions?: Partial<RunOptions>): Promise<AgentRunResult>;
+    /**
+     * Run prompts on multiple agents in parallel, subject to the concurrency
+     * cap set at construction time.
+     *
+     * Results are returned as a `Map<agentName, AgentRunResult>`. If two tasks
+     * target the same agent name, the map will only contain the last result.
+     * Use unique agent names or run tasks sequentially in that case.
+     *
+     * @param tasks - Array of `{ agent, prompt }` descriptors.
+     */
+    runParallel(tasks: ReadonlyArray<{
+        readonly agent: string;
+        readonly prompt: string;
+    }>): Promise<Map<string, AgentRunResult>>;
+    /**
+     * Run a prompt on the "best available" agent using round-robin selection.
+     *
+     * Agents are selected in insertion order, cycling back to the start. The
+     * concurrency limit is still enforced — if the selected agent is busy the
+     * call will queue via the semaphore.
+     *
+     * @throws {Error} If the pool is empty.
+     */
+    runAny(prompt: string): Promise<AgentRunResult>;
+    /**
+     * Snapshot of how many agents are in each lifecycle state.
+     */
+    getStatus(): PoolStatus;
+    /**
+     * Reset all agents in the pool.
+     *
+     * Clears their conversation histories and returns them to `idle` state.
+     * Does not remove agents from the pool.
+     *
+     * Async for forward compatibility — shutdown may need to perform async
+     * cleanup (e.g. draining in-flight requests) in future versions.
+     */
+    shutdown(): Promise<void>;
+    private requireAgent;
+    /**
+     * Build a failure {@link AgentRunResult} from a caught rejection reason.
+     * This keeps `runParallel` returning a complete map even when individual
+     * agents fail.
+     */
+    private errorResult;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/agent/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/agent/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAMjD,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAMD;;;;;;GAMG;AACH,qBAAa,SAAS;IAkBR,OAAO,CAAC,QAAQ,CAAC,cAAc;IAjB3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,wDAAwD;IACxD,OAAO,CAAC,eAAe,CAAI;IAE3B;;;OAGG;gBAC0B,cAAc,GAAE,MAAU;IAIvD;;;;;OAKG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAMD;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAWvB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ1B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIpC;;OAEG;IACH,IAAI,IAAI,KAAK,EAAE;IAQf;;;;;OAKG;IACG,GAAG,CACP,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,EAChC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAC5C,OAAO,CAAC,cAAc,CAAC;IAyC1B;;;;;;;;;;;;OAYG;IACG,YAAY,CAChB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC,cAAc,CAAC;IAS1B;;;;;;;;;OASG;IAEG,WAAW,CACf,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GACxE,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IA2BvC;;;;;;;;OAQG;IAEG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8BrD;;OAEG;IACH,SAAS,IAAI,UAAU;IAsBvB;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAU/B,OAAO,CAAC,YAAY;IAWpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAUpB"}

package/dist/agent/pool.js

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview Agent pool for managing and scheduling multiple agents.
+ *
+ * {@link AgentPool} is a registry + scheduler that:
+ *  - Holds any number of named {@link Agent} instances
+ *  - Enforces a concurrency cap across parallel runs via {@link Semaphore}
+ *  - Provides `runParallel` for fan-out and `runAny` for round-robin dispatch
+ *  - Reports aggregate pool health via `getStatus()`
+ *
+ * @example
+ * ```ts
+ * const pool = new AgentPool(3)
+ * pool.add(researchAgent)
+ * pool.add(writerAgent)
+ *
+ * const results = await pool.runParallel([
+ *   { agent: 'researcher', prompt: 'Find recent AI papers.' },
+ *   { agent: 'writer',     prompt: 'Draft an intro section.' },
+ * ])
+ * ```
+ */
+import { Semaphore } from '../utils/semaphore.js';
+export { Semaphore } from '../utils/semaphore.js';
+// ---------------------------------------------------------------------------
+// AgentPool
+// ---------------------------------------------------------------------------
+/**
+ * Registry and scheduler for a collection of {@link Agent} instances.
+ *
+ * Thread-safety note: Node.js is single-threaded, so the semaphore approach
+ * is safe — no atomics or mutex primitives are needed. The semaphore gates
+ * concurrent async operations, not CPU threads.
+ */
+export class AgentPool {
+    maxConcurrency;
+    agents = new Map();
+    semaphore;
+    /**
+     * Per-agent mutex (Semaphore(1)) to serialize concurrent runs on the same
+     * Agent instance.  Without this, two tasks assigned to the same agent could
+     * race on mutable instance state (`status`, `messages`, `tokenUsage`).
+     *
+     * @see https://github.com/anthropics/open-multi-agent/issues/72
+     */
+    agentLocks = new Map();
+    /** Cursor used by `runAny` for round-robin dispatch. */
+    roundRobinIndex = 0;
+    /**
+     * @param maxConcurrency - Maximum number of agent runs allowed at the same
+     *                         time across the whole pool. Defaults to `5`.
+     */
+    constructor(maxConcurrency = 5) {
+        this.maxConcurrency = maxConcurrency;
+        this.semaphore = new Semaphore(maxConcurrency);
+    }
+    /**
+     * Pool semaphore slots not currently held (`maxConcurrency - active`).
+     * Used to avoid deadlocks when a nested `run()` would wait forever for a slot
+     * held by the parent run. Best-effort only if multiple nested runs start in
+     * parallel after the same synchronous check.
+     */
+    get availableRunSlots() {
+        return this.maxConcurrency - this.semaphore.active;
+    }
+    // -------------------------------------------------------------------------
+    // Registry operations
+    // -------------------------------------------------------------------------
+    /**
+     * Register an agent with the pool.
+     *
+     * @throws {Error} If an agent with the same name is already registered.
+     */
+    add(agent) {
+        if (this.agents.has(agent.name)) {
+            throw new Error(`AgentPool: agent '${agent.name}' is already registered. ` +
+                `Call remove('${agent.name}') before re-adding.`);
+        }
+        this.agents.set(agent.name, agent);
+        this.agentLocks.set(agent.name, new Semaphore(1));
+    }
+    /**
+     * Unregister an agent by name.
+     *
+     * @throws {Error} If the agent is not found.
+     */
+    remove(name) {
+        if (!this.agents.has(name)) {
+            throw new Error(`AgentPool: agent '${name}' is not registered.`);
+        }
+        this.agents.delete(name);
+        this.agentLocks.delete(name);
+    }
+    /**
+     * Retrieve a registered agent by name, or `undefined` if not found.
+     */
+    get(name) {
+        return this.agents.get(name);
+    }
+    /**
+     * Return all registered agents in insertion order.
+     */
+    list() {
+        return Array.from(this.agents.values());
+    }
+    // -------------------------------------------------------------------------
+    // Execution API
+    // -------------------------------------------------------------------------
+    /**
+     * Run a single prompt on the named agent, respecting the pool concurrency
+     * limit.
+     *
+     * @throws {Error} If the agent name is not found.
+     */
+    async run(agentName, prompt, runOptions, streamCallback) {
+        const agent = this.requireAgent(agentName);
+        const agentLock = this.agentLocks.get(agentName);
+        // Acquire per-agent lock first so the second call for the same agent waits
+        // here without consuming a pool slot.  Then acquire the pool semaphore.
+        await agentLock.acquire();
+        try {
+            await this.semaphore.acquire();
+            try {
+                if (streamCallback) {
+                    let result = null;
+                    for await (const event of agent.stream(prompt, runOptions)) {
+                        try {
+                            streamCallback(event);
+                        }
+                        catch {
+                            // Streaming callback must not affect execution; mirrors the
+                            // observability contract of `emitTrace`. A throwing callback
+                            // here would otherwise be caught by `executeWithRetry` and
+                            // burn another LLM call on every retry until exhausted.
+                        }
+                        if (event.type === 'done')
+                            result = event.data;
+                        if (event.type === 'error')
+                            throw event.data;
+                    }
+                    return result ?? {
+                        success: false,
+                        output: '',
+                        messages: [],
+                        tokenUsage: { input_tokens: 0, output_tokens: 0 },
+                        toolCalls: [],
+                    };
+                }
+                return await agent.run(prompt, runOptions);
+            }
+            finally {
+                this.semaphore.release();
+            }
+        }
+        finally {
+            agentLock.release();
+        }
+    }
+    /**
+     * Run a prompt on a caller-supplied Agent instance, acquiring only the pool
+     * semaphore — no per-agent lock, no registry lookup.
+     *
+     * Designed for delegation: each delegated call should use a **fresh** Agent
+     * instance (matching `delegate_to_agent`'s "runs in a fresh conversation"
+     * semantics), so the per-agent mutex used by {@link run} would be dead
+     * weight and, worse, a deadlock vector for mutual delegation (A→B while
+     * B→A, each caller holding its own `run`'s agent lock).
+     *
+     * The caller is responsible for constructing the Agent; {@link AgentPool}
+     * does not register or track it.
+     */
+    async runEphemeral(agent, prompt, runOptions) {
+        await this.semaphore.acquire();
+        try {
+            return await agent.run(prompt, runOptions);
+        }
+        finally {
+            this.semaphore.release();
+        }
+    }
+    /**
+     * Run prompts on multiple agents in parallel, subject to the concurrency
+     * cap set at construction time.
+     *
+     * Results are returned as a `Map<agentName, AgentRunResult>`. If two tasks
+     * target the same agent name, the map will only contain the last result.
+     * Use unique agent names or run tasks sequentially in that case.
+     *
+     * @param tasks - Array of `{ agent, prompt }` descriptors.
+     */
+    // TODO(#18): accept RunOptions per task to forward trace context
+    async runParallel(tasks) {
+        const resultMap = new Map();
+        const settledResults = await Promise.allSettled(tasks.map(async (task) => {
+            const result = await this.run(task.agent, task.prompt);
+            return { name: task.agent, result };
+        }));
+        for (const settled of settledResults) {
+            if (settled.status === 'fulfilled') {
+                resultMap.set(settled.value.name, settled.value.result);
+            }
+            else {
+                // A rejected run is surfaced as an error AgentRunResult so the caller
+                // sees it in the map rather than needing to catch Promise.allSettled.
+                // We cannot know the agent name from the rejection alone — find it via
+                // the original task list index.
+                const idx = settledResults.indexOf(settled);
+                const agentName = tasks[idx]?.agent ?? 'unknown';
+                resultMap.set(agentName, this.errorResult(settled.reason));
+            }
+        }
+        return resultMap;
+    }
+    /**
+     * Run a prompt on the "best available" agent using round-robin selection.
+     *
+     * Agents are selected in insertion order, cycling back to the start. The
+     * concurrency limit is still enforced — if the selected agent is busy the
+     * call will queue via the semaphore.
+     *
+     * @throws {Error} If the pool is empty.
+     */
+    // TODO(#18): accept RunOptions to forward trace context
+    async runAny(prompt) {
+        const allAgents = this.list();
+        if (allAgents.length === 0) {
+            throw new Error('AgentPool: cannot call runAny on an empty pool.');
+        }
+        // Wrap the index to keep it in bounds even if agents were removed.
+        this.roundRobinIndex = this.roundRobinIndex % allAgents.length;
+        const agent = allAgents[this.roundRobinIndex];
+        this.roundRobinIndex = (this.roundRobinIndex + 1) % allAgents.length;
+        const agentLock = this.agentLocks.get(agent.name);
+        await agentLock.acquire();
+        try {
+            await this.semaphore.acquire();
+            try {
+                return await agent.run(prompt);
+            }
+            finally {
+                this.semaphore.release();
+            }
+        }
+        finally {
+            agentLock.release();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Observability
+    // -------------------------------------------------------------------------
+    /**
+     * Snapshot of how many agents are in each lifecycle state.
+     */
+    getStatus() {
+        let idle = 0;
+        let running = 0;
+        let completed = 0;
+        let error = 0;
+        for (const agent of this.agents.values()) {
+            switch (agent.getState().status) {
+                case 'idle':
+                    idle++;
+                    break;
+                case 'running':
+                    running++;
+                    break;
+                case 'completed':
+                    completed++;
+                    break;
+                case 'error':
+                    error++;
+                    break;
+            }
+        }
+        return { total: this.agents.size, idle, running, completed, error };
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Reset all agents in the pool.
+     *
+     * Clears their conversation histories and returns them to `idle` state.
+     * Does not remove agents from the pool.
+     *
+     * Async for forward compatibility — shutdown may need to perform async
+     * cleanup (e.g. draining in-flight requests) in future versions.
+     */
+    async shutdown() {
+        for (const agent of this.agents.values()) {
+            agent.reset();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    requireAgent(name) {
+        const agent = this.agents.get(name);
+        if (agent === undefined) {
+            throw new Error(`AgentPool: agent '${name}' is not registered. ` +
+                `Registered agents: [${Array.from(this.agents.keys()).join(', ')}]`);
+        }
+        return agent;
+    }
+    /**
+     * Build a failure {@link AgentRunResult} from a caught rejection reason.
+     * This keeps `runParallel` returning a complete map even when individual
+     * agents fail.
+     */
+    errorResult(reason) {
+        const message = reason instanceof Error ? reason.message : String(reason);
+        return {
+            success: false,
+            output: message,
+            messages: [],
+            tokenUsage: { input_tokens: 0, output_tokens: 0 },
+            toolCalls: [],
+        };
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/agent/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/agent/pool.ts"],"names":[],"mappings":"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"}