@jackchen_me/open-multi-agent 0.2.0 → 1.0.0

package/dist/tool/text-tool-extractor.js

@@ -0,0 +1,187 @@
+/**
+ * @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.
+ */
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+let callCounter = 0;
+/** Generate a unique tool-call ID for extracted calls. */
+function generateToolCallId() {
+    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, knownToolNames) {
+    if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+        return null;
+    }
+    const obj = json;
+    // Shape: { function: { name, arguments } }
+    if (typeof obj['function'] === 'object' && obj['function'] !== null) {
+        const fn = obj['function'];
+        return parseFlat(fn, knownToolNames);
+    }
+    // Shape: { name, arguments|parameters }
+    return parseFlat(obj, knownToolNames);
+}
+function parseFlat(obj, knownToolNames) {
+    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 = {};
+    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;
+                }
+            }
+            catch {
+                // Malformed — use empty input
+            }
+        }
+        else if (typeof args === 'object' && !Array.isArray(args)) {
+            input = args;
+        }
+    }
+    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) {
+    const results = [];
+    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, knownToolNames) {
+    const results = [];
+    for (const match of text.matchAll(/<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/g)) {
+        const inner = match[1].trim();
+        try {
+            const parsed = 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, knownToolNames) {
+    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 = [];
+    for (const obj of jsonObjects) {
+        const block = parseToolCallJSON(obj, nameSet);
+        if (block !== null)
+            results.push(block);
+    }
+    return results;
+}
+//# sourceMappingURL=text-tool-extractor.js.map

package/dist/tool/text-tool-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-tool-extractor.js","sourceRoot":"","sources":["../../src/tool/text-tool-extractor.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -72,7 +72,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;
 }
 /** The serialisable tool schema sent to the LLM provider. */
@@ -145,11 +145,18 @@ export interface ToolDefinition<TInput = Record<string, unknown>> {
     readonly inputSchema: ZodSchema<TInput>;
     execute(input: TInput, context: ToolUseContext): Promise<ToolResult>;
 }
+/** 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' | 'copilot' | '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
@@ -164,12 +171,64 @@ export interface AgentConfig {
     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;
+}
+/** 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. */
 export interface AgentState {
@@ -199,6 +258,8 @@ export interface AgentRunResult {
      * failed after retry.
      */
     readonly structured?: unknown;
+    /** True when the run was terminated or warned due to loop detection. */
+    readonly loopDetected?: boolean;
 }
 /** Static configuration for a team of cooperating agents. */
 export interface TeamConfig {
@@ -215,7 +276,7 @@ export interface TeamRunResult {
     readonly totalTokenUsage: TokenUsage;
 }
 /** 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 {
     readonly id: string;
@@ -236,9 +297,14 @@ export interface Task {
     /** Exponential backoff multiplier (default: 2). */
     readonly retryBackoff?: number;
 }
-/** 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_retry' | 'message' | 'error';
+    readonly type: 'agent_start' | 'agent_complete' | 'task_start' | 'task_complete' | 'task_skipped' | 'task_retry' | 'message' | 'error';
     readonly agent?: string;
     readonly task?: string;
     readonly data?: unknown;
@@ -247,11 +313,77 @@ export interface OrchestratorEvent {
 export interface OrchestratorConfig {
     readonly maxConcurrency?: number;
     readonly defaultModel?: string;
-    readonly defaultProvider?: 'anthropic' | 'copilot' | 'openai';
+    readonly defaultProvider?: 'anthropic' | 'copilot' | 'grok' | 'openai' | 'gemini';
     readonly defaultBaseURL?: string;
     readonly defaultApiKey?: string;
-    onProgress?: (event: OrchestratorEvent) => void;
+    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 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;
 /** A single key-value record stored in a {@link MemoryStore}. */
 export interface MemoryEntry {
     readonly key: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/trace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Trace emission utilities for the observability layer.
+ */
+import type { TraceEvent } from '../types.js';
+/**
+ * Safely emit a trace event. Swallows callback errors so a broken
+ * subscriber never crashes agent execution.
+ */
+export declare function emitTrace(fn: ((event: TraceEvent) => void | Promise<void>) | undefined, event: TraceEvent): void;
+/** Generate a unique run ID for trace correlation. */
+export declare function generateRunId(): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/utils/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/utils/trace.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;GAGG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EAC7D,KAAK,EAAE,UAAU,GAChB,IAAI,CAYN;AAID,sDAAsD;AACtD,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/utils/trace.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Trace emission utilities for the observability layer.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Safely emit a trace event. Swallows callback errors so a broken
+ * subscriber never crashes agent execution.
+ */
+export function emitTrace(fn, event) {
+    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);
+        if (result && typeof result.catch === 'function') {
+            ;
+            result.catch(noop);
+        }
+    }
+    catch {
+        // Intentionally swallowed — observability must never break execution.
+    }
+}
+function noop() { }
+/** Generate a unique run ID for trace correlation. */
+export function generateRunId() {
+    return randomUUID();
+}
+//# sourceMappingURL=trace.js.map

package/dist/utils/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/utils/trace.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,EAA6D,EAC7D,KAAiB;IAEjB,IAAI,CAAC,EAAE;QAAE,OAAM;IACf,IAAI,CAAC;QACH,wEAAwE;QACxE,qEAAqE;QACrE,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAY,CAAA;QACnC,IAAI,MAAM,IAAI,OAAQ,MAA2B,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACvE,CAAC;YAAC,MAA2B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;AACH,CAAC;AAED,SAAS,IAAI,KAAI,CAAC;AAElB,sDAAsD;AACtD,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,EAAE,CAAA;AACrB,CAAC"}

package/examples/06-local-model.ts

@@ -64,6 +64,7 @@ Your review MUST include these sections:
 Be specific and constructive. Reference line numbers or function names when possible.`,
   tools: ['file_read'],
   maxTurns: 4,
+  timeoutMs: 120_000, // 2 min — local models can be slow
 }
 
 // ---------------------------------------------------------------------------