@jackchen_me/open-multi-agent 0.1.0 → 1.0.0

package/tests/orchestrator.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { OpenMultiAgent } from '../src/orchestrator/orchestrator.js'
+import type {
+  AgentConfig,
+  AgentRunResult,
+  LLMAdapter,
+  LLMChatOptions,
+  LLMMessage,
+  LLMResponse,
+  OrchestratorEvent,
+  TeamConfig,
+} from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Mock LLM adapter
+// ---------------------------------------------------------------------------
+
+/** A controllable fake LLM adapter for orchestrator tests. */
+function createMockAdapter(responses: string[]): LLMAdapter {
+  let callIndex = 0
+  return {
+    name: 'mock',
+    async chat(_msgs: LLMMessage[], options: LLMChatOptions): Promise<LLMResponse> {
+      const text = responses[callIndex] ?? 'no response configured'
+      callIndex++
+      return {
+        id: `resp-${callIndex}`,
+        content: [{ type: 'text', text }],
+        model: options.model,
+        stop_reason: 'end_turn',
+        usage: { input_tokens: 10, output_tokens: 20 },
+      }
+    },
+    async *stream() {
+      yield { type: 'done' as const, data: {} }
+    },
+  }
+}
+
+/**
+ * Mock the createAdapter factory to return our mock adapter.
+ * We need to do this at the module level because Agent calls createAdapter internally.
+ */
+let mockAdapterResponses: string[] = []
+
+vi.mock('../src/llm/adapter.js', () => ({
+  createAdapter: async () => {
+    let callIndex = 0
+    return {
+      name: 'mock',
+      async chat(_msgs: LLMMessage[], options: LLMChatOptions): Promise<LLMResponse> {
+        const text = mockAdapterResponses[callIndex] ?? 'default mock response'
+        callIndex++
+        return {
+          id: `resp-${callIndex}`,
+          content: [{ type: 'text', text }],
+          model: options.model ?? 'mock-model',
+          stop_reason: 'end_turn',
+          usage: { input_tokens: 10, output_tokens: 20 },
+        }
+      },
+      async *stream() {
+        yield { type: 'done' as const, data: {} }
+      },
+    }
+  },
+}))
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function agentConfig(name: string): AgentConfig {
+  return {
+    name,
+    model: 'mock-model',
+    provider: 'openai',
+    systemPrompt: `You are ${name}.`,
+  }
+}
+
+function teamCfg(agents?: AgentConfig[]): TeamConfig {
+  return {
+    name: 'test-team',
+    agents: agents ?? [agentConfig('worker-a'), agentConfig('worker-b')],
+    sharedMemory: true,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('OpenMultiAgent', () => {
+  beforeEach(() => {
+    mockAdapterResponses = []
+  })
+
+  describe('createTeam', () => {
+    it('creates and registers a team', () => {
+      const oma = new OpenMultiAgent()
+      const team = oma.createTeam('my-team', teamCfg())
+      expect(team.name).toBe('test-team')
+      expect(oma.getStatus().teams).toBe(1)
+    })
+
+    it('throws on duplicate team name', () => {
+      const oma = new OpenMultiAgent()
+      oma.createTeam('my-team', teamCfg())
+      expect(() => oma.createTeam('my-team', teamCfg())).toThrow('already exists')
+    })
+  })
+
+  describe('shutdown', () => {
+    it('clears teams and counters', async () => {
+      const oma = new OpenMultiAgent()
+      oma.createTeam('t1', teamCfg())
+      await oma.shutdown()
+      expect(oma.getStatus().teams).toBe(0)
+      expect(oma.getStatus().completedTasks).toBe(0)
+    })
+  })
+
+  describe('getStatus', () => {
+    it('reports initial state', () => {
+      const oma = new OpenMultiAgent()
+      const status = oma.getStatus()
+      expect(status).toEqual({ teams: 0, activeAgents: 0, completedTasks: 0 })
+    })
+  })
+
+  describe('runAgent', () => {
+    it('runs a single agent and returns result', async () => {
+      mockAdapterResponses = ['Hello from agent!']
+
+      const oma = new OpenMultiAgent({ defaultModel: 'mock-model' })
+      const result = await oma.runAgent(
+        agentConfig('solo'),
+        'Say hello',
+      )
+
+      expect(result.success).toBe(true)
+      expect(result.output).toBe('Hello from agent!')
+      expect(oma.getStatus().completedTasks).toBe(1)
+    })
+
+    it('fires onProgress events', async () => {
+      mockAdapterResponses = ['done']
+
+      const events: OrchestratorEvent[] = []
+      const oma = new OpenMultiAgent({
+        defaultModel: 'mock-model',
+        onProgress: (e) => events.push(e),
+      })
+
+      await oma.runAgent(agentConfig('solo'), 'test')
+
+      const types = events.map(e => e.type)
+      expect(types).toContain('agent_start')
+      expect(types).toContain('agent_complete')
+    })
+  })
+
+  describe('runTasks', () => {
+    it('executes explicit tasks assigned to agents', async () => {
+      // Each agent run produces one LLM call
+      mockAdapterResponses = ['result-a', 'result-b']
+
+      const events: OrchestratorEvent[] = []
+      const oma = new OpenMultiAgent({
+        defaultModel: 'mock-model',
+        onProgress: (e) => events.push(e),
+      })
+      const team = oma.createTeam('t', teamCfg())
+
+      const result = await oma.runTasks(team, [
+        { title: 'Task A', description: 'Do A', assignee: 'worker-a' },
+        { title: 'Task B', description: 'Do B', assignee: 'worker-b' },
+      ])
+
+      expect(result.success).toBe(true)
+      expect(result.agentResults.size).toBeGreaterThanOrEqual(1)
+    })
+
+    it('handles task dependencies sequentially', async () => {
+      mockAdapterResponses = ['first done', 'second done']
+
+      const oma = new OpenMultiAgent({ defaultModel: 'mock-model' })
+      const team = oma.createTeam('t', teamCfg())
+
+      const result = await oma.runTasks(team, [
+        { title: 'First', description: 'Do first', assignee: 'worker-a' },
+        { title: 'Second', description: 'Do second', assignee: 'worker-b', dependsOn: ['First'] },
+      ])
+
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('runTeam', () => {
+    it('runs coordinator decomposition + execution + synthesis', async () => {
+      // Response 1: coordinator decomposition (returns JSON task array)
+      // Response 2: worker-a executes task
+      // Response 3: coordinator synthesis
+      mockAdapterResponses = [
+        '```json\n[{"title": "Research", "description": "Research the topic", "assignee": "worker-a"}]\n```',
+        'Research results here',
+        'Final synthesized answer based on research results',
+      ]
+
+      const events: OrchestratorEvent[] = []
+      const oma = new OpenMultiAgent({
+        defaultModel: 'mock-model',
+        onProgress: (e) => events.push(e),
+      })
+      const team = oma.createTeam('t', teamCfg())
+
+      const result = await oma.runTeam(team, 'Research AI safety')
+
+      expect(result.success).toBe(true)
+      // Should have coordinator result
+      expect(result.agentResults.has('coordinator')).toBe(true)
+    })
+
+    it('falls back to one-task-per-agent when coordinator output is unparseable', async () => {
+      mockAdapterResponses = [
+        'I cannot produce JSON output', // invalid coordinator output
+        'worker-a result',
+        'worker-b result',
+        'synthesis',
+      ]
+
+      const oma = new OpenMultiAgent({ defaultModel: 'mock-model' })
+      const team = oma.createTeam('t', teamCfg())
+
+      const result = await oma.runTeam(team, 'Do something')
+
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('config defaults', () => {
+    it('uses default model and provider', () => {
+      const oma = new OpenMultiAgent()
+      const status = oma.getStatus()
+      expect(status).toBeDefined()
+    })
+
+    it('accepts custom config', () => {
+      const oma = new OpenMultiAgent({
+        maxConcurrency: 3,
+        defaultModel: 'custom-model',
+        defaultProvider: 'openai',
+      })
+      expect(oma.getStatus().teams).toBe(0)
+    })
+  })
+
+  describe('onApproval gate', () => {
+    it('skips remaining tasks when approval rejects', async () => {
+      mockAdapterResponses = ['first done', 'should not run']
+
+      const oma = new OpenMultiAgent({
+        defaultModel: 'mock-model',
+        onApproval: async () => false, // reject all
+      })
+      const team = oma.createTeam('t', teamCfg([agentConfig('worker')]))
+
+      const result = await oma.runTasks(team, [
+        { title: 'First', description: 'Do first', assignee: 'worker' },
+        { title: 'Second', description: 'Do second', assignee: 'worker', dependsOn: ['First'] },
+      ])
+
+      // The first task succeeded; the second was skipped (no agentResult entry).
+      // Overall success is based on agentResults only, so it's true.
+      expect(result.success).toBe(true)
+      // But we should have fewer agent results than tasks
+      expect(result.agentResults.size).toBeLessThanOrEqual(1)
+    })
+  })
+})

package/tests/scheduler.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect } from 'vitest'
+import { Scheduler } from '../src/orchestrator/scheduler.js'
+import { TaskQueue } from '../src/task/queue.js'
+import { createTask } from '../src/task/task.js'
+import type { AgentConfig, Task } from '../src/types.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function agent(name: string, systemPrompt?: string): AgentConfig {
+  return { name, model: 'test-model', systemPrompt }
+}
+
+function pendingTask(title: string, opts?: { assignee?: string; dependsOn?: string[] }): Task {
+  return createTask({ title, description: title, assignee: opts?.assignee, ...opts })
+}
+
+// ---------------------------------------------------------------------------
+// round-robin
+// ---------------------------------------------------------------------------
+
+describe('Scheduler: round-robin', () => {
+  it('distributes tasks evenly across agents', () => {
+    const s = new Scheduler('round-robin')
+    const agents = [agent('a'), agent('b'), agent('c')]
+    const tasks = [
+      pendingTask('t1'),
+      pendingTask('t2'),
+      pendingTask('t3'),
+      pendingTask('t4'),
+      pendingTask('t5'),
+      pendingTask('t6'),
+    ]
+
+    const assignments = s.schedule(tasks, agents)
+
+    expect(assignments.get(tasks[0]!.id)).toBe('a')
+    expect(assignments.get(tasks[1]!.id)).toBe('b')
+    expect(assignments.get(tasks[2]!.id)).toBe('c')
+    expect(assignments.get(tasks[3]!.id)).toBe('a')
+    expect(assignments.get(tasks[4]!.id)).toBe('b')
+    expect(assignments.get(tasks[5]!.id)).toBe('c')
+  })
+
+  it('skips already-assigned tasks', () => {
+    const s = new Scheduler('round-robin')
+    const agents = [agent('a'), agent('b')]
+    const tasks = [
+      pendingTask('t1', { assignee: 'a' }),
+      pendingTask('t2'),
+    ]
+
+    const assignments = s.schedule(tasks, agents)
+
+    // Only t2 should be assigned
+    expect(assignments.size).toBe(1)
+    expect(assignments.has(tasks[1]!.id)).toBe(true)
+  })
+
+  it('returns empty map when no agents', () => {
+    const s = new Scheduler('round-robin')
+    const tasks = [pendingTask('t1')]
+    expect(s.schedule(tasks, []).size).toBe(0)
+  })
+
+  it('cursor advances across calls', () => {
+    const s = new Scheduler('round-robin')
+    const agents = [agent('a'), agent('b')]
+    const t1 = [pendingTask('t1')]
+    const t2 = [pendingTask('t2')]
+
+    const a1 = s.schedule(t1, agents)
+    const a2 = s.schedule(t2, agents)
+
+    expect(a1.get(t1[0]!.id)).toBe('a')
+    expect(a2.get(t2[0]!.id)).toBe('b')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// least-busy
+// ---------------------------------------------------------------------------
+
+describe('Scheduler: least-busy', () => {
+  it('assigns to agent with fewest in_progress tasks', () => {
+    const s = new Scheduler('least-busy')
+    const agents = [agent('a'), agent('b')]
+
+    // Create some in-progress tasks for agent 'a'
+    const inProgress: Task = {
+      ...pendingTask('busy'),
+      status: 'in_progress',
+      assignee: 'a',
+    }
+    const newTask = pendingTask('new')
+    const allTasks = [inProgress, newTask]
+
+    const assignments = s.schedule(allTasks, agents)
+
+    // 'b' has 0 in-progress, 'a' has 1 → assign to 'b'
+    expect(assignments.get(newTask.id)).toBe('b')
+  })
+
+  it('balances load across batch', () => {
+    const s = new Scheduler('least-busy')
+    const agents = [agent('a'), agent('b')]
+    const tasks = [pendingTask('t1'), pendingTask('t2'), pendingTask('t3'), pendingTask('t4')]
+
+    const assignments = s.schedule(tasks, agents)
+
+    // Should alternate: a, b, a, b
+    const values = [...assignments.values()]
+    const aCount = values.filter(v => v === 'a').length
+    const bCount = values.filter(v => v === 'b').length
+    expect(aCount).toBe(2)
+    expect(bCount).toBe(2)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// capability-match
+// ---------------------------------------------------------------------------
+
+describe('Scheduler: capability-match', () => {
+  it('matches task keywords to agent system prompt', () => {
+    const s = new Scheduler('capability-match')
+    const agents = [
+      agent('researcher', 'You are a research expert who analyzes data and writes reports'),
+      agent('coder', 'You are a software engineer who writes TypeScript code'),
+    ]
+    const tasks = [
+      pendingTask('Write TypeScript code for the API'),
+      pendingTask('Research and analyze market data'),
+    ]
+
+    const assignments = s.schedule(tasks, agents)
+
+    expect(assignments.get(tasks[0]!.id)).toBe('coder')
+    expect(assignments.get(tasks[1]!.id)).toBe('researcher')
+  })
+
+  it('falls back to first agent when no keywords match', () => {
+    const s = new Scheduler('capability-match')
+    const agents = [agent('alpha'), agent('beta')]
+    const tasks = [pendingTask('xyz')]
+
+    const assignments = s.schedule(tasks, agents)
+
+    // When scores are tied (all 0), first agent wins
+    expect(assignments.size).toBe(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// dependency-first
+// ---------------------------------------------------------------------------
+
+describe('Scheduler: dependency-first', () => {
+  it('prioritises tasks that unblock more dependents', () => {
+    const s = new Scheduler('dependency-first')
+    const agents = [agent('a')]
+
+    // t1 blocks t2 and t3; t2 blocks nothing
+    const t1 = pendingTask('t1')
+    const t2 = pendingTask('t2')
+    const t3 = { ...pendingTask('t3'), dependsOn: [t1.id] }
+    const t4 = { ...pendingTask('t4'), dependsOn: [t1.id] }
+
+    const allTasks = [t2, t1, t3, t4] // t2 first in input order
+
+    const assignments = s.schedule(allTasks, agents)
+
+    // t1 should be assigned first (unblocks 2 others)
+    const entries = [...assignments.entries()]
+    expect(entries[0]![0]).toBe(t1.id)
+  })
+
+  it('returns empty map for empty task list', () => {
+    const s = new Scheduler('dependency-first')
+    const assignments = s.schedule([], [agent('a')])
+    expect(assignments.size).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// autoAssign
+// ---------------------------------------------------------------------------
+
+describe('Scheduler: autoAssign', () => {
+  it('updates queue tasks with assignees', () => {
+    const s = new Scheduler('round-robin')
+    const agents = [agent('a'), agent('b')]
+    const queue = new TaskQueue()
+
+    const t1 = pendingTask('t1')
+    const t2 = pendingTask('t2')
+    queue.add(t1)
+    queue.add(t2)
+
+    s.autoAssign(queue, agents)
+
+    const tasks = queue.list()
+    const assignees = tasks.map(t => t.assignee)
+    expect(assignees).toContain('a')
+    expect(assignees).toContain('b')
+  })
+
+  it('does not overwrite existing assignees', () => {
+    const s = new Scheduler('round-robin')
+    const agents = [agent('a'), agent('b')]
+    const queue = new TaskQueue()
+
+    const t1 = pendingTask('t1', { assignee: 'x' })
+    queue.add(t1)
+
+    s.autoAssign(queue, agents)
+
+    expect(queue.list()[0]!.assignee).toBe('x')
+  })
+})

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)
+  })
+})