@jackchen_me/open-multi-agent 0.2.0 → 1.0.0

package/src/orchestrator/orchestrator.ts

@@ -52,8 +52,10 @@ import type {
   TeamRunResult,
   TokenUsage,
 } from '../types.js'
+import type { RunOptions } from '../agent/runner.js'
 import { Agent } from '../agent/agent.js'
 import { AgentPool } from '../agent/pool.js'
+import { emitTrace, generateRunId } from '../utils/trace.js'
 import { ToolRegistry } from '../tool/framework.js'
 import { ToolExecutor } from '../tool/executor.js'
 import { registerBuiltInTools } from '../tool/built-in/index.js'
@@ -128,9 +130,10 @@ export async function executeWithRetry(
   onRetry?: (data: { attempt: number; maxAttempts: number; error: string; nextDelayMs: number }) => void,
   delayFn: (ms: number) => Promise<void> = sleep,
 ): Promise<AgentRunResult> {
-  const maxAttempts = Math.max(0, task.maxRetries ?? 0) + 1
-  const baseDelay = Math.max(0, task.retryDelayMs ?? 1000)
-  const backoff = Math.max(1, task.retryBackoff ?? 2)
+  const rawRetries = Number.isFinite(task.maxRetries) ? task.maxRetries! : 0
+  const maxAttempts = Math.max(0, rawRetries) + 1
+  const baseDelay = Math.max(0, Number.isFinite(task.retryDelayMs) ? task.retryDelayMs! : 1000)
+  const backoff = Math.max(1, Number.isFinite(task.retryBackoff) ? task.retryBackoff! : 2)
 
   let lastError: string = ''
   // Accumulate token usage across all attempts so billing/observability
@@ -259,6 +262,8 @@ interface RunContext {
   readonly scheduler: Scheduler
   readonly agentResults: Map<string, AgentRunResult>
   readonly config: OrchestratorConfig
+  /** Trace run ID, present when `onTrace` is configured. */
+  readonly runId?: string
 }
 
 /**
@@ -278,6 +283,17 @@ async function executeQueue(
 ): Promise<void> {
   const { team, pool, scheduler, config } = ctx
 
+  // Relay queue-level skip events to the orchestrator's onProgress callback.
+  const unsubSkipped = config.onProgress
+    ? queue.on('task:skipped', (task) => {
+        config.onProgress!({
+          type: 'task_skipped',
+          task: task.id,
+          data: task,
+        } satisfies OrchestratorEvent)
+      })
+    : undefined
+
   while (true) {
     // Re-run auto-assignment each iteration so tasks that were unblocked since
     // the last round (and thus have no assignee yet) get assigned before dispatch.
@@ -289,6 +305,11 @@ async function executeQueue(
       break
     }
 
+    // Track tasks that complete successfully in this round for the approval gate.
+    // Safe to push from concurrent promises: JS is single-threaded, so
+    // Array.push calls from resolved microtasks never interleave.
+    const completedThisRound: Task[] = []
+
     // Dispatch all currently-pending tasks as a parallel batch.
     const dispatchPromises = pending.map(async (task): Promise<void> => {
       // Mark in-progress
@@ -337,10 +358,19 @@ async function executeQueue(
       // Build the prompt: inject shared memory context + task description
       const prompt = await buildTaskPrompt(task, team)
 
+      // Build trace context for this task's agent run
+      const traceOptions: Partial<RunOptions> | undefined = config.onTrace
+        ? { onTrace: config.onTrace, runId: ctx.runId ?? '', taskId: task.id, traceAgent: assignee }
+        : undefined
+
+      const taskStartMs = config.onTrace ? Date.now() : 0
+      let retryCount = 0
+
       const result = await executeWithRetry(
-        () => pool.run(assignee, prompt),
+        () => pool.run(assignee, prompt, traceOptions),
         task,
         (retryData) => {
+          retryCount++
           config.onProgress?.({
             type: 'task_retry',
             task: task.id,
@@ -350,6 +380,23 @@ async function executeQueue(
         },
       )
 
+      // Emit task trace
+      if (config.onTrace) {
+        const taskEndMs = Date.now()
+        emitTrace(config.onTrace, {
+          type: 'task',
+          runId: ctx.runId ?? '',
+          taskId: task.id,
+          taskTitle: task.title,
+          agent: assignee,
+          success: result.success,
+          retries: retryCount,
+          startMs: taskStartMs,
+          endMs: taskEndMs,
+          durationMs: taskEndMs - taskStartMs,
+        })
+      }
+
       ctx.agentResults.set(`${assignee}:${task.id}`, result)
 
       if (result.success) {
@@ -359,7 +406,8 @@ async function executeQueue(
           await sharedMem.write(assignee, `task:${task.id}:result`, result.output)
         }
 
-        queue.complete(task.id, result.output)
+        const completedTask = queue.complete(task.id, result.output)
+        completedThisRound.push(completedTask)
 
         config.onProgress?.({
           type: 'task_complete',
@@ -387,7 +435,32 @@ async function executeQueue(
 
     // Wait for the entire parallel batch before checking for newly-unblocked tasks.
     await Promise.all(dispatchPromises)
+
+    // --- Approval gate ---
+    // After the batch completes, check if the caller wants to approve
+    // the next round before it starts.
+    if (config.onApproval && completedThisRound.length > 0) {
+      scheduler.autoAssign(queue, team.getAgents())
+      const nextPending = queue.getByStatus('pending')
+
+      if (nextPending.length > 0) {
+        let approved: boolean
+        try {
+          approved = await config.onApproval(completedThisRound, nextPending)
+        } catch (err) {
+          const reason = `Skipped: approval callback error — ${err instanceof Error ? err.message : String(err)}`
+          queue.skipRemaining(reason)
+          break
+        }
+        if (!approved) {
+          queue.skipRemaining('Skipped: approval rejected.')
+          break
+        }
+      }
+    }
   }
+
+  unsubSkipped?.()
 }
 
 /**
@@ -440,8 +513,8 @@ async function buildTaskPrompt(task: Task, team: Team): Promise<string> {
  */
 export class OpenMultiAgent {
   private readonly config: Required<
-    Omit<OrchestratorConfig, 'onProgress' | 'defaultBaseURL' | 'defaultApiKey'>
-  > & Pick<OrchestratorConfig, 'onProgress' | 'defaultBaseURL' | 'defaultApiKey'>
+    Omit<OrchestratorConfig, 'onApproval' | 'onProgress' | 'onTrace' | 'defaultBaseURL' | 'defaultApiKey'>
+  > & Pick<OrchestratorConfig, 'onApproval' | 'onProgress' | 'onTrace' | 'defaultBaseURL' | 'defaultApiKey'>
 
   private readonly teams: Map<string, Team> = new Map()
   private completedTaskCount = 0
@@ -461,7 +534,9 @@ export class OpenMultiAgent {
       defaultProvider: config.defaultProvider ?? 'anthropic',
       defaultBaseURL: config.defaultBaseURL,
       defaultApiKey: config.defaultApiKey,
+      onApproval: config.onApproval,
       onProgress: config.onProgress,
+      onTrace: config.onTrace,
     }
   }
 
@@ -519,7 +594,11 @@ export class OpenMultiAgent {
       data: { prompt },
     })
 
