@jackchen_me/open-multi-agent 0.1.0 → 0.2.0

package/examples/09-gemma4-auto-orchestration.ts

@@ -0,0 +1,162 @@
+/**
+ * Example 09 — Gemma 4 Auto-Orchestration (runTeam, 100% Local)
+ *
+ * Demonstrates the framework's key feature — automatic task decomposition —
+ * powered entirely by a local Gemma 4 model. No cloud API needed.
+ *
+ * What happens:
+ * 1. A Gemma 4 "coordinator" receives the goal + agent roster
+ * 2. It outputs a structured JSON task array (title, description, assignee, dependsOn)
+ * 3. The framework resolves dependencies, schedules tasks, and runs agents
+ * 4. The coordinator synthesises all task results into a final answer
+ *
+ * This is the hardest test for a local model — it must produce valid JSON
+ * for task decomposition AND do tool-calling for actual task execution.
+ * Gemma 4 e2b (5.1B params) handles both reliably.
+ *
+ * Run:
+ *   no_proxy=localhost npx tsx examples/09-gemma4-auto-orchestration.ts
+ *
+ * Prerequisites:
+ *   1. Ollama >= 0.20.0 installed and running: https://ollama.com
+ *   2. Pull the model: ollama pull gemma4:e2b
+ *   3. No API keys needed!
+ *
+ * Note: The no_proxy=localhost prefix is needed if you have an HTTP proxy
+ * configured, since the OpenAI SDK would otherwise route Ollama requests
+ * through the proxy.
+ */
+
+import { OpenMultiAgent } from '../src/index.js'
+import type { AgentConfig, OrchestratorEvent, Task } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+// See available tags at https://ollama.com/library/gemma4
+const OLLAMA_MODEL = 'gemma4:e2b'      // or 'gemma4:e4b', 'gemma4:26b'
+const OLLAMA_BASE_URL = 'http://localhost:11434/v1'
+
+// ---------------------------------------------------------------------------
+// Agents — the coordinator is created automatically by runTeam()
+// ---------------------------------------------------------------------------
+
+const researcher: AgentConfig = {
+  name: 'researcher',
+  model: OLLAMA_MODEL,
+  provider: 'openai',
+  baseURL: OLLAMA_BASE_URL,
+  apiKey: 'ollama',
+  systemPrompt: `You are a system researcher. Use bash to run non-destructive,
+read-only commands and report the results concisely.`,
+  tools: ['bash'],
+  maxTurns: 4,
+}
+
+const writer: AgentConfig = {
+  name: 'writer',
+  model: OLLAMA_MODEL,
+  provider: 'openai',
+  baseURL: OLLAMA_BASE_URL,
+  apiKey: 'ollama',
+  systemPrompt: `You are a technical writer. Use file_write to create clear,
+structured Markdown reports based on the information provided.`,
+  tools: ['file_write'],
+  maxTurns: 4,
+}
+
+// ---------------------------------------------------------------------------
+// Progress handler
+// ---------------------------------------------------------------------------
+
+function handleProgress(event: OrchestratorEvent): void {
+  const ts = new Date().toISOString().slice(11, 23)
+  switch (event.type) {
+    case 'task_start': {
+      const task = event.data as Task | undefined
+      console.log(`[${ts}] TASK START    "${task?.title ?? event.task}" → ${task?.assignee ?? '?'}`)
+      break
+    }
+    case 'task_complete':
+      console.log(`[${ts}] TASK DONE     "${event.task}"`)
+      break
+    case 'agent_start':
+      console.log(`[${ts}] AGENT START   ${event.agent}`)
+      break
+    case 'agent_complete':
+      console.log(`[${ts}] AGENT DONE    ${event.agent}`)
+      break
+    case 'error':
+      console.error(`[${ts}] ERROR         ${event.agent ?? ''}  task=${event.task ?? '?'}`)
+      break
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator — defaultModel is used for the coordinator agent
+// ---------------------------------------------------------------------------
+
+const orchestrator = new OpenMultiAgent({
+  defaultModel: OLLAMA_MODEL,
+  defaultProvider: 'openai',
+  defaultBaseURL: OLLAMA_BASE_URL,
+  defaultApiKey: 'ollama',
+  maxConcurrency: 1, // local model serves one request at a time
+  onProgress: handleProgress,
+})
+
+const team = orchestrator.createTeam('gemma4-auto', {
+  name: 'gemma4-auto',
+  agents: [researcher, writer],
+  sharedMemory: true,
+})
+
+// ---------------------------------------------------------------------------
+// Give a goal — the framework handles the rest
+// ---------------------------------------------------------------------------
+
+const goal = `Check this machine's Node.js version, npm version, and OS info,
+then write a short Markdown summary report to /tmp/gemma4-auto/report.md`
+
+console.log('Gemma 4 Auto-Orchestration — Zero API Cost')
+console.log('='.repeat(60))
+console.log(`  model        → ${OLLAMA_MODEL} via Ollama (all agents + coordinator)`)
+console.log(`  researcher   → bash`)
+console.log(`  writer       → file_write`)
+console.log(`  coordinator  → auto-created by runTeam()`)
+console.log()
+console.log(`Goal: ${goal.replace(/\n/g, ' ').trim()}`)
+console.log('='.repeat(60))
+
+const start = Date.now()
+const result = await orchestrator.runTeam(team, goal)
+const totalTime = Date.now() - start
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+console.log('\n' + '='.repeat(60))
+console.log('Pipeline complete.\n')
+console.log(`Overall success: ${result.success}`)
+console.log(`Total time: ${(totalTime / 1000).toFixed(1)}s`)
+console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
+
+console.log('\nPer-agent results:')
+for (const [name, r] of result.agentResults) {
+  const icon = r.success ? 'OK  ' : 'FAIL'
+  const tools = r.toolCalls.length > 0 ? r.toolCalls.map(c => c.toolName).join(', ') : '(none)'
+  console.log(`  [${icon}] ${name.padEnd(24)} tools: ${tools}`)
+}
+
+// Print the coordinator's final synthesis
+const coordResult = result.agentResults.get('coordinator')
+if (coordResult?.success) {
+  console.log('\nFinal synthesis (from local Gemma 4 coordinator):')
+  console.log('-'.repeat(60))
+  console.log(coordResult.output)
+  console.log('-'.repeat(60))
+}
+
+console.log('\nAll processing done locally. $0 API cost.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackchen_me/open-multi-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Production-grade multi-agent orchestration framework. Model-agnostic, supports team collaboration, task scheduling, and inter-agent communication.",
   "type": "module",
   "main": "dist/index.js",
@@ -42,8 +42,9 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.6.0",
-    "vitest": "^2.1.0",
-    "@types/node": "^22.0.0"
+    "vitest": "^2.1.0"
   }
 }

package/src/agent/agent.ts

@@ -35,7 +35,12 @@ import type {
 import type { ToolDefinition as FrameworkToolDefinition, ToolRegistry } from '../tool/framework.js'
 import type { ToolExecutor } from '../tool/executor.js'
 import { createAdapter } from '../llm/adapter.js'
-import { AgentRunner, type RunnerOptions, type RunOptions } from './runner.js'
+import { AgentRunner, type RunnerOptions, type RunOptions, type RunResult } from './runner.js'
+import {
+  buildStructuredOutputInstruction,
+  extractJSON,
+  validateOutput,
+} from './structured-output.js'
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -109,11 +114,20 @@ export class Agent {
     }
 
     const provider = this.config.provider ?? 'anthropic'
-    const adapter = await createAdapter(provider)
+    const adapter = await createAdapter(provider, this.config.apiKey, this.config.baseURL)
+
+    // Append structured-output instructions when an outputSchema is configured.
+    let effectiveSystemPrompt = this.config.systemPrompt
+    if (this.config.outputSchema) {
+      const instruction = buildStructuredOutputInstruction(this.config.outputSchema)
+      effectiveSystemPrompt = effectiveSystemPrompt
+        ? effectiveSystemPrompt + '\n' + instruction
+        : instruction
+    }
 
     const runnerOptions: RunnerOptions = {
       model: this.config.model,
-      systemPrompt: this.config.systemPrompt,
+      systemPrompt: effectiveSystemPrompt,
       maxTurns: this.config.maxTurns,
       maxTokens: this.config.maxTokens,
       temperature: this.config.temperature,
@@ -264,10 +278,19 @@ export class Agent {
       }
 
       const result = await runner.run(messages, runOptions)
-
       this.state.tokenUsage = addUsage(this.state.tokenUsage, result.tokenUsage)
-      this.transitionTo('completed')
 
+      // --- Structured output validation ---
+      if (this.config.outputSchema) {
+        return this.validateStructuredOutput(
+          messages,
+          result,
+          runner,
+          runOptions,
+        )
+      }
+
+      this.transitionTo('completed')
       return this.toAgentRunResult(result, true)
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err))
@@ -279,6 +302,90 @@ export class Agent {
         messages: [],
         tokenUsage: ZERO_USAGE,
         toolCalls: [],
+        structured: undefined,
+      }
+    }
+  }
+
+  /**
+   * Validate agent output against the configured `outputSchema`.
+   * On first validation failure, retry once with error feedback.
+   */
+  private async validateStructuredOutput(
+    originalMessages: LLMMessage[],
+    result: RunResult,
+    runner: AgentRunner,
+    runOptions: RunOptions,
+  ): Promise<AgentRunResult> {
+    const schema = this.config.outputSchema!
+
+    // First attempt
+    let firstAttemptError: unknown
+    try {
+      const parsed = extractJSON(result.output)
+      const validated = validateOutput(schema, parsed)
+      this.transitionTo('completed')
+      return this.toAgentRunResult(result, true, validated)
+    } catch (e) {
+      firstAttemptError = e
+    }
+
+    // Retry: send full context + error feedback
+    const errorMsg = firstAttemptError instanceof Error
+      ? firstAttemptError.message
+      : String(firstAttemptError)
+
+    const errorFeedbackMessage: LLMMessage = {
+      role: 'user' as const,
+      content: [{
+        type: 'text' as const,
+        text: [
+          'Your previous response did not produce valid JSON matching the required schema.',
+          '',
+          `Error: ${errorMsg}`,
+          '',
+          'Please try again. Respond with ONLY valid JSON, no other text.',
+        ].join('\n'),
+      }],
+    }
+
+    const retryMessages: LLMMessage[] = [
+      ...originalMessages,
+      ...result.messages,
+      errorFeedbackMessage,
+    ]
+
+    const retryResult = await runner.run(retryMessages, runOptions)
+    this.state.tokenUsage = addUsage(this.state.tokenUsage, retryResult.tokenUsage)
+
+    const mergedTokenUsage = addUsage(result.tokenUsage, retryResult.tokenUsage)
+    // Include the error feedback turn to maintain alternating user/assistant roles,
+    // which is required by Anthropic's API for subsequent prompt() calls.
+    const mergedMessages = [...result.messages, errorFeedbackMessage, ...retryResult.messages]
+    const mergedToolCalls = [...result.toolCalls, ...retryResult.toolCalls]
+
+    try {
+      const parsed = extractJSON(retryResult.output)
+      const validated = validateOutput(schema, parsed)
+      this.transitionTo('completed')
+      return {
+        success: true,
+        output: retryResult.output,
+        messages: mergedMessages,
+        tokenUsage: mergedTokenUsage,
+        toolCalls: mergedToolCalls,
+        structured: validated,
+      }
+    } catch {
+      // Retry also failed
+      this.transitionTo('completed')
+      return {
+        success: false,
+        output: retryResult.output,
+        messages: mergedMessages,
+        tokenUsage: mergedTokenUsage,
+        toolCalls: mergedToolCalls,
+        structured: undefined,
       }
     }
   }
@@ -331,8 +438,9 @@ export class Agent {
   // -------------------------------------------------------------------------
 
   private toAgentRunResult(
-    result: import('./runner.js').RunResult,
+    result: RunResult,
     success: boolean,
+    structured?: unknown,
   ): AgentRunResult {
     return {
       success,
@@ -340,6 +448,7 @@ export class Agent {
       messages: result.messages,
       tokenUsage: result.tokenUsage,
       toolCalls: result.toolCalls,
+      structured,
     }
   }
 

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,7 @@ export type { SchedulingStrategy } from './orchestrator/scheduler.js'
 // ---------------------------------------------------------------------------
 
 export { Agent } from './agent/agent.js'
+export { buildStructuredOutputInstruction, extractJSON, validateOutput } from './agent/structured-output.js'
 export { AgentPool, Semaphore } from './agent/pool.js'
 export type { PoolStatus } from './agent/pool.js'
 

package/src/llm/adapter.ts

@@ -37,33 +37,46 @@ 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' | 'openai'
 
 /**
  * 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`
+ * - `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 'openai': {
       const { OpenAIAdapter } = await import('./openai.js')
-      return new OpenAIAdapter(apiKey)
+      return new OpenAIAdapter(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,
     })
   }