@jackchen_me/open-multi-agent 0.2.0 → 1.0.1

package/src/agent/pool.ts

@@ -1,278 +0,0 @@
-/**
- * @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 } from '../types.js'
-import type { Agent } from './agent.js'
-import { Semaphore } from '../utils/semaphore.js'
-
-export { Semaphore } from '../utils/semaphore.js'
-
-// ---------------------------------------------------------------------------
-// Pool status snapshot
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// 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 {
-  private readonly agents: Map<string, Agent> = new Map()
-  private readonly semaphore: Semaphore
-  /** Cursor used by `runAny` for round-robin dispatch. */
-  private roundRobinIndex = 0
-
-  /**
-   * @param maxConcurrency - Maximum number of agent runs allowed at the same
-   *                         time across the whole pool. Defaults to `5`.
-   */
-  constructor(private readonly maxConcurrency: number = 5) {
-    this.semaphore = new Semaphore(maxConcurrency)
-  }
-
-  // -------------------------------------------------------------------------
-  // Registry operations
-  // -------------------------------------------------------------------------
-
-  /**
-   * Register an agent with the pool.
-   *
-   * @throws {Error} If an agent with the same name is already registered.
-   */
-  add(agent: Agent): void {
-    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)
-  }
-
-  /**
-   * Unregister an agent by name.
-   *
-   * @throws {Error} If the agent is not found.
-   */
-  remove(name: string): void {
-    if (!this.agents.has(name)) {
-      throw new Error(`AgentPool: agent '${name}' is not registered.`)
-    }
-    this.agents.delete(name)
-  }
-
-  /**
-   * Retrieve a registered agent by name, or `undefined` if not found.
-   */
-  get(name: string): Agent | undefined {
-    return this.agents.get(name)
-  }
-
-  /**
-   * Return all registered agents in insertion order.
-   */
-  list(): Agent[] {
-    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: string, prompt: string): Promise<AgentRunResult> {
-    const agent = this.requireAgent(agentName)
-
-    await this.semaphore.acquire()
-    try {
-      return await agent.run(prompt)
-    } 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.
-   */
-  async runParallel(
-    tasks: ReadonlyArray<{ readonly agent: string; readonly prompt: string }>,
-  ): Promise<Map<string, AgentRunResult>> {
-    const resultMap = new Map<string, AgentRunResult>()
-
-    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.
-   */
-  async runAny(prompt: string): Promise<AgentRunResult> {
-    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
-
-    await this.semaphore.acquire()
-    try {
-      return await agent.run(prompt)
-    } finally {
-      this.semaphore.release()
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // Observability
-  // -------------------------------------------------------------------------
-
-  /**
-   * Snapshot of how many agents are in each lifecycle state.
-   */
-  getStatus(): PoolStatus {
-    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(): Promise<void> {
-    for (const agent of this.agents.values()) {
-      agent.reset()
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
-  private requireAgent(name: string): Agent {
-    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.
-   */
-  private errorResult(reason: unknown): AgentRunResult {
-    const message = reason instanceof Error ? reason.message : String(reason)
-    return {
-      success: false,
-      output: message,
-      messages: [],
-      tokenUsage: { input_tokens: 0, output_tokens: 0 },
-      toolCalls: [],
-    }
-  }
-}

package/src/agent/runner.ts

@@ -1,413 +0,0 @@
-/**
- * @fileoverview Core conversation loop engine for open-multi-agent.
- *
- * {@link AgentRunner} is the heart of the framework. It handles:
- *  - Sending messages to the LLM adapter
- *  - Extracting tool-use blocks from the response
- *  - Executing tool calls in parallel via {@link ToolExecutor}
- *  - Appending tool results and looping back until `end_turn`
- *  - Accumulating token usage and timing data across all turns
- *
- * The loop follows a standard agentic conversation pattern:
- * one outer `while (true)` that breaks on `end_turn` or maxTurns exhaustion.
- */
-
-import type {
-  LLMMessage,
-  ContentBlock,
-  TextBlock,
-  ToolUseBlock,
-  ToolResultBlock,
-  ToolCallRecord,
-  TokenUsage,
-  StreamEvent,
-  ToolResult,
-  ToolUseContext,
-  LLMAdapter,
-  LLMChatOptions,
-} from '../types.js'
-import type { ToolRegistry } from '../tool/framework.js'
-import type { ToolExecutor } from '../tool/executor.js'
-
-// ---------------------------------------------------------------------------
-// Public interfaces
-// ---------------------------------------------------------------------------
-
-/**
- * Static configuration for an {@link AgentRunner} instance.
- * These values are constant across every `run` / `stream` call.
- */
-export interface RunnerOptions {
-  /** LLM model identifier, e.g. `'claude-opus-4-6'`. */
-  readonly model: string
-  /** Optional system prompt prepended to every conversation. */
-  readonly systemPrompt?: string
-  /**
-   * Maximum number of tool-call round-trips before the runner stops.
-   * Prevents unbounded loops. Defaults to `10`.
-   */
-  readonly maxTurns?: number
-  /** Maximum output tokens per LLM response. */
-  readonly maxTokens?: number
-  /** Sampling temperature passed to the adapter. */
-  readonly temperature?: number
-  /** AbortSignal that cancels any in-flight adapter call and stops the loop. */
-  readonly abortSignal?: AbortSignal
-  /**
-   * Whitelist of tool names this runner is allowed to use.
-   * When provided, only tools whose name appears in this list are sent to the
-   * LLM. When omitted, all registered tools are available.
-   */
-  readonly allowedTools?: readonly string[]
-  /** Display name of the agent driving this runner (used in tool context). */
-  readonly agentName?: string
-  /** Short role description of the agent (used in tool context). */
-  readonly agentRole?: string
-}
-
-/**
- * Per-call callbacks for observing tool execution in real time.
- * All callbacks are optional; unused ones are simply skipped.
- */
-export interface RunOptions {
-  /** Fired just before each tool is dispatched. */
-  readonly onToolCall?: (name: string, input: Record<string, unknown>) => void
-  /** Fired after each tool result is received. */
-  readonly onToolResult?: (name: string, result: ToolResult) => void
-  /** Fired after each complete {@link LLMMessage} is appended. */
-  readonly onMessage?: (message: LLMMessage) => void
-}
-
-/** The aggregated result returned when a full run completes. */
-export interface RunResult {
-  /** All messages accumulated during this run (assistant + tool results). */
-  readonly messages: LLMMessage[]
-  /** The final text output from the last assistant turn. */
-  readonly output: string
-  /** All tool calls made during this run, in execution order. */
-  readonly toolCalls: ToolCallRecord[]
-  /** Aggregated token counts across every LLM call in this run. */
-  readonly tokenUsage: TokenUsage
-  /** Total number of LLM turns (including tool-call follow-ups). */
-  readonly turns: number
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Extract every TextBlock from a content array and join them. */
-function extractText(content: readonly ContentBlock[]): string {
-  return content
-    .filter((b): b is TextBlock => b.type === 'text')
-    .map(b => b.text)
-    .join('')
-}
-
-/** Extract every ToolUseBlock from a content array. */
-function extractToolUseBlocks(content: readonly ContentBlock[]): ToolUseBlock[] {
-  return content.filter((b): b is ToolUseBlock => b.type === 'tool_use')
-}
-
-/** Add two {@link TokenUsage} values together, returning a new object. */
-function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
-  return {
-    input_tokens: a.input_tokens + b.input_tokens,
-    output_tokens: a.output_tokens + b.output_tokens,
-  }
-}
-
-const ZERO_USAGE: TokenUsage = { input_tokens: 0, output_tokens: 0 }
-
-// ---------------------------------------------------------------------------
-// AgentRunner
-// ---------------------------------------------------------------------------
-
-/**
- * Drives a full agentic conversation: LLM calls, tool execution, and looping.
- *
- * @example
- * ```ts
- * const runner = new AgentRunner(adapter, registry, executor, {
- *   model: 'claude-opus-4-6',
- *   maxTurns: 10,
- * })
- * const result = await runner.run(messages)
- * console.log(result.output)
- * ```
- */
-export class AgentRunner {
-  private readonly maxTurns: number
-
-  constructor(
-    private readonly adapter: LLMAdapter,
-    private readonly toolRegistry: ToolRegistry,
-    private readonly toolExecutor: ToolExecutor,
-    private readonly options: RunnerOptions,
-  ) {
-    this.maxTurns = options.maxTurns ?? 10
-  }
-
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
-
-  /**
-   * Run a complete conversation starting from `messages`.
-   *
-   * The call may internally make multiple LLM requests (one per tool-call
-   * round-trip). It returns only when:
-   *  - The LLM emits `end_turn` with no tool-use blocks, or
-   *  - `maxTurns` is exceeded, or
-   *  - The abort signal is triggered.
-   */
-  async run(
-    messages: LLMMessage[],
-    options: RunOptions = {},
-  ): Promise<RunResult> {
-    // Collect everything yielded by the internal streaming loop.
-    const accumulated: {
-      messages: LLMMessage[]
-      output: string
-      toolCalls: ToolCallRecord[]
-      tokenUsage: TokenUsage
-      turns: number
-    } = {
-      messages: [],
-      output: '',
-      toolCalls: [],
-      tokenUsage: ZERO_USAGE,
-      turns: 0,
-    }
-
-    for await (const event of this.stream(messages, options)) {
-      if (event.type === 'done') {
-        const result = event.data as RunResult
-        accumulated.messages = result.messages
-        accumulated.output = result.output
-        accumulated.toolCalls = result.toolCalls
-        accumulated.tokenUsage = result.tokenUsage
-        accumulated.turns = result.turns
-      }
-    }
-
-    return accumulated
-  }
-
-  /**
-   * Run the conversation and yield {@link StreamEvent}s incrementally.
-   *
-   * Callers receive:
-   *  - `{ type: 'text', data: string }` for each text delta
-   *  - `{ type: 'tool_use', data: ToolUseBlock }` when the model requests a tool
-   *  - `{ type: 'tool_result', data: ToolResultBlock }` after each execution
-   *  - `{ type: 'done', data: RunResult }` at the very end
-   *  - `{ type: 'error', data: Error }` on unrecoverable failure
-   */
-  async *stream(
-    initialMessages: LLMMessage[],
-    options: RunOptions = {},
-  ): AsyncGenerator<StreamEvent> {
-    // Working copy of the conversation — mutated as turns progress.
-    const conversationMessages: LLMMessage[] = [...initialMessages]
-
-    // Accumulated state across all turns.
-    let totalUsage: TokenUsage = ZERO_USAGE
-    const allToolCalls: ToolCallRecord[] = []
-    let finalOutput = ''
-    let turns = 0
-
-    // Build the stable LLM options once; model / tokens / temp don't change.
-    // toToolDefs() returns LLMToolDef[] (inputSchema, camelCase) — matches
-    // LLMChatOptions.tools from types.ts directly.
-    const allDefs = this.toolRegistry.toToolDefs()
-    const toolDefs = this.options.allowedTools
-      ? allDefs.filter(d => this.options.allowedTools!.includes(d.name))
-      : allDefs
-
-    const baseChatOptions: LLMChatOptions = {
-      model: this.options.model,
-      tools: toolDefs.length > 0 ? toolDefs : undefined,
-      maxTokens: this.options.maxTokens,
-      temperature: this.options.temperature,
-      systemPrompt: this.options.systemPrompt,
-      abortSignal: this.options.abortSignal,
-    }
-
-    try {
-      // -----------------------------------------------------------------
-      // Main agentic loop — `while (true)` until end_turn or maxTurns
-      // -----------------------------------------------------------------
-      while (true) {
-        // Respect abort before each LLM call.
-        if (this.options.abortSignal?.aborted) {
-          break
-        }
-
-        // Guard against unbounded loops.
-        if (turns >= this.maxTurns) {
-          break
-        }
-
-        turns++
-
-        // ------------------------------------------------------------------
-        // Step 1: Call the LLM and collect the full response for this turn.
-        // ------------------------------------------------------------------
-        const response = await this.adapter.chat(conversationMessages, baseChatOptions)
-
-        totalUsage = addTokenUsage(totalUsage, response.usage)
-
-        // ------------------------------------------------------------------
-        // Step 2: Build the assistant message from the response content.
-        // ------------------------------------------------------------------
-        const assistantMessage: LLMMessage = {
-          role: 'assistant',
-          content: response.content,
-        }
-
-        conversationMessages.push(assistantMessage)
-        options.onMessage?.(assistantMessage)
-
-        // Yield text deltas so streaming callers can display them promptly.
-        const turnText = extractText(response.content)
-        if (turnText.length > 0) {
-          yield { type: 'text', data: turnText } satisfies StreamEvent
-        }
-
-        // Announce each tool-use block the model requested.
-        const toolUseBlocks = extractToolUseBlocks(response.content)
-        for (const block of toolUseBlocks) {
-          yield { type: 'tool_use', data: block } satisfies StreamEvent
-        }
-
-        // ------------------------------------------------------------------
-        // Step 3: Decide whether to continue looping.
-        // ------------------------------------------------------------------
-        if (toolUseBlocks.length === 0) {
-          // No tools requested — this is the terminal assistant turn.
-          finalOutput = turnText
-          break
-        }
-
-        // ------------------------------------------------------------------
-        // Step 4: Execute all tool calls in PARALLEL.
-        //
-        // Parallel execution is critical for multi-tool responses where the
-        // tools are independent (e.g. reading several files at once).
-        // ------------------------------------------------------------------
-        const toolContext: ToolUseContext = this.buildToolContext()
-
-        const executionPromises = toolUseBlocks.map(async (block): Promise<{
-          resultBlock: ToolResultBlock
-          record: ToolCallRecord
-        }> => {
-          options.onToolCall?.(block.name, block.input)
-
-          const startTime = Date.now()
-          let result: ToolResult
-
-          try {
-            result = await this.toolExecutor.execute(
-              block.name,
-              block.input,
-              toolContext,
-            )
-          } catch (err) {
-            // Tool executor errors become error results — the loop continues.
-            const message = err instanceof Error ? err.message : String(err)
-            result = { data: message, isError: true }
-          }
-
-          const duration = Date.now() - startTime
-
-          options.onToolResult?.(block.name, result)
-
-          const record: ToolCallRecord = {
-            toolName: block.name,
-            input: block.input,
-            output: result.data,
-            duration,
-          }
-
-          const resultBlock: ToolResultBlock = {
-            type: 'tool_result',
-            tool_use_id: block.id,
-            content: result.data,
-            is_error: result.isError,
-          }
-
-          return { resultBlock, record }
-        })
-
-        // Wait for every tool in this turn to finish.
-        const executions = await Promise.all(executionPromises)
-
-        // ------------------------------------------------------------------
-        // Step 5: Accumulate results and build the user message that carries
-        //         them back to the LLM in the next turn.
-        // ------------------------------------------------------------------
-        const toolResultBlocks: ContentBlock[] = executions.map(e => e.resultBlock)
-
-        for (const { record, resultBlock } of executions) {
-          allToolCalls.push(record)
-          yield { type: 'tool_result', data: resultBlock } satisfies StreamEvent
-        }
-
-        const toolResultMessage: LLMMessage = {
-          role: 'user',
-          content: toolResultBlocks,
-        }
-
-        conversationMessages.push(toolResultMessage)
-        options.onMessage?.(toolResultMessage)
-
-        // Loop back to Step 1 — send updated conversation to the LLM.
-      }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err))
-      yield { type: 'error', data: error } satisfies StreamEvent
-      return
-    }
-
-    // If the loop exited due to maxTurns, use whatever text was last emitted.
-    if (finalOutput === '' && conversationMessages.length > 0) {
-      const lastAssistant = [...conversationMessages]
-        .reverse()
-        .find(m => m.role === 'assistant')
-      if (lastAssistant !== undefined) {
-        finalOutput = extractText(lastAssistant.content)
-      }
-    }
-
-    const runResult: RunResult = {
-      // Return only the messages added during this run (not the initial seed).
-      messages: conversationMessages.slice(initialMessages.length),
-      output: finalOutput,
-      toolCalls: allToolCalls,
-      tokenUsage: totalUsage,
-      turns,
-    }
-
-    yield { type: 'done', data: runResult } satisfies StreamEvent
-  }
-
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
-  /**
-   * Build the {@link ToolUseContext} passed to every tool execution.
-   * Identifies this runner as the invoking agent.
-   */
-  private buildToolContext(): ToolUseContext {
-    return {
-      agent: {
-        name: this.options.agentName ?? 'runner',
-        role: this.options.agentRole ?? 'assistant',
-        model: this.options.model,
-      },
-      abortSignal: this.options.abortSignal,
-    }
-  }
-}