-    const result = await agent.run(prompt)
+    const traceOptions: Partial<RunOptions> | undefined = this.config.onTrace
+      ? { onTrace: this.config.onTrace, runId: generateRunId(), traceAgent: config.name }
+      : undefined
+
+    const result = await agent.run(prompt, traceOptions)
 
     this.config.onProgress?.({
       type: 'agent_complete',
@@ -577,6 +656,7 @@ export class OpenMultiAgent {
 
     const decompositionPrompt = this.buildDecompositionPrompt(goal, agentConfigs)
     const coordinatorAgent = buildAgent(coordinatorConfig)
+    const runId = this.config.onTrace ? generateRunId() : undefined
 
     this.config.onProgress?.({
       type: 'agent_start',
@@ -584,7 +664,10 @@ export class OpenMultiAgent {
       data: { phase: 'decomposition', goal },
     })
 
-    const decompositionResult = await coordinatorAgent.run(decompositionPrompt)
+    const decompTraceOptions: Partial<RunOptions> | undefined = this.config.onTrace
+      ? { onTrace: this.config.onTrace, runId: runId ?? '', traceAgent: 'coordinator' }
+      : undefined
+    const decompositionResult = await coordinatorAgent.run(decompositionPrompt, decompTraceOptions)
     const agentResults = new Map<string, AgentRunResult>()
     agentResults.set('coordinator:decompose', decompositionResult)
 
@@ -628,6 +711,7 @@ export class OpenMultiAgent {
       scheduler,
       agentResults,
       config: this.config,
+      runId,
     }
 
     await executeQueue(queue, ctx)
@@ -636,7 +720,10 @@ export class OpenMultiAgent {
     // Step 5: Coordinator synthesises final result
     // ------------------------------------------------------------------
     const synthesisPrompt = await this.buildSynthesisPrompt(goal, queue.list(), team)
-    const synthesisResult = await coordinatorAgent.run(synthesisPrompt)
+    const synthTraceOptions: Partial<RunOptions> | undefined = this.config.onTrace
+      ? { onTrace: this.config.onTrace, runId: runId ?? '', traceAgent: 'coordinator' }
+      : undefined
+    const synthesisResult = await coordinatorAgent.run(synthesisPrompt, synthTraceOptions)
     agentResults.set('coordinator', synthesisResult)
 
     this.config.onProgress?.({
@@ -706,6 +793,7 @@ export class OpenMultiAgent {
       scheduler,
       agentResults,
       config: this.config,
+      runId: this.config.onTrace ? generateRunId() : undefined,
     }
 
     await executeQueue(queue, ctx)
@@ -809,6 +897,7 @@ export class OpenMultiAgent {
   ): Promise<string> {
     const completedTasks = tasks.filter((t) => t.status === 'completed')
     const failedTasks = tasks.filter((t) => t.status === 'failed')
+    const skippedTasks = tasks.filter((t) => t.status === 'skipped')
 
     const resultSections = completedTasks.map((t) => {
       const assignee = t.assignee ?? 'unknown'
@@ -819,6 +908,10 @@ export class OpenMultiAgent {
       (t) => `### ${t.title} (FAILED)\nError: ${t.result ?? 'unknown error'}`,
     )
 
+    const skippedSections = skippedTasks.map(
+      (t) => `### ${t.title} (SKIPPED)\nReason: ${t.result ?? 'approval rejected'}`,
+    )
+
     // Also include shared memory summary for additional context
     let memorySummary = ''
     const sharedMem = team.getSharedMemoryInstance()
@@ -833,11 +926,12 @@ export class OpenMultiAgent {
       `## Task Results`,
       ...resultSections,
       ...(failureSections.length > 0 ? ['', '## Failed Tasks', ...failureSections] : []),
+      ...(skippedSections.length > 0 ? ['', '## Skipped Tasks', ...skippedSections] : []),
       ...(memorySummary ? ['', memorySummary] : []),
       '',
       '## Your Task',
       'Synthesise the above results into a comprehensive final answer that addresses the original goal.',
-      'If some tasks failed, note any gaps in the result.',
+      'If some tasks failed or were skipped, note any gaps in the result.',
     ].join('\n')
   }
 

package/src/task/queue.ts

@@ -18,6 +18,7 @@ export type TaskQueueEvent =
   | 'task:ready'
   | 'task:complete'
   | 'task:failed'
+  | 'task:skipped'
   | 'all:complete'
 
 /** Handler for `'task:ready' | 'task:complete' | 'task:failed'` events. */
@@ -156,6 +157,51 @@ export class TaskQueue {
     return failed
   }
 
+  /**
+   * Marks `taskId` as `'skipped'` and records `reason` in the `result` field.
+   *
+   * Fires `'task:skipped'` for the skipped task and cascades to every
+   * downstream task that transitively depended on it — even if the dependent
+   * has other dependencies that are still pending or completed. A skipped
+   * upstream is treated as permanently unsatisfiable, mirroring `fail()`.
+   *
+   * @throws {Error} when `taskId` is not found.
+   */
+  skip(taskId: string, reason: string): Task {
+    const skipped = this.update(taskId, { status: 'skipped', result: reason })
+    this.emit('task:skipped', skipped)
+    this.cascadeSkip(taskId)
+    if (this.isComplete()) {
+      this.emitAllComplete()
+    }
+    return skipped
+  }
+
+  /**
+   * Marks all non-terminal tasks as `'skipped'`.
+   *
+   * Used when an approval gate rejects continuation — every pending, blocked,
+   * or in-progress task is skipped with the given reason.
+   *
+   * **Important:** Call only when no tasks are actively executing. The
+   * orchestrator invokes this after `await Promise.all()`, so no tasks are
+   * in-flight. Calling while agents are running may mark an in-progress task
+   * as skipped while its agent continues executing.
+   */
+  skipRemaining(reason = 'Skipped: approval rejected.'): void {
+    // Snapshot first — update() mutates the live map, which is unsafe to
+    // iterate over during modification.
+    const snapshot = Array.from(this.tasks.values())
+    for (const task of snapshot) {
+      if (task.status === 'completed' || task.status === 'failed' || task.status === 'skipped') continue
+      const skipped = this.update(task.id, { status: 'skipped', result: reason })
+      this.emit('task:skipped', skipped)
+    }
+    if (this.isComplete()) {
+      this.emitAllComplete()
+    }
+  }
+
   /**
    * Recursively marks all tasks that (transitively) depend on `failedTaskId`
    * as `'failed'` with an informative message, firing `'task:failed'` for each.
@@ -178,6 +224,24 @@ export class TaskQueue {
     }
   }
 
+  /**
+   * Recursively marks all tasks that (transitively) depend on `skippedTaskId`
+   * as `'skipped'`, firing `'task:skipped'` for each.
+   */
+  private cascadeSkip(skippedTaskId: string): void {
+    for (const task of this.tasks.values()) {
+      if (task.status !== 'blocked' && task.status !== 'pending') continue
+      if (!task.dependsOn?.includes(skippedTaskId)) continue
+
+      const cascaded = this.update(task.id, {
+        status: 'skipped',
+        result: `Skipped: dependency "${skippedTaskId}" was skipped.`,
+      })
+      this.emit('task:skipped', cascaded)
+      this.cascadeSkip(task.id)
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Queries
   // ---------------------------------------------------------------------------
@@ -227,11 +291,11 @@ export class TaskQueue {
 
   /**
    * Returns `true` when every task in the queue has reached a terminal state
-   * (`'completed'` or `'failed'`), **or** the queue is empty.
+   * (`'completed'`, `'failed'`, or `'skipped'`), **or** the queue is empty.
    */
   isComplete(): boolean {
     for (const task of this.tasks.values()) {
-      if (task.status !== 'completed' && task.status !== 'failed') return false
+      if (task.status !== 'completed' && task.status !== 'failed' && task.status !== 'skipped') return false
     }
     return true
   }
@@ -249,12 +313,14 @@ export class TaskQueue {
     total: number
     completed: number
     failed: number
+    skipped: number
     inProgress: number
     pending: number
     blocked: number
   } {
     let completed = 0
     let failed = 0
+    let skipped = 0
     let inProgress = 0
     let pending = 0
     let blocked = 0
@@ -267,6 +333,9 @@ export class TaskQueue {
         case 'failed':
           failed++
           break
+        case 'skipped':
+          skipped++
+          break
         case 'in_progress':
           inProgress++
           break
@@ -283,6 +352,7 @@ export class TaskQueue {
       total: this.tasks.size,
       completed,
       failed,
+      skipped,
       inProgress,
       pending,
       blocked,
@@ -370,7 +440,7 @@ export class TaskQueue {
     }
   }
 
-  private emit(event: 'task:ready' | 'task:complete' | 'task:failed', task: Task): void {
+  private emit(event: 'task:ready' | 'task:complete' | 'task:failed' | 'task:skipped', task: Task): void {
     const map = this.listeners.get(event)
     if (!map) return
     for (const handler of map.values()) {

package/src/tool/text-tool-extractor.ts

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Fallback tool-call extractor for local models.
+ *
+ * When a local model (Ollama, vLLM, LM Studio) returns tool calls as plain
+ * text instead of using the OpenAI `tool_calls` wire format, this module
+ * attempts to extract them from the text output.
+ *
+ * Common scenarios:
+ * - Ollama thinking-model bug: tool call JSON ends up inside unclosed `<think>` tags
+ * - Model outputs raw JSON tool calls without the server parsing them
+ * - Model wraps tool calls in markdown code fences
+ * - Hermes-format `<tool_call>` tags
+ *
+ * This is a **safety net**, not the primary path. Native `tool_calls` from
+ * the server are always preferred.
+ */
+
+import type { ToolUseBlock } from '../types.js'
+
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+
+let callCounter = 0
+
+/** Generate a unique tool-call ID for extracted calls. */
+function generateToolCallId(): string {
+  return `extracted_call_${Date.now()}_${++callCounter}`
+}
+
+// ---------------------------------------------------------------------------
+// Internal parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to parse a single JSON object as a tool call.
+ *
+ * Accepted shapes:
+ * ```json
+ * { "name": "bash", "arguments": { "command": "ls" } }
+ * { "name": "bash", "parameters": { "command": "ls" } }
+ * { "function": { "name": "bash", "arguments": { "command": "ls" } } }
+ * ```
+ */
+function parseToolCallJSON(
+  json: unknown,
+  knownToolNames: ReadonlySet<string>,
+): ToolUseBlock | null {
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+    return null
+  }
+
+  const obj = json as Record<string, unknown>
+
+  // Shape: { function: { name, arguments } }
+  if (typeof obj['function'] === 'object' && obj['function'] !== null) {
+    const fn = obj['function'] as Record<string, unknown>
+    return parseFlat(fn, knownToolNames)
+  }
+
+  // Shape: { name, arguments|parameters }
+  return parseFlat(obj, knownToolNames)
+}
+
+function parseFlat(
+  obj: Record<string, unknown>,
+  knownToolNames: ReadonlySet<string>,
+): ToolUseBlock | null {
+  const name = obj['name']
+  if (typeof name !== 'string' || name.length === 0) return null
+
+  // Whitelist check — don't treat arbitrary JSON as a tool call
+  if (knownToolNames.size > 0 && !knownToolNames.has(name)) return null
+
+  let input: Record<string, unknown> = {}
+  const args = obj['arguments'] ?? obj['parameters'] ?? obj['input']
+  if (args !== null && args !== undefined) {
+    if (typeof args === 'string') {
+      try {
+        const parsed = JSON.parse(args)
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+          input = parsed as Record<string, unknown>
+        }
+      } catch {
+        // Malformed — use empty input
+      }
+    } else if (typeof args === 'object' && !Array.isArray(args)) {
+      input = args as Record<string, unknown>
+    }
+  }
+
+  return {
+    type: 'tool_use',
+    id: generateToolCallId(),
+    name,
+    input,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON extraction from text
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all top-level JSON objects in a string by tracking brace depth.
+ * Returns the parsed objects (not sub-objects).
+ */
+function extractJSONObjects(text: string): unknown[] {
+  const results: unknown[] = []
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escape = false
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!
+
+    if (escape) {
+      escape = false
+      continue
+    }
+
+    if (ch === '\\' && inString) {
+      escape = true
+      continue
+    }
+
+    if (ch === '"') {
+      inString = !inString
+      continue
+    }
+
+    if (inString) continue
+
+    if (ch === '{') {
+      if (depth === 0) start = i
+      depth++
+    } else if (ch === '}') {
+      depth--
+      if (depth === 0 && start !== -1) {
+        const candidate = text.slice(start, i + 1)
+        try {
+          results.push(JSON.parse(candidate))
+        } catch {
+          // Not valid JSON — skip
+        }
+        start = -1
+      }
+    }
+  }
+
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// Hermes format: <tool_call>...</tool_call>
+// ---------------------------------------------------------------------------
+
+function extractHermesToolCalls(
+  text: string,
+  knownToolNames: ReadonlySet<string>,
+): ToolUseBlock[] {
+  const results: ToolUseBlock[] = []
+
+  for (const match of text.matchAll(/<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/g)) {
+    const inner = match[1]!.trim()
+    try {
+      const parsed: unknown = JSON.parse(inner)
+      const block = parseToolCallJSON(parsed, knownToolNames)
+      if (block !== null) results.push(block)
+    } catch {
+      // Malformed hermes content — skip
+    }
+  }
+
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to extract tool calls from a model's text output.
+ *
+ * Tries multiple strategies in order:
+ * 1. Hermes `<tool_call>` tags
+ * 2. JSON objects in text (bare or inside code fences)
+ *
+ * @param text           - The model's text output.
+ * @param knownToolNames - Whitelist of registered tool names. When non-empty,
+ *                         only JSON objects whose `name` matches a known tool
+ *                         are treated as tool calls.
+ * @returns Extracted {@link ToolUseBlock}s, or an empty array if none found.
+ */
+export function extractToolCallsFromText(
+  text: string,
+  knownToolNames: string[],
+): ToolUseBlock[] {
+  if (text.length === 0) return []
+
+  const nameSet = new Set(knownToolNames)
+
+  // Strategy 1: Hermes format
+  const hermesResults = extractHermesToolCalls(text, nameSet)
+  if (hermesResults.length > 0) return hermesResults
+
+  // Strategy 2: Strip code fences, then extract JSON objects
+  const stripped = text.replace(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/g, '$1')
+  const jsonObjects = extractJSONObjects(stripped)
+
+  const results: ToolUseBlock[] = []
+  for (const obj of jsonObjects) {
+    const block = parseToolCallJSON(obj, nameSet)
+    if (block !== null) results.push(block)
+  }
+
+  return results
+}