@jackchen_me/open-multi-agent 0.1.0 → 0.2.0

package/src/orchestrator/orchestrator.ts

@@ -92,6 +92,104 @@ function buildAgent(config: AgentConfig): Agent {
   return new Agent(config, registry, executor)
 }
 
+/** Promise-based delay. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/** Maximum delay cap to prevent runaway exponential backoff (30 seconds). */
+const MAX_RETRY_DELAY_MS = 30_000
+
+/**
+ * Compute the retry delay for a given attempt, capped at {@link MAX_RETRY_DELAY_MS}.
+ */
+export function computeRetryDelay(
+  baseDelay: number,
+  backoff: number,
+  attempt: number,
+): number {
+  return Math.min(baseDelay * backoff ** (attempt - 1), MAX_RETRY_DELAY_MS)
+}
+
+/**
+ * Execute an agent task with optional retry and exponential backoff.
+ *
+ * Exported for testability — called internally by {@link executeQueue}.
+ *
+ * @param run      - The function that executes the task (typically `pool.run`).
+ * @param task     - The task to execute (retry config read from its fields).
+ * @param onRetry  - Called before each retry sleep with event data.
+ * @param delayFn  - Injectable delay function (defaults to real `sleep`).
+ * @returns The final {@link AgentRunResult} from the last attempt.
+ */
+export async function executeWithRetry(
+  run: () => Promise<AgentRunResult>,
+  task: Task,
+  onRetry?: (data: { attempt: number; maxAttempts: number; error: string; nextDelayMs: number }) => void,
+  delayFn: (ms: number) => Promise<void> = sleep,
+): Promise<AgentRunResult> {
+  const maxAttempts = Math.max(0, task.maxRetries ?? 0) + 1
+  const baseDelay = Math.max(0, task.retryDelayMs ?? 1000)
+  const backoff = Math.max(1, task.retryBackoff ?? 2)
+
+  let lastError: string = ''
+  // Accumulate token usage across all attempts so billing/observability
+  // reflects the true cost of retries.
+  let totalUsage: TokenUsage = { input_tokens: 0, output_tokens: 0 }
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const result = await run()
+      totalUsage = {
+        input_tokens: totalUsage.input_tokens + result.tokenUsage.input_tokens,
+        output_tokens: totalUsage.output_tokens + result.tokenUsage.output_tokens,
+      }
+
+      if (result.success) {
+        return { ...result, tokenUsage: totalUsage }
+      }
+      lastError = result.output
+
+      // Failure — retry or give up
+      if (attempt < maxAttempts) {
+        const delay = computeRetryDelay(baseDelay, backoff, attempt)
+        onRetry?.({ attempt, maxAttempts, error: lastError, nextDelayMs: delay })
+        await delayFn(delay)
+        continue
+      }
+
+      return { ...result, tokenUsage: totalUsage }
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err)
+
+      if (attempt < maxAttempts) {
+        const delay = computeRetryDelay(baseDelay, backoff, attempt)
+        onRetry?.({ attempt, maxAttempts, error: lastError, nextDelayMs: delay })
+        await delayFn(delay)
+        continue
+      }
+
+      // All retries exhausted — return a failure result
+      return {
+        success: false,
+        output: lastError,
+        messages: [],
+        tokenUsage: totalUsage,
+        toolCalls: [],
+      }
+    }
+  }
+
+  // Should not be reached, but TypeScript needs a return
+  return {
+    success: false,
+    output: lastError,
+    messages: [],
+    tokenUsage: totalUsage,
+    toolCalls: [],
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Parsed task spec (result of coordinator decomposition)
 // ---------------------------------------------------------------------------
@@ -239,49 +337,50 @@ async function executeQueue(
       // Build the prompt: inject shared memory context + task description
       const prompt = await buildTaskPrompt(task, team)
 
-      try {
-        const result = await pool.run(assignee, prompt)
-        ctx.agentResults.set(`${assignee}:${task.id}`, result)
-
-        if (result.success) {
-          // Persist result into shared memory so other agents can read it
-          const sharedMem = team.getSharedMemoryInstance()
-          if (sharedMem) {
-            await sharedMem.write(assignee, `task:${task.id}:result`, result.output)
-          }
-
-          queue.complete(task.id, result.output)
-
+      const result = await executeWithRetry(
+        () => pool.run(assignee, prompt),
+        task,
+        (retryData) => {
           config.onProgress?.({
-            type: 'task_complete',
+            type: 'task_retry',
             task: task.id,
             agent: assignee,
-            data: result,
+            data: retryData,
           } satisfies OrchestratorEvent)
+        },
+      )
 
-          config.onProgress?.({
-            type: 'agent_complete',
-            agent: assignee,
-            task: task.id,
-            data: result,
-          } satisfies OrchestratorEvent)
-        } else {
-          queue.fail(task.id, result.output)
-          config.onProgress?.({
-            type: 'error',
-            task: task.id,
-            agent: assignee,
-            data: result,
-          } satisfies OrchestratorEvent)
+      ctx.agentResults.set(`${assignee}:${task.id}`, result)
+
+      if (result.success) {
+        // Persist result into shared memory so other agents can read it
+        const sharedMem = team.getSharedMemoryInstance()
+        if (sharedMem) {
+          await sharedMem.write(assignee, `task:${task.id}:result`, result.output)
         }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err)
-        queue.fail(task.id, message)
+
+        queue.complete(task.id, result.output)
+
+        config.onProgress?.({
+          type: 'task_complete',
+          task: task.id,
+          agent: assignee,
+          data: result,
+        } satisfies OrchestratorEvent)
+
+        config.onProgress?.({
+          type: 'agent_complete',
+          agent: assignee,
+          task: task.id,
+          data: result,
+        } satisfies OrchestratorEvent)
+      } else {
+        queue.fail(task.id, result.output)
         config.onProgress?.({
           type: 'error',
           task: task.id,
           agent: assignee,
-          data: err,
+          data: result,
         } satisfies OrchestratorEvent)
       }
     })
@@ -341,8 +440,8 @@ async function buildTaskPrompt(task: Task, team: Team): Promise<string> {
  */
 export class OpenMultiAgent {
   private readonly config: Required<
-    Omit<OrchestratorConfig, 'onProgress'>
-  > & Pick<OrchestratorConfig, 'onProgress'>
+    Omit<OrchestratorConfig, 'onProgress' | 'defaultBaseURL' | 'defaultApiKey'>
+  > & Pick<OrchestratorConfig, 'onProgress' | 'defaultBaseURL' | 'defaultApiKey'>
 
   private readonly teams: Map<string, Team> = new Map()
   private completedTaskCount = 0
@@ -360,6 +459,8 @@ export class OpenMultiAgent {
       maxConcurrency: config.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
       defaultModel: config.defaultModel ?? DEFAULT_MODEL,
       defaultProvider: config.defaultProvider ?? 'anthropic',
+      defaultBaseURL: config.defaultBaseURL,
+      defaultApiKey: config.defaultApiKey,
       onProgress: config.onProgress,
     }
   }
@@ -405,7 +506,13 @@ export class OpenMultiAgent {
    * @param prompt - The user prompt to send.
    */
   async runAgent(config: AgentConfig, prompt: string): Promise<AgentRunResult> {
-    const agent = buildAgent(config)
+    const effective: AgentConfig = {
+      ...config,
+      provider: config.provider ?? this.config.defaultProvider,
+      baseURL: config.baseURL ?? this.config.defaultBaseURL,
+      apiKey: config.apiKey ?? this.config.defaultApiKey,
+    }
+    const agent = buildAgent(effective)
     this.config.onProgress?.({
       type: 'agent_start',
       agent: config.name,
@@ -462,6 +569,8 @@ export class OpenMultiAgent {
       name: 'coordinator',
       model: this.config.defaultModel,
       provider: this.config.defaultProvider,
+      baseURL: this.config.defaultBaseURL,
+      apiKey: this.config.defaultApiKey,
       systemPrompt: this.buildCoordinatorSystemPrompt(agentConfigs),
       maxTurns: 3,
     }
@@ -564,6 +673,9 @@ export class OpenMultiAgent {
       description: string
       assignee?: string
       dependsOn?: string[]
+      maxRetries?: number
+      retryDelayMs?: number
+      retryBackoff?: number
     }>,
   ): Promise<TeamRunResult> {
     const agentConfigs = team.getAgents()
@@ -576,6 +688,9 @@ export class OpenMultiAgent {
         description: t.description,
         assignee: t.assignee,
         dependsOn: t.dependsOn,
+        maxRetries: t.maxRetries,
+        retryDelayMs: t.retryDelayMs,
+        retryBackoff: t.retryBackoff,
       })),
       agentConfigs,
       queue,
@@ -733,7 +848,11 @@ export class OpenMultiAgent {
    * then resolving them to real IDs before adding tasks to the queue.
    */
   private loadSpecsIntoQueue(
-    specs: ReadonlyArray<ParsedTaskSpec>,
+    specs: ReadonlyArray<ParsedTaskSpec & {
+      maxRetries?: number
+      retryDelayMs?: number
+      retryBackoff?: number
+    }>,
     agentConfigs: AgentConfig[],
     queue: TaskQueue,
   ): void {
@@ -750,6 +869,9 @@ export class OpenMultiAgent {
         assignee: spec.assignee && agentNames.has(spec.assignee)
           ? spec.assignee
           : undefined,
+        maxRetries: spec.maxRetries,
+        retryDelayMs: spec.retryDelayMs,
+        retryBackoff: spec.retryBackoff,
       })
       titleToId.set(spec.title.toLowerCase().trim(), task.id)
       createdTasks.push(task)
@@ -792,6 +914,8 @@ export class OpenMultiAgent {
         ...config,
         model: config.model,
         provider: config.provider ?? this.config.defaultProvider,
+        baseURL: config.baseURL ?? this.config.defaultBaseURL,
+        apiKey: config.apiKey ?? this.config.defaultApiKey,
       }
       pool.add(buildAgent(effective))
     }
@@ -825,13 +949,15 @@ export class OpenMultiAgent {
       if (!existing) {
         collapsed.set(agentName, result)
       } else {
-        // Merge multiple results for the same agent (multi-task case)
+        // Merge multiple results for the same agent (multi-task case).
+        // Keep the latest `structured` value (last completed task wins).
         collapsed.set(agentName, {
           success: existing.success && result.success,
           output: [existing.output, result.output].filter(Boolean).join('\n\n---\n\n'),
           messages: [...existing.messages, ...result.messages],
           tokenUsage: addUsage(existing.tokenUsage, result.tokenUsage),
           toolCalls: [...existing.toolCalls, ...result.toolCalls],
+          structured: result.structured !== undefined ? result.structured : existing.structured,
         })
       }
 

package/src/task/queue.ts

@@ -356,7 +356,7 @@ export class TaskQueue {
 
       // Re-check against the current state of the whole task set.
       // Pass the pre-built map to avoid rebuilding it for every candidate task.
-      if (isTaskReady(task, allTasks, taskById)) {
+      if (isTaskReady({ ...task, status: 'pending' }, allTasks, taskById)) {
         const unblocked: Task = {
           ...task,
           status: 'pending',

package/src/task/task.ts

@@ -6,6 +6,7 @@
  * Stateful orchestration belongs in {@link TaskQueue}.
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Task, TaskStatus } from '../types.js'
 
 // ---------------------------------------------------------------------------
@@ -30,10 +31,13 @@ export function createTask(input: {
   description: string
   assignee?: string
   dependsOn?: string[]
+  maxRetries?: number
+  retryDelayMs?: number
+  retryBackoff?: number
 }): Task {
   const now = new Date()
   return {
-    id: crypto.randomUUID(),
+    id: randomUUID(),
     title: input.title,
     description: input.description,
     status: 'pending' as TaskStatus,
@@ -42,6 +46,9 @@ export function createTask(input: {
     result: undefined,
     createdAt: now,
     updatedAt: now,
+    maxRetries: input.maxRetries,
+    retryDelayMs: input.retryDelayMs,
+    retryBackoff: input.retryBackoff,
   }
 }
 

package/src/team/messaging.ts

@@ -6,6 +6,8 @@
  * for replay and audit; read-state is tracked per recipient.
  */
 
+import { randomUUID } from 'node:crypto'
+
 // ---------------------------------------------------------------------------
 // Message type
 // ---------------------------------------------------------------------------
@@ -93,7 +95,7 @@ export class MessageBus {
    */
   send(from: string, to: string, content: string): Message {
     const message: Message = {
-      id: crypto.randomUUID(),
+      id: randomUUID(),
       from,
       to,
       content,

package/src/types.ts

@@ -186,13 +186,27 @@ export interface ToolDefinition<TInput = Record<string, unknown>> {
 export interface AgentConfig {
   readonly name: string
   readonly model: string
-  readonly provider?: 'anthropic' | 'openai'
+  readonly provider?: 'anthropic' | 'copilot' | 'openai'
+  /**
+   * 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
+  /**
+   * 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
 }
 
 /** Lifecycle state tracked during an agent run. */
@@ -219,6 +233,12 @@ 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
 }
 
 // ---------------------------------------------------------------------------
@@ -261,6 +281,12 @@ 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
 }
 
 // ---------------------------------------------------------------------------
@@ -274,6 +300,7 @@ export interface OrchestratorEvent {
     | 'agent_complete'
     | 'task_start'
     | 'task_complete'
+    | 'task_retry'
     | 'message'
     | 'error'
   readonly agent?: string
@@ -285,7 +312,9 @@ export interface OrchestratorEvent {
 export interface OrchestratorConfig {
   readonly maxConcurrency?: number
   readonly defaultModel?: string
-  readonly defaultProvider?: 'anthropic' | 'openai'
+  readonly defaultProvider?: 'anthropic' | 'copilot' | 'openai'
+  readonly defaultBaseURL?: string
+  readonly defaultApiKey?: string
   onProgress?: (event: OrchestratorEvent) => void
 }
 

package/tests/semaphore.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { Semaphore } from '../src/utils/semaphore.js'
+
+describe('Semaphore', () => {
+  it('throws on max < 1', () => {
+    expect(() => new Semaphore(0)).toThrow()
+  })
+
+  it('allows up to max concurrent holders', async () => {
+    const sem = new Semaphore(2)
+    let running = 0
+    let peak = 0
+
+    const work = async () => {
+      await sem.acquire()
+      running++
+      peak = Math.max(peak, running)
+      await new Promise((r) => setTimeout(r, 30))
+      running--
+      sem.release()
+    }
+
+    await Promise.all([work(), work(), work(), work()])
+    expect(peak).toBeLessThanOrEqual(2)
+  })
+
+  it('run() auto-releases on success', async () => {
+    const sem = new Semaphore(1)
+    const result = await sem.run(async () => 42)
+    expect(result).toBe(42)
+    expect(sem.active).toBe(0)
+  })
+
+  it('run() auto-releases on error', async () => {
+    const sem = new Semaphore(1)
+    await expect(sem.run(async () => { throw new Error('oops') })).rejects.toThrow('oops')
+    expect(sem.active).toBe(0)
+  })
+
+  it('tracks active and pending counts', async () => {
+    const sem = new Semaphore(1)
+    await sem.acquire()
+    expect(sem.active).toBe(1)
+
+    // This will queue
+    const p = sem.acquire()
+    expect(sem.pending).toBe(1)
+
+    sem.release()
+    await p
+    expect(sem.active).toBe(1)
+    expect(sem.pending).toBe(0)
+
+    sem.release()
+    expect(sem.active).toBe(0)
+  })
+})

package/tests/shared-memory.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest'
+import { SharedMemory } from '../src/memory/shared.js'
+
+describe('SharedMemory', () => {
+  // -------------------------------------------------------------------------
+  // Write & read
+  // -------------------------------------------------------------------------
+
+  it('writes and reads a value under a namespaced key', async () => {
+    const mem = new SharedMemory()
+    await mem.write('researcher', 'findings', 'TS 5.5 ships const type params')
+
+    const entry = await mem.read('researcher/findings')
+    expect(entry).not.toBeNull()
+    expect(entry!.value).toBe('TS 5.5 ships const type params')
+  })
+
+  it('returns null for a non-existent key', async () => {
+    const mem = new SharedMemory()
+    expect(await mem.read('nope/nothing')).toBeNull()
+  })
+
+  // -------------------------------------------------------------------------
+  // Namespace isolation
+  // -------------------------------------------------------------------------
+
+  it('isolates writes between agents', async () => {
+    const mem = new SharedMemory()
+    await mem.write('alice', 'plan', 'plan A')
+    await mem.write('bob', 'plan', 'plan B')
+
+    const alice = await mem.read('alice/plan')
+    const bob = await mem.read('bob/plan')
+    expect(alice!.value).toBe('plan A')
+    expect(bob!.value).toBe('plan B')
+  })
+
+  it('listByAgent returns only that agent\'s entries', async () => {
+    const mem = new SharedMemory()
+    await mem.write('alice', 'a1', 'v1')
+    await mem.write('alice', 'a2', 'v2')
+    await mem.write('bob', 'b1', 'v3')
+
+    const aliceEntries = await mem.listByAgent('alice')
+    expect(aliceEntries).toHaveLength(2)
+    expect(aliceEntries.every((e) => e.key.startsWith('alice/'))).toBe(true)
+  })
+
+  // -------------------------------------------------------------------------
+  // Overwrite
+  // -------------------------------------------------------------------------
+
+  it('overwrites a value and preserves createdAt', async () => {
+    const mem = new SharedMemory()
+    await mem.write('agent', 'key', 'first')
+    const first = await mem.read('agent/key')
+
+    await mem.write('agent', 'key', 'second')
+    const second = await mem.read('agent/key')
+
+    expect(second!.value).toBe('second')
+    expect(second!.createdAt.getTime()).toBe(first!.createdAt.getTime())
+  })
+
+  // -------------------------------------------------------------------------
+  // Metadata
+  // -------------------------------------------------------------------------
+
+  it('stores metadata alongside the value', async () => {
+    const mem = new SharedMemory()
+    await mem.write('agent', 'key', 'val', { priority: 'high' })
+
+    const entry = await mem.read('agent/key')
+    expect(entry!.metadata).toMatchObject({ priority: 'high', agent: 'agent' })
+  })
+
+  // -------------------------------------------------------------------------
+  // Summary
+  // -------------------------------------------------------------------------
+
+  it('returns empty string for an empty store', async () => {
+    const mem = new SharedMemory()
+    expect(await mem.getSummary()).toBe('')
+  })
+
+  it('produces a markdown summary grouped by agent', async () => {
+    const mem = new SharedMemory()
+    await mem.write('researcher', 'findings', 'result A')
+    await mem.write('coder', 'plan', 'implement X')
+
+    const summary = await mem.getSummary()
+    expect(summary).toContain('## Shared Team Memory')
+    expect(summary).toContain('### researcher')
+    expect(summary).toContain('### coder')
+    expect(summary).toContain('findings: result A')
+    expect(summary).toContain('plan: implement X')
+  })
+
+  it('truncates long values in the summary', async () => {
+    const mem = new SharedMemory()
+    const longValue = 'x'.repeat(300)
+    await mem.write('agent', 'big', longValue)
+
+    const summary = await mem.getSummary()
+    // Summary truncates at 200 chars → 197 + '…'
+    expect(summary.length).toBeLessThan(longValue.length)
+    expect(summary).toContain('…')
+  })
+
+  // -------------------------------------------------------------------------
+  // listAll
+  // -------------------------------------------------------------------------
+
+  it('listAll returns entries from all agents', async () => {
+    const mem = new SharedMemory()
+    await mem.write('a', 'k1', 'v1')
+    await mem.write('b', 'k2', 'v2')
+
+    const all = await mem.listAll()
+    expect(all).toHaveLength(2)
+  })
+})