@jackchen_me/open-multi-agent 0.1.0 → 1.0.0

package/src/agent/runner.ts

@@ -25,7 +25,12 @@ import type {
   ToolUseContext,
   LLMAdapter,
   LLMChatOptions,
+  TraceEvent,
+  LoopDetectionConfig,
+  LoopDetectionInfo,
 } from '../types.js'
+import { LoopDetector } from './loop-detector.js'
+import { emitTrace } from '../utils/trace.js'
 import type { ToolRegistry } from '../tool/framework.js'
 import type { ToolExecutor } from '../tool/executor.js'
 
@@ -63,6 +68,8 @@ export interface RunnerOptions {
   readonly agentName?: string
   /** Short role description of the agent (used in tool context). */
   readonly agentRole?: string
+  /** Loop detection configuration. When set, detects stuck agent loops. */
+  readonly loopDetection?: LoopDetectionConfig
 }
 
 /**
@@ -76,6 +83,24 @@ export interface RunOptions {
   readonly onToolResult?: (name: string, result: ToolResult) => void
   /** Fired after each complete {@link LLMMessage} is appended. */
   readonly onMessage?: (message: LLMMessage) => void
+  /**
+   * Fired when the runner detects a potential configuration issue.
+   * For example, when a model appears to ignore tool definitions.
+   */
+  readonly onWarning?: (message: string) => void
+  /** Trace callback for observability spans. Async callbacks are safe. */
+  readonly onTrace?: (event: TraceEvent) => void | Promise<void>
+  /** Run ID for trace correlation. */
+  readonly runId?: string
+  /** Task ID for trace correlation. */
+  readonly taskId?: string
+  /** Agent name for trace correlation (overrides RunnerOptions.agentName). */
+  readonly traceAgent?: string
+  /**
+   * Per-call abort signal. When set, takes precedence over the static
+   * {@link RunnerOptions.abortSignal}. Useful for per-run timeouts.
+   */
+  readonly abortSignal?: AbortSignal
 }
 
 /** The aggregated result returned when a full run completes. */
