@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

package/src/agent/loop-detector.ts

@@ -1,137 +0,0 @@
-/**
- * @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.
- */
-
-import type { LoopDetectionConfig, LoopDetectionInfo } from '../types.js'
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Recursively sort object keys so that `{b:1, a:2}` and `{a:2, b:1}` produce
- * the same JSON string.
- */
-function sortKeys(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value
-  if (Array.isArray(value)) return value.map(sortKeys)
-  const sorted: Record<string, unknown> = {}
-  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
-    sorted[key] = sortKeys((value as Record<string, unknown>)[key])
-  }
-  return sorted
-}
-
-// ---------------------------------------------------------------------------
-// LoopDetector
-// ---------------------------------------------------------------------------
-
-export class LoopDetector {
-  private readonly maxRepeats: number
-  private readonly windowSize: number
-
-  private readonly toolSignatures: string[] = []
-  private readonly textOutputs: string[] = []
-
-  constructor(config: LoopDetectionConfig = {}) {
-    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: ReadonlyArray<{ name: string; input: Record<string, unknown> }>,
-  ): LoopDetectionInfo | null {
-    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: string): LoopDetectionInfo | null {
-    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.
-   */
-  private computeToolSignature(
-    blocks: ReadonlyArray<{ name: string; input: Record<string, unknown> }>,
-  ): string {
-    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`. */
-  private push(buffer: string[], entry: string): void {
-    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.
-   */
-  private consecutiveRepeats(buffer: string[]): number {
-    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
-  }
-}

package/src/agent/pool.ts

@@ -1,285 +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 { RunOptions } from './runner.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,
-    runOptions?: Partial<RunOptions>,
-  ): Promise<AgentRunResult> {
-    const agent = this.requireAgent(agentName)
-
-    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: 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.
-   */
-  // TODO(#18): accept RunOptions to forward trace context
-  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: [],
-    }
-  }
-}