@jackchen_me/open-multi-agent 0.2.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/index.ts

@@ -63,6 +63,7 @@ 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'
@@ -147,7 +148,10 @@ export type {
   AgentConfig,
   AgentState,
   AgentRunResult,
+  BeforeRunHookContext,
   ToolCallRecord,
+  LoopDetectionConfig,
+  LoopDetectionInfo,
 
   // Team
   TeamConfig,
@@ -161,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,7 +38,7 @@ import type { LLMAdapter } from '../types.js'
  * Additional providers can be integrated by implementing {@link LLMAdapter}
  * directly and bypassing this factory.
  */
-export type SupportedProvider = 'anthropic' | 'copilot' | 'openai'
+export type SupportedProvider = 'anthropic' | 'copilot' | 'grok' | 'openai' | 'gemini'
 
 /**
  * Instantiate the appropriate {@link LLMAdapter} for the given provider.
@@ -46,6 +47,8 @@ export type SupportedProvider = 'anthropic' | 'copilot' | 'openai'
  * 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
  *
@@ -74,10 +77,18 @@ export async function createAdapter(
       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, baseURL)
     }
+    case 'grok': {
+      const { GrokAdapter } = await import('./grok.js')
+      return new GrokAdapter(apiKey, baseURL)
+    }
     default: {
       // The `never` cast here makes TypeScript enforce exhaustiveness.
       const _exhaustive: never = provider

package/src/llm/copilot.ts

@@ -313,7 +313,8 @@ export class CopilotAdapter implements LLMAdapter {
       },
     )
 
-    return fromOpenAICompletion(completion)
+    const toolNames = options.tools?.map(t => t.name)
+    return fromOpenAICompletion(completion, toolNames)
   }
 
   // -------------------------------------------------------------------------