@@ -90,6 +115,8 @@ export interface RunResult {
   readonly tokenUsage: TokenUsage
   /** Total number of LLM turns (including tool-call follow-ups). */
   readonly turns: number
+  /** True when the run was terminated or warned due to loop detection. */
+  readonly loopDetected?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -166,13 +193,7 @@ export class AgentRunner {
     options: RunOptions = {},
   ): Promise<RunResult> {
     // Collect everything yielded by the internal streaming loop.
-    const accumulated: {
-      messages: LLMMessage[]
-      output: string
-      toolCalls: ToolCallRecord[]
-      tokenUsage: TokenUsage
-      turns: number
-    } = {
+    const accumulated: RunResult = {
       messages: [],
       output: '',
       toolCalls: [],
@@ -182,12 +203,7 @@ export class AgentRunner {
 
     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
+        Object.assign(accumulated, event.data)
       }
     }
 
@@ -225,22 +241,33 @@ export class AgentRunner {
       ? allDefs.filter(d => this.options.allowedTools!.includes(d.name))
       : allDefs
 
+    // Per-call abortSignal takes precedence over the static one.
+    const effectiveAbortSignal = options.abortSignal ?? this.options.abortSignal
+
     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,
+      abortSignal: effectiveAbortSignal,
     }
 
+    // Loop detection state — only allocated when configured.
+    const detector = this.options.loopDetection
+      ? new LoopDetector(this.options.loopDetection)
+      : null
+    let loopDetected = false
+    let loopWarned = false
+    const loopAction = this.options.loopDetection?.onLoopDetected ?? 'warn'
+
     try {
       // -----------------------------------------------------------------
       // Main agentic loop — `while (true)` until end_turn or maxTurns
       // -----------------------------------------------------------------
       while (true) {
         // Respect abort before each LLM call.
-        if (this.options.abortSignal?.aborted) {
+        if (effectiveAbortSignal?.aborted) {
           break
         }
 
@@ -254,7 +281,23 @@ export class AgentRunner {
         // ------------------------------------------------------------------
         // Step 1: Call the LLM and collect the full response for this turn.
         // ------------------------------------------------------------------
+        const llmStartMs = Date.now()
         const response = await this.adapter.chat(conversationMessages, baseChatOptions)
+        if (options.onTrace) {
+          const llmEndMs = Date.now()
+          emitTrace(options.onTrace, {
+            type: 'llm_call',
+            runId: options.runId ?? '',
+            taskId: options.taskId,
+            agent: options.traceAgent ?? this.options.agentName ?? 'unknown',
+            model: this.options.model,
+            turn: turns,
+            tokens: response.usage,
+            startMs: llmStartMs,
+            endMs: llmEndMs,
+            durationMs: llmEndMs - llmStartMs,
+          })
+        }
 
         totalUsage = addTokenUsage(totalUsage, response.usage)
 
@@ -275,21 +318,77 @@ export class AgentRunner {
           yield { type: 'text', data: turnText } satisfies StreamEvent
         }
 
-        // Announce each tool-use block the model requested.
+        // Extract tool-use blocks for detection and execution.
         const toolUseBlocks = extractToolUseBlocks(response.content)
-        for (const block of toolUseBlocks) {
-          yield { type: 'tool_use', data: block } satisfies StreamEvent
+
+        // ------------------------------------------------------------------
+        // Step 2.5: Loop detection — check before yielding tool_use events
+        // so that terminate mode doesn't emit orphaned tool_use without
+        // matching tool_result.
+        // ------------------------------------------------------------------
+        let injectWarning = false
+        let injectWarningKind: 'tool_repetition' | 'text_repetition' = 'tool_repetition'
+        if (detector && toolUseBlocks.length > 0) {
+          const toolInfo = detector.recordToolCalls(toolUseBlocks)
+          const textInfo = turnText.length > 0 ? detector.recordText(turnText) : null
+          const info = toolInfo ?? textInfo
+
+          if (info) {
+            yield { type: 'loop_detected', data: info } satisfies StreamEvent
+            options.onWarning?.(info.detail)
+
+            const action = typeof loopAction === 'function'
+              ? await loopAction(info)
+              : loopAction
+
+            if (action === 'terminate') {
+              loopDetected = true
+              finalOutput = turnText
+              break
+            } else if (action === 'warn' || action === 'inject') {
+              if (loopWarned) {
+                // Second detection after a warning — force terminate.
+                loopDetected = true
+                finalOutput = turnText
+                break
+              }
+              loopWarned = true
+              injectWarning = true
+              injectWarningKind = info.kind
+              // Fall through to execute tools, then inject warning.
+            }
+            // 'continue' — do nothing, let the loop proceed normally.
+          } else {
+            // No loop detected this turn — agent has recovered, so reset
+            // the warning state. A future loop gets a fresh warning cycle.
+            loopWarned = false
+          }
         }
 
         // ------------------------------------------------------------------
         // Step 3: Decide whether to continue looping.
         // ------------------------------------------------------------------
         if (toolUseBlocks.length === 0) {
+          // Warn on first turn if tools were provided but model didn't use them.
+          if (turns === 1 && toolDefs.length > 0 && options.onWarning) {
+            const agentName = this.options.agentName ?? 'unknown'
+            options.onWarning(
+              `Agent "${agentName}" has ${toolDefs.length} tool(s) available but the model ` +
+              `returned no tool calls. If using a local model, verify it supports tool calling ` +
+              `(see https://ollama.com/search?c=tools).`,
+            )
+          }
           // No tools requested — this is the terminal assistant turn.
           finalOutput = turnText
           break
         }
 
+        // Announce each tool-use block the model requested (after loop
+        // detection, so terminate mode never emits unpaired events).
+        for (const block of toolUseBlocks) {
+          yield { type: 'tool_use', data: block } satisfies StreamEvent
+        }
+
         // ------------------------------------------------------------------
         // Step 4: Execute all tool calls in PARALLEL.
         //
@@ -319,10 +418,25 @@ export class AgentRunner {
             result = { data: message, isError: true }
           }
 
-          const duration = Date.now() - startTime
+          const endTime = Date.now()
+          const duration = endTime - startTime
 
           options.onToolResult?.(block.name, result)
 
+          if (options.onTrace) {
+            emitTrace(options.onTrace, {
+              type: 'tool_call',
+              runId: options.runId ?? '',
+              taskId: options.taskId,
+              agent: options.traceAgent ?? this.options.agentName ?? 'unknown',
+              tool: block.name,
+              isError: result.isError ?? false,
+              startMs: startTime,
+              endMs: endTime,
+              durationMs: duration,
+            })
+          }
+
           const record: ToolCallRecord = {
             toolName: block.name,
             input: block.input,
@@ -354,6 +468,20 @@ export class AgentRunner {
           yield { type: 'tool_result', data: resultBlock } satisfies StreamEvent
         }
 
+        // Inject a loop-detection warning into the tool-result message so
+        // the LLM sees it alongside the results (avoids two consecutive user
+        // messages which violates the alternating-role constraint).
+        if (injectWarning) {
+          const warningText = injectWarningKind === 'text_repetition'
+            ? 'WARNING: You appear to be generating the same response repeatedly. ' +
+              'This suggests you are stuck in a loop. Please try a different approach ' +
+              'or provide new information.'
+            : 'WARNING: You appear to be repeating the same tool calls with identical arguments. ' +
+              'This suggests you are stuck in a loop. Please try a different approach, use different ' +
+              'parameters, or explain what you are trying to accomplish.'
+          toolResultBlocks.push({ type: 'text' as const, text: warningText })
+        }
+
         const toolResultMessage: LLMMessage = {
           role: 'user',
           content: toolResultBlocks,
@@ -387,6 +515,7 @@ export class AgentRunner {
       toolCalls: allToolCalls,
       tokenUsage: totalUsage,
       turns,
+      ...(loopDetected ? { loopDetected: true } : {}),
     }
 
     yield { type: 'done', data: runResult } satisfies StreamEvent

package/src/agent/structured-output.ts

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Structured output utilities for agent responses.
+ *
+ * Provides JSON extraction, Zod validation, and system-prompt injection so
+ * that agents can return typed, schema-validated output.
+ */
+
+import { type ZodSchema } from 'zod'
+import { zodToJsonSchema } from '../tool/framework.js'
+
+// ---------------------------------------------------------------------------
+// System-prompt instruction builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a JSON-mode instruction block to append to the agent's system prompt.
+ *
+ * Converts the Zod schema to JSON Schema and formats it as a clear directive
+ * for the LLM to respond with valid JSON matching the schema.
+ */
+export function buildStructuredOutputInstruction(schema: ZodSchema): string {
+  const jsonSchema = zodToJsonSchema(schema)
+  return [
+    '',
+    '## Output Format (REQUIRED)',
+    'You MUST respond with ONLY valid JSON that conforms to the following JSON Schema.',
+    'Do NOT include any text, markdown fences, or explanation outside the JSON object.',
+    'Do NOT wrap the JSON in ```json code fences.',
+    '',
+    '```',
+    JSON.stringify(jsonSchema, null, 2),
+    '```',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// JSON extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to extract and parse JSON from the agent's raw text output.
+ *
+ * Handles three cases in order:
+ * 1. The output is already valid JSON (ideal case)
+ * 2. The output contains a ` ```json ` fenced block
+ * 3. The output contains a bare JSON object/array (first `{`/`[` to last `}`/`]`)
+ *
+ * @throws {Error} when no valid JSON can be extracted
+ */
+export function extractJSON(raw: string): unknown {
+  const trimmed = raw.trim()
+
+  // Case 1: Direct parse
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    // Continue to fallback strategies
+  }
+
+  // Case 2a: Prefer ```json tagged fence
+  const jsonFenceMatch = trimmed.match(/```json\s*([\s\S]*?)```/)
+  if (jsonFenceMatch?.[1]) {
+    try {
+      return JSON.parse(jsonFenceMatch[1].trim())
+    } catch {
+      // Continue
+    }
+  }
+
+  // Case 2b: Fall back to bare ``` fence
+  const bareFenceMatch = trimmed.match(/```\s*([\s\S]*?)```/)
+  if (bareFenceMatch?.[1]) {
+    try {
+      return JSON.parse(bareFenceMatch[1].trim())
+    } catch {
+      // Continue
+    }
+  }
+
+  // Case 3: Find first { to last } (object)
+  const objStart = trimmed.indexOf('{')
+  const objEnd = trimmed.lastIndexOf('}')
+  if (objStart !== -1 && objEnd > objStart) {
+    try {
+      return JSON.parse(trimmed.slice(objStart, objEnd + 1))
+    } catch {
+      // Fall through
+    }
+  }
+
+  // Case 3b: Find first [ to last ] (array)
+  const arrStart = trimmed.indexOf('[')
+  const arrEnd = trimmed.lastIndexOf(']')
+  if (arrStart !== -1 && arrEnd > arrStart) {
+    try {
+      return JSON.parse(trimmed.slice(arrStart, arrEnd + 1))
+    } catch {
+      // Fall through
+    }
+  }
+
+  throw new Error(
+    `Failed to extract JSON from output. Raw output begins with: "${trimmed.slice(0, 100)}"`,
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Zod validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a parsed JSON value against a Zod schema.
+ *
+ * @returns The validated (and potentially transformed) value on success.
+ * @throws {Error} with a human-readable Zod error message on failure.
+ */
+export function validateOutput(schema: ZodSchema, data: unknown): unknown {
+  const result = schema.safeParse(data)
+  if (result.success) {
+    return result.data
+  }
+  const issues = result.error.issues
+    .map(issue => `  - ${issue.path.length > 0 ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+    .join('\n')
+  throw new Error(`Output validation failed:\n${issues}`)
+}

package/src/index.ts

@@ -54,7 +54,7 @@
 // Orchestrator (primary entry point)
 // ---------------------------------------------------------------------------
 
-export { OpenMultiAgent } from './orchestrator/orchestrator.js'
+export { OpenMultiAgent, executeWithRetry, computeRetryDelay } from './orchestrator/orchestrator.js'
 export { Scheduler } from './orchestrator/scheduler.js'
 export type { SchedulingStrategy } from './orchestrator/scheduler.js'
 
@@ -63,6 +63,8 @@ export type { SchedulingStrategy } from './orchestrator/scheduler.js'
 // ---------------------------------------------------------------------------
 
 export { Agent } from './agent/agent.js'
+export { LoopDetector } from './agent/loop-detector.js'
+export { buildStructuredOutputInstruction, extractJSON, validateOutput } from './agent/structured-output.js'
 export { AgentPool, Semaphore } from './agent/pool.js'
 export type { PoolStatus } from './agent/pool.js'
 
@@ -146,7 +148,10 @@ export type {
   AgentConfig,
   AgentState,
   AgentRunResult,
+  BeforeRunHookContext,
   ToolCallRecord,
+  LoopDetectionConfig,
+  LoopDetectionInfo,
 
   // Team
   TeamConfig,
@@ -160,7 +165,18 @@ export type {
   OrchestratorConfig,
   OrchestratorEvent,
 
+  // Trace
+  TraceEventType,
+  TraceEventBase,
+  TraceEvent,
+  LLMCallTrace,
+  ToolCallTrace,
+  TaskTrace,
+  AgentTrace,
+
   // Memory
   MemoryEntry,
   MemoryStore,
 } from './types.js'
+
+export { generateRunId } from './utils/trace.js'

package/src/llm/adapter.ts

@@ -11,6 +11,7 @@
  *
  * const anthropic = createAdapter('anthropic')
  * const openai    = createAdapter('openai', process.env.OPENAI_API_KEY)
+ * const gemini    = createAdapter('gemini', process.env.GEMINI_API_KEY)
  * ```
  */
 
@@ -37,33 +38,56 @@ import type { LLMAdapter } from '../types.js'
  * Additional providers can be integrated by implementing {@link LLMAdapter}
  * directly and bypassing this factory.
  */
-export type SupportedProvider = 'anthropic' | 'openai'
+export type SupportedProvider = 'anthropic' | 'copilot' | 'grok' | 'openai' | 'gemini'
 
 /**
  * Instantiate the appropriate {@link LLMAdapter} for the given provider.
  *
- * API keys fall back to the standard environment variables
- * (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) when not supplied explicitly.
+ * API keys fall back to the standard environment variables when not supplied
+ * explicitly:
+ * - `anthropic` → `ANTHROPIC_API_KEY`
+ * - `openai`    → `OPENAI_API_KEY`
+ * - `gemini`    → `GEMINI_API_KEY` / `GOOGLE_API_KEY`
+ * - `grok`      → `XAI_API_KEY`
+ * - `copilot`   → `GITHUB_COPILOT_TOKEN` / `GITHUB_TOKEN`, or interactive
+ *                  OAuth2 device flow if neither is set
  *
  * Adapters are imported lazily so that projects using only one provider
  * are not forced to install the SDK for the other.
  *
  * @param provider - Which LLM provider to target.
  * @param apiKey   - Optional API key override; falls back to env var.
+ * @param baseURL  - Optional base URL for OpenAI-compatible APIs (Ollama, vLLM, etc.).
  * @throws {Error} When the provider string is not recognised.
  */
 export async function createAdapter(
   provider: SupportedProvider,
   apiKey?: string,
+  baseURL?: string,
 ): Promise<LLMAdapter> {
   switch (provider) {
     case 'anthropic': {
       const { AnthropicAdapter } = await import('./anthropic.js')
-      return new AnthropicAdapter(apiKey)
+      return new AnthropicAdapter(apiKey, baseURL)
+    }
+    case 'copilot': {
+      if (baseURL) {
+        console.warn('[open-multi-agent] baseURL is not supported for the copilot provider and will be ignored.')
+      }
+      const { CopilotAdapter } = await import('./copilot.js')
+      return new CopilotAdapter(apiKey)
+    }
+    case 'gemini': {
+      const { GeminiAdapter } = await import('./gemini.js')
+      return new GeminiAdapter(apiKey)
     }
     case 'openai': {
       const { OpenAIAdapter } = await import('./openai.js')
-      return new OpenAIAdapter(apiKey)
+      return new OpenAIAdapter(apiKey, baseURL)
+    }
+    case 'grok': {
+      const { GrokAdapter } = await import('./grok.js')
+      return new GrokAdapter(apiKey, baseURL)
     }
     default: {
       // The `never` cast here makes TypeScript enforce exhaustiveness.

package/src/llm/anthropic.ts

@@ -189,9 +189,10 @@ export class AnthropicAdapter implements LLMAdapter {
 
   readonly #client: Anthropic
 
-  constructor(apiKey?: string) {
+  constructor(apiKey?: string, baseURL?: string) {
     this.#client = new Anthropic({
       apiKey: apiKey ?? process.env['ANTHROPIC_API_KEY'],
+      baseURL,
     })
   }