@jackchen_me/open-multi-agent 0.1.0 → 1.0.0

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
+}

package/src/types.ts

@@ -94,7 +94,7 @@ export interface LLMResponse {
  * - `error`       — an unrecoverable error occurred; `data` is an `Error`
  */
 export interface StreamEvent {
-  readonly type: 'text' | 'tool_use' | 'tool_result' | 'done' | 'error'
+  readonly type: 'text' | 'tool_use' | 'tool_result' | 'loop_detected' | 'done' | 'error'
   readonly data: unknown
 }
 
@@ -182,17 +182,97 @@ export interface ToolDefinition<TInput = Record<string, unknown>> {
 // Agent
 // ---------------------------------------------------------------------------
 
+/** Context passed to the {@link AgentConfig.beforeRun} hook. */
+export interface BeforeRunHookContext {
+  /** The user prompt text. */
+  readonly prompt: string
+  /** The agent's static configuration. */
+  readonly agent: AgentConfig
+}
+
 /** Static configuration for a single agent. */
 export interface AgentConfig {
   readonly name: string
   readonly model: string
-  readonly provider?: 'anthropic' | 'openai'
+  readonly provider?: 'anthropic' | 'copilot' | 'grok' | 'openai' | 'gemini'
+  /**
+   * Custom base URL for OpenAI-compatible APIs (Ollama, vLLM, LM Studio, etc.).
+   * Note: local servers that don't require auth still need `apiKey` set to a
+   * non-empty placeholder (e.g. `'ollama'`) because the OpenAI SDK validates it.
+   */
+  readonly baseURL?: string
+  /** API key override; falls back to the provider's standard env var. */
+  readonly apiKey?: string
   readonly systemPrompt?: string
   /** Names of tools (from the tool registry) available to this agent. */
   readonly tools?: readonly string[]
   readonly maxTurns?: number
   readonly maxTokens?: number
   readonly temperature?: number
+  /**
+   * Maximum wall-clock time (in milliseconds) for the entire agent run.
+   * When exceeded, the run is aborted via `AbortSignal.timeout()`.
+   * Useful for local models where inference can be unpredictably slow.
+   */
+  readonly timeoutMs?: number
+  /**
+   * Loop detection configuration. When set, the agent tracks repeated tool
+   * calls and text outputs to detect stuck loops before `maxTurns` is reached.
+   */
+  readonly loopDetection?: LoopDetectionConfig
+  /**
+   * Optional Zod schema for structured output.  When set, the agent's final
+   * output is parsed as JSON and validated against this schema.  A single
+   * retry with error feedback is attempted on validation failure.
+   */
+  readonly outputSchema?: ZodSchema
+  /**
+   * Called before each agent run. Receives the prompt and agent config.
+   * Return a (possibly modified) context to continue, or throw to abort the run.
+   * Only `prompt` from the returned context is applied; `agent` is read-only informational.
+   */
+  readonly beforeRun?: (context: BeforeRunHookContext) => Promise<BeforeRunHookContext> | BeforeRunHookContext
+  /**
+   * Called after each agent run completes successfully. Receives the run result.
+   * Return a (possibly modified) result, or throw to mark the run as failed.
+   * Not called when the run throws. For error observation, handle errors at the call site.
+   */
+  readonly afterRun?: (result: AgentRunResult) => Promise<AgentRunResult> | AgentRunResult
+}
+
+// ---------------------------------------------------------------------------
+// Loop detection
+// ---------------------------------------------------------------------------
+
+/** Configuration for agent loop detection. */
+export interface LoopDetectionConfig {
+  /**
+   * Maximum consecutive times the same tool call (name + args) or text
+   * output can repeat before detection triggers. Default: `3`.
+   */
+  readonly maxRepetitions?: number
+  /**
+   * Number of recent turns to track for repetition analysis. Default: `4`.
+   */
+  readonly loopDetectionWindow?: number
+  /**
+   * Action to take when a loop is detected.
+   * - `'warn'`      — inject a "you appear stuck" message, give the LLM one
+   *                    more chance; terminate if the loop persists (default)
+   * - `'terminate'` — stop the run immediately
+   * - `function`    — custom callback (sync or async); return `'continue'`,
+   *                    `'inject'`, or `'terminate'` to control the outcome
+   */
+  readonly onLoopDetected?: 'warn' | 'terminate' | ((info: LoopDetectionInfo) => 'continue' | 'inject' | 'terminate' | Promise<'continue' | 'inject' | 'terminate'>)
+}
+
+/** Diagnostic payload emitted when a loop is detected. */
+export interface LoopDetectionInfo {
+  readonly kind: 'tool_repetition' | 'text_repetition'
+  /** Number of consecutive identical occurrences observed. */
+  readonly repetitions: number
+  /** Human-readable description of the detected loop. */
+  readonly detail: string
 }
 
 /** Lifecycle state tracked during an agent run. */
@@ -219,6 +299,14 @@ export interface AgentRunResult {
   readonly messages: LLMMessage[]
   readonly tokenUsage: TokenUsage
   readonly toolCalls: ToolCallRecord[]
+  /**
+   * Parsed and validated structured output when `outputSchema` is set on the
+   * agent config.  `undefined` when no schema is configured or validation
+   * failed after retry.
+   */
+  readonly structured?: unknown
+  /** True when the run was terminated or warned due to loop detection. */
+  readonly loopDetected?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -246,7 +334,7 @@ export interface TeamRunResult {
 // ---------------------------------------------------------------------------
 
 /** Valid states for a {@link Task}. */
-export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'blocked'
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'blocked' | 'skipped'
 
 /** A discrete unit of work tracked by the orchestrator. */
 export interface Task {
@@ -261,19 +349,32 @@ export interface Task {
   result?: string
   readonly createdAt: Date
   updatedAt: Date
+  /** Maximum number of retry attempts on failure (default: 0 — no retry). */
+  readonly maxRetries?: number
+  /** Base delay in ms before the first retry (default: 1000). */
+  readonly retryDelayMs?: number
+  /** Exponential backoff multiplier (default: 2). */
+  readonly retryBackoff?: number
 }
 
 // ---------------------------------------------------------------------------
 // Orchestrator
 // ---------------------------------------------------------------------------
 
-/** Progress event emitted by the orchestrator during a run. */
+/**
+ * Progress event emitted by the orchestrator during a run.
+ *
+ * **v0.3 addition:** `'task_skipped'` — consumers with exhaustive switches
+ * on `type` will need to add a case for this variant.
+ */
 export interface OrchestratorEvent {
   readonly type:
     | 'agent_start'
     | 'agent_complete'
     | 'task_start'
     | 'task_complete'
+    | 'task_skipped'
+    | 'task_retry'
     | 'message'
     | 'error'
   readonly agent?: string
@@ -285,10 +386,89 @@ export interface OrchestratorEvent {
 export interface OrchestratorConfig {
   readonly maxConcurrency?: number
   readonly defaultModel?: string
-  readonly defaultProvider?: 'anthropic' | 'openai'
-  onProgress?: (event: OrchestratorEvent) => void
+  readonly defaultProvider?: 'anthropic' | 'copilot' | 'grok' | 'openai' | 'gemini'
+  readonly defaultBaseURL?: string
+  readonly defaultApiKey?: string
+  readonly onProgress?: (event: OrchestratorEvent) => void
+  readonly onTrace?: (event: TraceEvent) => void | Promise<void>
+  /**
+   * Optional approval gate called between task execution rounds.
+   *
+   * After a batch of tasks completes, this callback receives all
+   * completed {@link Task}s from that round and the list of tasks about
+   * to start next. Return `true` to continue or `false` to abort —
+   * remaining tasks will be marked `'skipped'`.
+   *
+   * Not called when:
+   * - No tasks succeeded in the round (all failed).
+   * - No pending tasks remain after the round (final batch).
+   *
+   * **Note:** Do not mutate the {@link Task} objects passed to this
+   * callback — they are live references to queue state. Mutation is
+   * undefined behavior.
+   */
+  readonly onApproval?: (completedTasks: readonly Task[], nextTasks: readonly Task[]) => Promise<boolean>
 }
 
+// ---------------------------------------------------------------------------
+// Trace events — lightweight observability spans
+// ---------------------------------------------------------------------------
+
+/** Trace event type discriminants. */
+export type TraceEventType = 'llm_call' | 'tool_call' | 'task' | 'agent'
+
+/** Shared fields present on every trace event. */
+export interface TraceEventBase {
+  /** Unique identifier for the entire run (runTeam / runTasks / runAgent call). */
+  readonly runId: string
+  readonly type: TraceEventType
+  /** Unix epoch ms when the span started. */
+  readonly startMs: number
+  /** Unix epoch ms when the span ended. */
+  readonly endMs: number
+  /** Wall-clock duration in milliseconds (`endMs - startMs`). */
+  readonly durationMs: number
+  /** Agent name associated with this span. */
+  readonly agent: string
+  /** Task ID associated with this span. */
+  readonly taskId?: string
+}
+
+/** Emitted for each LLM API call (one per agent turn). */
+export interface LLMCallTrace extends TraceEventBase {
+  readonly type: 'llm_call'
+  readonly model: string
+  readonly turn: number
+  readonly tokens: TokenUsage
+}
+
+/** Emitted for each tool execution. */
+export interface ToolCallTrace extends TraceEventBase {
+  readonly type: 'tool_call'
+  readonly tool: string
+  readonly isError: boolean
+}
+
+/** Emitted when a task completes (wraps the full retry sequence). */
+export interface TaskTrace extends TraceEventBase {
+  readonly type: 'task'
+  readonly taskId: string
+  readonly taskTitle: string
+  readonly success: boolean
+  readonly retries: number
+}
+
+/** Emitted when an agent run completes (wraps the full conversation loop). */
+export interface AgentTrace extends TraceEventBase {
+  readonly type: 'agent'
+  readonly turns: number
+  readonly tokens: TokenUsage
+  readonly toolCalls: number
+}
+
+/** Discriminated union of all trace event types. */
+export type TraceEvent = LLMCallTrace | ToolCallTrace | TaskTrace | AgentTrace
+
 // ---------------------------------------------------------------------------
 // Memory
 // ---------------------------------------------------------------------------

package/src/utils/trace.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Trace emission utilities for the observability layer.
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { TraceEvent } from '../types.js'
+
+/**
+ * Safely emit a trace event. Swallows callback errors so a broken
+ * subscriber never crashes agent execution.
+ */
+export function emitTrace(
+  fn: ((event: TraceEvent) => void | Promise<void>) | undefined,
+  event: TraceEvent,
+): void {
+  if (!fn) return
+  try {
+    // Guard async callbacks: if fn returns a Promise, swallow its rejection
+    // so an async onTrace never produces an unhandled promise rejection.
+    const result = fn(event) as unknown
+    if (result && typeof (result as Promise<unknown>).catch === 'function') {
+      ;(result as Promise<unknown>).catch(noop)
+    }
+  } catch {
+    // Intentionally swallowed — observability must never break execution.
+  }
+}
+
+function noop() {}
+
+/** Generate a unique run ID for trace correlation. */
+export function generateRunId(): string {
+  return randomUUID()
+}