@jackchen_me/open-multi-agent 0.2.0 → 1.0.0

package/examples/12-grok.ts

@@ -0,0 +1,154 @@
+/**
+ * Example 12 — Multi-Agent Team Collaboration with Grok (xAI)
+ *
+ * Three specialized agents (architect, developer, reviewer) collaborate via `runTeam()`
+ * to build a minimal Express.js REST API. Every agent uses Grok's coding-optimized model.
+ *
+ * Run:
+ *   npx tsx examples/12-grok.ts
+ *
+ * Prerequisites:
+ *   XAI_API_KEY environment variable must be set.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig, OrchestratorEvent } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Agent definitions (all using grok-code-fast-1)
+// ---------------------------------------------------------------------------
+const architect: AgentConfig = {
+  name: 'architect',
+  model: 'grok-code-fast-1',
+  provider: 'grok',
+  systemPrompt: `You are a software architect with deep experience in Node.js and REST API design.
+Your job is to design clear, production-quality API contracts and file/directory structures.
+Output concise plans in markdown — no unnecessary prose.`,
+  tools: ['bash', 'file_write'],
+  maxTurns: 5,
+  temperature: 0.2,
+}
+
+const developer: AgentConfig = {
+  name: 'developer',
+  model: 'grok-code-fast-1',
+  provider: 'grok',
+  systemPrompt: `You are a TypeScript/Node.js developer. You implement what the architect specifies.
+Write clean, runnable code with proper error handling. Use the tools to write files and run tests.`,
+  tools: ['bash', 'file_read', 'file_write', 'file_edit'],
+  maxTurns: 12,
+  temperature: 0.1,
+}
+
+const reviewer: AgentConfig = {
+  name: 'reviewer',
+  model: 'grok-code-fast-1',
+  provider: 'grok',
+  systemPrompt: `You are a senior code reviewer. Review code for correctness, security, and clarity.
+Provide a structured review with: LGTM items, suggestions, and any blocking issues.
+Read files using the tools before reviewing.`,
+  tools: ['bash', 'file_read', 'grep'],
+  maxTurns: 5,
+  temperature: 0.3,
+}
+
+// ---------------------------------------------------------------------------
+// Progress tracking
+// ---------------------------------------------------------------------------
+const startTimes = new Map<string, number>()
+
+function handleProgress(event: OrchestratorEvent): void {
+  const ts = new Date().toISOString().slice(11, 23) // HH:MM:SS.mmm
+  switch (event.type) {
+    case 'agent_start':
+      startTimes.set(event.agent ?? '', Date.now())
+      console.log(`[${ts}] AGENT START → ${event.agent}`)
+      break
+    case 'agent_complete': {
+      const elapsed = Date.now() - (startTimes.get(event.agent ?? '') ?? Date.now())
+      console.log(`[${ts}] AGENT DONE ← ${event.agent} (${elapsed}ms)`)
+      break
+    }
+    case 'task_start':
+      console.log(`[${ts}] TASK START ↓ ${event.task}`)
+      break
+    case 'task_complete':
+      console.log(`[${ts}] TASK DONE ↑ ${event.task}`)
+      break
+    case 'message':
+      console.log(`[${ts}] MESSAGE • ${event.agent} → (team)`)
+      break
+    case 'error':
+      console.error(`[${ts}] ERROR ✗ agent=${event.agent} task=${event.task}`)
+      if (event.data instanceof Error) console.error(` ${event.data.message}`)
+      break
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrate
+// ---------------------------------------------------------------------------
+const orchestrator = new OpenMultiAgent({
+  defaultModel: 'grok-code-fast-1',
+  defaultProvider: 'grok',
+  maxConcurrency: 1, // sequential for readable output
+  onProgress: handleProgress,
+})
+
+const team = orchestrator.createTeam('api-team', {
+  name: 'api-team',
+  agents: [architect, developer, reviewer],
+  sharedMemory: true,
+  maxConcurrency: 1,
+})
+
+console.log(`Team "${team.name}" created with agents: ${team.getAgents().map(a => a.name).join(', ')}`)
+console.log('\nStarting team run...\n')
+console.log('='.repeat(60))
+
+const goal = `Create a minimal Express.js REST API in /tmp/express-api/ with:
+- GET /health → { status: "ok" }
+- GET /users → returns a hardcoded array of 2 user objects
+- POST /users → accepts { name, email } body, logs it, returns 201
+- Proper error handling middleware
+- The server should listen on port 3001
+- Include a package.json with the required dependencies`
+
+const result = await orchestrator.runTeam(team, goal)
+
+console.log('\n' + '='.repeat(60))
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+console.log('\nTeam run complete.')
+console.log(`Success: ${result.success}`)
+console.log(`Total tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
+
+console.log('\nPer-agent results:')
+for (const [agentName, agentResult] of result.agentResults) {
+  const status = agentResult.success ? 'OK' : 'FAILED'
+  const tools = agentResult.toolCalls.length
+  console.log(` ${agentName.padEnd(12)} [${status}] tool_calls=${tools}`)
+  if (!agentResult.success) {
+    console.log(` Error: ${agentResult.output.slice(0, 120)}`)
+  }
+}
+
+// Sample outputs
+const developerResult = result.agentResults.get('developer')
+if (developerResult?.success) {
+  console.log('\nDeveloper output (last 600 chars):')
+  console.log('─'.repeat(60))
+  const out = developerResult.output
+  console.log(out.length > 600 ? '...' + out.slice(-600) : out)
+  console.log('─'.repeat(60))
+}
+
+const reviewerResult = result.agentResults.get('reviewer')
+if (reviewerResult?.success) {
+  console.log('\nReviewer output:')
+  console.log('─'.repeat(60))
+  console.log(reviewerResult.output)
+  console.log('─'.repeat(60))
+}

package/examples/13-gemini.ts

@@ -0,0 +1,48 @@
+/**
+ * Quick smoke test for the Gemini adapter.
+ *
+ * Run:
+ *   npx tsx examples/13-gemini.ts
+ *
+ * If GEMINI_API_KEY is not set, the adapter will not work.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { OrchestratorEvent } from '../src/types.js'
+
+const orchestrator = new OpenMultiAgent({
+  defaultModel: 'gemini-2.5-flash',
+  defaultProvider: 'gemini',
+  onProgress: (event: OrchestratorEvent) => {
+    if (event.type === 'agent_start') {
+      console.log(`[start]    agent=${event.agent}`)
+    } else if (event.type === 'agent_complete') {
+      console.log(`[complete] agent=${event.agent}`)
+    }
+  },
+})
+
+console.log('Testing Gemini adapter with gemini-2.5-flash...\n')
+
+const result = await orchestrator.runAgent(
+  {
+    name: 'assistant',
+    model: 'gemini-2.5-flash',
+    provider: 'gemini',
+    systemPrompt: 'You are a helpful assistant. Keep answers brief.',
+    maxTurns: 1,
+    maxTokens: 256,
+  },
+  'What is 2 + 2? Reply in one sentence.',
+)
+
+if (result.success) {
+  console.log('\nAgent output:')
+  console.log('─'.repeat(60))
+  console.log(result.output)
+  console.log('─'.repeat(60))
+  console.log(`\nTokens: input=${result.tokenUsage.input_tokens}, output=${result.tokenUsage.output_tokens}`)
+} else {
+  console.error('Agent failed:', result.output)
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackchen_me/open-multi-agent",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Production-grade multi-agent orchestration framework. Model-agnostic, supports team collaboration, task scheduling, and inter-agent communication.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,8 +41,18 @@
     "openai": "^4.73.0",
     "zod": "^3.23.0"
   },
+  "peerDependencies": {
+    "@google/genai": "^1.48.0"
+  },
+  "peerDependenciesMeta": {
+    "@google/genai": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@google/genai": "^1.48.0",
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "tsx": "^4.21.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/src/agent/agent.ts

@@ -27,11 +27,13 @@ import type {
   AgentConfig,
   AgentState,
   AgentRunResult,
+  BeforeRunHookContext,
   LLMMessage,
   StreamEvent,
   TokenUsage,
   ToolUseContext,
 } from '../types.js'
+import { emitTrace, generateRunId } from '../utils/trace.js'
 import type { ToolDefinition as FrameworkToolDefinition, ToolRegistry } from '../tool/framework.js'
 import type { ToolExecutor } from '../tool/executor.js'
 import { createAdapter } from '../llm/adapter.js'
@@ -48,6 +50,19 @@ import {
 
 const ZERO_USAGE: TokenUsage = { input_tokens: 0, output_tokens: 0 }
 
+/**
+ * Combine two {@link AbortSignal}s so that aborting either one cancels the
+ * returned signal.  Works on Node 18+ (no `AbortSignal.any` required).
+ */
+function mergeAbortSignals(a: AbortSignal, b: AbortSignal): AbortSignal {
+  const controller = new AbortController()
+  if (a.aborted || b.aborted) { controller.abort(); return controller.signal }
+  const abort = () => controller.abort()
+  a.addEventListener('abort', abort, { once: true })
+  b.addEventListener('abort', abort, { once: true })
+  return controller.signal
+}
+
 function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
   return {
     input_tokens: a.input_tokens + b.input_tokens,
@@ -134,6 +149,7 @@ export class Agent {
       allowedTools: this.config.tools,
       agentName: this.name,
       agentRole: this.config.systemPrompt?.slice(0, 50) ?? 'assistant',
+      loopDetection: this.config.loopDetection,
     }
 
     this.runner = new AgentRunner(
@@ -158,12 +174,12 @@ export class Agent {
    *
    * Use this for one-shot queries where past context is irrelevant.
    */
-  async run(prompt: string): Promise<AgentRunResult> {
+  async run(prompt: string, runOptions?: Partial<RunOptions>): Promise<AgentRunResult> {
     const messages: LLMMessage[] = [
       { role: 'user', content: [{ type: 'text', text: prompt }] },
     ]
 
-    return this.executeRun(messages)
+    return this.executeRun(messages, runOptions)
   }
 
   /**
@@ -174,6 +190,7 @@ export class Agent {
    *
    * Use this for multi-turn interactions.
    */
+  // TODO(#18): accept optional RunOptions to forward trace context
   async prompt(message: string): Promise<AgentRunResult> {
     const userMessage: LLMMessage = {
       role: 'user',
@@ -197,6 +214,7 @@ export class Agent {
    *
    * Like {@link run}, this does not use or update the persistent history.
    */
+  // TODO(#18): accept optional RunOptions to forward trace context
   async *stream(prompt: string): AsyncGenerator<StreamEvent> {
     const messages: LLMMessage[] = [
       { role: 'user', content: [{ type: 'text', text: prompt }] },
@@ -266,15 +284,45 @@ export class Agent {
    * Shared execution path used by both `run` and `prompt`.
    * Handles state transitions and error wrapping.
    */
-  private async executeRun(messages: LLMMessage[]): Promise<AgentRunResult> {
+  private async executeRun(
+    messages: LLMMessage[],
+    callerOptions?: Partial<RunOptions>,
+  ): Promise<AgentRunResult> {
     this.transitionTo('running')
 
+    const agentStartMs = Date.now()
+
     try {
+      // --- beforeRun hook ---
+      if (this.config.beforeRun) {
+        const hookCtx = this.buildBeforeRunHookContext(messages)
+        const modified = await this.config.beforeRun(hookCtx)
+        this.applyHookContext(messages, modified, hookCtx.prompt)
+      }
+
       const runner = await this.getRunner()
+      const internalOnMessage = (msg: LLMMessage) => {
+        this.state.messages.push(msg)
+        callerOptions?.onMessage?.(msg)
+      }
+      // Auto-generate runId when onTrace is provided but runId is missing
+      const needsRunId = callerOptions?.onTrace && !callerOptions.runId
+      // Create a fresh timeout signal per run (not per runner) so that
+      // each run() / prompt() call gets its own timeout window.
+      const timeoutSignal = this.config.timeoutMs !== undefined && this.config.timeoutMs > 0
+        ? AbortSignal.timeout(this.config.timeoutMs)
+        : undefined
+      // Merge caller-provided abortSignal with the timeout signal so that
+      // either cancellation source is respected.
+      const callerAbort = callerOptions?.abortSignal
+      const effectiveAbort = timeoutSignal && callerAbort
+        ? mergeAbortSignals(timeoutSignal, callerAbort)
+        : timeoutSignal ?? callerAbort
       const runOptions: RunOptions = {
-        onMessage: msg => {
-          this.state.messages.push(msg)
-        },
+        ...callerOptions,
+        onMessage: internalOnMessage,
+        ...(needsRunId ? { runId: generateRunId() } : undefined),
+        ...(effectiveAbort ? { abortSignal: effectiveAbort } : undefined),
       }
 
       const result = await runner.run(messages, runOptions)
@@ -282,21 +330,35 @@ export class Agent {
 
       // --- Structured output validation ---
       if (this.config.outputSchema) {
-        return this.validateStructuredOutput(
+        let validated = await this.validateStructuredOutput(
           messages,
           result,
           runner,
           runOptions,
         )
+        // --- afterRun hook ---
+        if (this.config.afterRun) {
+          validated = await this.config.afterRun(validated)
+        }
+        this.emitAgentTrace(callerOptions, agentStartMs, validated)
+        return validated
+      }
+
+      let agentResult = this.toAgentRunResult(result, true)
+
+      // --- afterRun hook ---
+      if (this.config.afterRun) {
+        agentResult = await this.config.afterRun(agentResult)
       }
 
       this.transitionTo('completed')
-      return this.toAgentRunResult(result, true)
+      this.emitAgentTrace(callerOptions, agentStartMs, agentResult)
+      return agentResult
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err))
       this.transitionToError(error)
 
-      return {
+      const errorResult: AgentRunResult = {
         success: false,
         output: error.message,
         messages: [],
@@ -304,9 +366,33 @@ export class Agent {
         toolCalls: [],
         structured: undefined,
       }
+      this.emitAgentTrace(callerOptions, agentStartMs, errorResult)
+      return errorResult
     }
   }
 
+  /** Emit an `agent` trace event if `onTrace` is provided. */
+  private emitAgentTrace(
+    options: Partial<RunOptions> | undefined,
+    startMs: number,
+    result: AgentRunResult,
+  ): void {
+    if (!options?.onTrace) return
+    const endMs = Date.now()
+    emitTrace(options.onTrace, {
+      type: 'agent',
+      runId: options.runId ?? '',
+      taskId: options.taskId,
+      agent: options.traceAgent ?? this.name,
+      turns: result.messages.filter(m => m.role === 'assistant').length,
+      tokens: result.tokenUsage,
+      toolCalls: result.toolCalls.length,
+      startMs,
+      endMs,
+      durationMs: endMs - startMs,
+    })
+  }
+
   /**
    * Validate agent output against the configured `outputSchema`.
    * On first validation failure, retry once with error feedback.
@@ -398,13 +484,31 @@ export class Agent {
     this.transitionTo('running')
 
     try {
+      // --- beforeRun hook ---
+      if (this.config.beforeRun) {
+        const hookCtx = this.buildBeforeRunHookContext(messages)
+        const modified = await this.config.beforeRun(hookCtx)
+        this.applyHookContext(messages, modified, hookCtx.prompt)
+      }
+
       const runner = await this.getRunner()
+      // Fresh timeout per stream call, same as executeRun.
+      const timeoutSignal = this.config.timeoutMs !== undefined && this.config.timeoutMs > 0
+        ? AbortSignal.timeout(this.config.timeoutMs)
+        : undefined
 
-      for await (const event of runner.stream(messages)) {
+      for await (const event of runner.stream(messages, timeoutSignal ? { abortSignal: timeoutSignal } : {})) {
         if (event.type === 'done') {
           const result = event.data as import('./runner.js').RunResult
           this.state.tokenUsage = addUsage(this.state.tokenUsage, result.tokenUsage)
+
+          let agentResult = this.toAgentRunResult(result, true)
+          if (this.config.afterRun) {
+            agentResult = await this.config.afterRun(agentResult)
+          }
           this.transitionTo('completed')
+          yield { type: 'done', data: agentResult } satisfies StreamEvent
+          continue
         } else if (event.type === 'error') {
           const error = event.data instanceof Error
             ? event.data
@@ -421,6 +525,50 @@ export class Agent {
     }
   }
 
+  // -------------------------------------------------------------------------
+  // Hook helpers
+  // -------------------------------------------------------------------------
+
+  /** Extract the prompt text from the last user message to build hook context. */
+  private buildBeforeRunHookContext(messages: LLMMessage[]): BeforeRunHookContext {
+    let prompt = ''
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i]!.role === 'user') {
+        prompt = messages[i]!.content
+          .filter((b): b is import('../types.js').TextBlock => b.type === 'text')
+          .map(b => b.text)
+          .join('')
+        break
+      }
+    }
+    // Strip hook functions to avoid circular self-references in the context
+    const { beforeRun, afterRun, ...agentInfo } = this.config
+    return { prompt, agent: agentInfo as AgentConfig }
+  }
+
+  /**
+   * Apply a (possibly modified) hook context back to the messages array.
+   *
+   * Only text blocks in the last user message are replaced; non-text content
+   * (images, tool results) is preserved. The array element is replaced (not
+   * mutated in place) so that shallow copies of the original array (e.g. from
+   * `prompt()`) are not affected.
+   */
+  private applyHookContext(messages: LLMMessage[], ctx: BeforeRunHookContext, originalPrompt: string): void {
+    if (ctx.prompt === originalPrompt) return
+
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i]!.role === 'user') {
+        const nonTextBlocks = messages[i]!.content.filter(b => b.type !== 'text')
+        messages[i] = {
+          role: 'user',
+          content: [{ type: 'text', text: ctx.prompt }, ...nonTextBlocks],
+        }
+        break
+      }
+    }
+  }
+
   // -------------------------------------------------------------------------
   // State transition helpers
   // -------------------------------------------------------------------------
@@ -449,6 +597,7 @@ export class Agent {
       tokenUsage: result.tokenUsage,
       toolCalls: result.toolCalls,
       structured,
+      ...(result.loopDetected ? { loopDetected: true } : {}),
     }
   }
 

package/src/agent/loop-detector.ts

@@ -0,0 +1,137 @@
+/**
+ * @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

@@ -21,6 +21,7 @@
  */
 
 import type { AgentRunResult } from '../types.js'
+import type { RunOptions } from './runner.js'
 import type { Agent } from './agent.js'
 import { Semaphore } from '../utils/semaphore.js'
 
@@ -123,12 +124,16 @@ export class AgentPool {
    *
    * @throws {Error} If the agent name is not found.
    */
-  async run(agentName: string, prompt: string): Promise<AgentRunResult> {
+  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)
+      return await agent.run(prompt, runOptions)
     } finally {
       this.semaphore.release()
     }
@@ -144,6 +149,7 @@ export class AgentPool {
    *
    * @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>> {
@@ -182,6 +188,7 @@ export class AgentPool {
    *
    * @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) {