@jackchen_me/open-multi-agent 0.2.0 → 1.0.1

package/examples/01-single-agent.ts

@@ -1,131 +0,0 @@
-/**
- * Example 01 — Single Agent
- *
- * The simplest possible usage: one agent with bash and file tools, running
- * a coding task. Then shows streaming output using the Agent class directly.
- *
- * Run:
- *   npx tsx examples/01-single-agent.ts
- *
- * Prerequisites:
- *   ANTHROPIC_API_KEY env var must be set.
- */
-
-import { OpenMultiAgent, Agent, ToolRegistry, ToolExecutor, registerBuiltInTools } from '../src/index.js'
-import type { OrchestratorEvent } from '../src/types.js'
-
-// ---------------------------------------------------------------------------
-// Part 1: Single agent via OpenMultiAgent (simplest path)
-// ---------------------------------------------------------------------------
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: 'claude-sonnet-4-6',
-  onProgress: (event: OrchestratorEvent) => {
-    if (event.type === 'agent_start') {
-      console.log(`[start]    agent=${event.agent}`)
-    } else if (event.type === 'agent_complete') {
-      console.log(`[complete] agent=${event.agent}`)
-    }
-  },
-})
-
-console.log('Part 1: runAgent() — single one-shot task\n')
-
-const result = await orchestrator.runAgent(
-  {
-    name: 'coder',
-    model: 'claude-sonnet-4-6',
-    systemPrompt: `You are a focused TypeScript developer.
-When asked to implement something, write clean, minimal code with no extra commentary.
-Use the bash tool to run commands and the file tools to read/write files.`,
-    tools: ['bash', 'file_read', 'file_write'],
-    maxTurns: 8,
-  },
-  `Create a small TypeScript utility function in /tmp/greet.ts that:
-  1. Exports a function named greet(name: string): string
-  2. Returns "Hello, <name>!"
-  3. Adds a brief usage comment at the top of the file.
-  Then add a default call greet("World") at the bottom and run the file with: npx tsx /tmp/greet.ts`,
-)
-
-if (result.success) {
-  console.log('\nAgent output:')
-  console.log('─'.repeat(60))
-  console.log(result.output)
-  console.log('─'.repeat(60))
-} else {
-  console.error('Agent failed:', result.output)
-  process.exit(1)
-}
-
-console.log('\nToken usage:')
-console.log(`  input:  ${result.tokenUsage.input_tokens}`)
-console.log(`  output: ${result.tokenUsage.output_tokens}`)
-console.log(`  tool calls made: ${result.toolCalls.length}`)
-
-// ---------------------------------------------------------------------------
-// Part 2: Streaming via Agent directly
-//
-// OpenMultiAgent.runAgent() is a convenient wrapper. When you need streaming, use
-// the Agent class directly with an injected ToolRegistry + ToolExecutor.
-// ---------------------------------------------------------------------------
-
-console.log('\n\nPart 2: Agent.stream() — incremental text output\n')
-
-// Build a registry with all built-in tools registered
-const registry = new ToolRegistry()
-registerBuiltInTools(registry)
-const executor = new ToolExecutor(registry)
-
-const streamingAgent = new Agent(
-  {
-    name: 'explainer',
-    model: 'claude-sonnet-4-6',
-    systemPrompt: 'You are a concise technical writer. Keep explanations brief.',
-    maxTurns: 3,
-  },
-  registry,
-  executor,
-)
-
-process.stdout.write('Streaming: ')
-
-for await (const event of streamingAgent.stream(
-  'In two sentences, explain what a TypeScript generic constraint is.',
-)) {
-  if (event.type === 'text' && typeof event.data === 'string') {
-    process.stdout.write(event.data)
-  } else if (event.type === 'done') {
-    process.stdout.write('\n')
-  } else if (event.type === 'error') {
-    console.error('\nStream error:', event.data)
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Part 3: Multi-turn conversation via Agent.prompt()
-// ---------------------------------------------------------------------------
-
-console.log('\nPart 3: Agent.prompt() — multi-turn conversation\n')
-
-const conversationAgent = new Agent(
-  {
-    name: 'tutor',
-    model: 'claude-sonnet-4-6',
-    systemPrompt: 'You are a TypeScript tutor. Give short, direct answers.',
-    maxTurns: 2,
-  },
-  new ToolRegistry(), // no tools needed for this conversation
-  new ToolExecutor(new ToolRegistry()),
-)
-
-const turn1 = await conversationAgent.prompt('What is a type guard in TypeScript?')
-console.log('Turn 1:', turn1.output.slice(0, 200))
-
-const turn2 = await conversationAgent.prompt('Give me one concrete code example of what you just described.')
-console.log('\nTurn 2:', turn2.output.slice(0, 300))
-
-// History is retained between prompt() calls
-console.log(`\nConversation history length: ${conversationAgent.getHistory().length} messages`)
-
-console.log('\nDone.')

package/examples/02-team-collaboration.ts

@@ -1,167 +0,0 @@
-/**
- * Example 02 — Multi-Agent Team Collaboration
- *
- * Three specialised agents (architect, developer, reviewer) collaborate on a
- * shared goal. The OpenMultiAgent orchestrator breaks the goal into tasks, assigns
- * them to the right agents, and collects the results.
- *
- * Run:
- *   npx tsx examples/02-team-collaboration.ts
- *
- * Prerequisites:
- *   ANTHROPIC_API_KEY env var must be set.
- */
-
-import { OpenMultiAgent } from '../src/index.js'
-import type { AgentConfig, OrchestratorEvent } from '../src/types.js'
-
-// ---------------------------------------------------------------------------
-// Agent definitions
-// ---------------------------------------------------------------------------
-
-const architect: AgentConfig = {
-  name: 'architect',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: `You are a software architect with deep experience in Node.js and REST API design.
-Your job is to design clear, production-quality API contracts and file/directory structures.
-Output concise plans in markdown — no unnecessary prose.`,
-  tools: ['bash', 'file_write'],
-  maxTurns: 5,
-  temperature: 0.2,
-}
-
-const developer: AgentConfig = {
-  name: 'developer',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: `You are a TypeScript/Node.js developer. You implement what the architect specifies.
-Write clean, runnable code with proper error handling. Use the tools to write files and run tests.`,
-  tools: ['bash', 'file_read', 'file_write', 'file_edit'],
-  maxTurns: 12,
-  temperature: 0.1,
-}
-
-const reviewer: AgentConfig = {
-  name: 'reviewer',
-  model: 'claude-sonnet-4-6',
-  provider: 'anthropic',
-  systemPrompt: `You are a senior code reviewer. Review code for correctness, security, and clarity.
-Provide a structured review with: LGTM items, suggestions, and any blocking issues.
-Read files using the tools before reviewing.`,
-  tools: ['bash', 'file_read', 'grep'],
-  maxTurns: 5,
-  temperature: 0.3,
-}
-
-// ---------------------------------------------------------------------------
-// Progress tracking
-// ---------------------------------------------------------------------------
-
-const startTimes = new Map<string, number>()
-
-function handleProgress(event: OrchestratorEvent): void {
-  const ts = new Date().toISOString().slice(11, 23) // HH:MM:SS.mmm
-
-  switch (event.type) {
-    case 'agent_start':
-      startTimes.set(event.agent ?? '', Date.now())
-      console.log(`[${ts}] AGENT START  → ${event.agent}`)
-      break
-
-    case 'agent_complete': {
-      const elapsed = Date.now() - (startTimes.get(event.agent ?? '') ?? Date.now())
-      console.log(`[${ts}] AGENT DONE   ← ${event.agent} (${elapsed}ms)`)
-      break
-    }
-
-    case 'task_start':
-      console.log(`[${ts}] TASK START   ↓ ${event.task}`)
-      break
-
-    case 'task_complete':
-      console.log(`[${ts}] TASK DONE    ↑ ${event.task}`)
-      break
-
-    case 'message':
-      console.log(`[${ts}] MESSAGE      • ${event.agent} → (team)`)
-      break
-
-    case 'error':
-      console.error(`[${ts}] ERROR        ✗ agent=${event.agent} task=${event.task}`)
-      if (event.data instanceof Error) {
-        console.error(`               ${event.data.message}`)
-      }
-      break
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Orchestrate
-// ---------------------------------------------------------------------------
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: 'claude-sonnet-4-6',
-  maxConcurrency: 1, // run agents sequentially so output is readable
-  onProgress: handleProgress,
-})
-
-const team = orchestrator.createTeam('api-team', {
-  name: 'api-team',
-  agents: [architect, developer, reviewer],
-  sharedMemory: true,
-  maxConcurrency: 1,
-})
-
-console.log(`Team "${team.name}" created with agents: ${team.getAgents().map(a => a.name).join(', ')}`)
-console.log('\nStarting team run...\n')
-console.log('='.repeat(60))
-
-const goal = `Create a minimal Express.js REST API in /tmp/express-api/ with:
-- GET  /health       → { status: "ok" }
-- GET  /users        → returns a hardcoded array of 2 user objects
-- POST /users        → accepts { name, email } body, logs it, returns 201
-- Proper error handling middleware
-- The server should listen on port 3001
-- Include a package.json with the required dependencies`
-
-const result = await orchestrator.runTeam(team, goal)
-
-console.log('\n' + '='.repeat(60))
-
-// ---------------------------------------------------------------------------
-// Results
-// ---------------------------------------------------------------------------
-
-console.log('\nTeam run complete.')
-console.log(`Success: ${result.success}`)
-console.log(`Total tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
-
-console.log('\nPer-agent results:')
-for (const [agentName, agentResult] of result.agentResults) {
-  const status = agentResult.success ? 'OK' : 'FAILED'
-  const tools = agentResult.toolCalls.length
-  console.log(`  ${agentName.padEnd(12)} [${status}]  tool_calls=${tools}`)
-  if (!agentResult.success) {
-    console.log(`    Error: ${agentResult.output.slice(0, 120)}`)
-  }
-}
-
-// Print the developer's final output (the actual code) as a sample
-const developerResult = result.agentResults.get('developer')
-if (developerResult?.success) {
-  console.log('\nDeveloper output (last 600 chars):')
-  console.log('─'.repeat(60))
-  const out = developerResult.output
-  console.log(out.length > 600 ? '...' + out.slice(-600) : out)
-  console.log('─'.repeat(60))
-}
-
-// Print the reviewer's findings
-const reviewerResult = result.agentResults.get('reviewer')
-if (reviewerResult?.success) {
-  console.log('\nReviewer output:')
-  console.log('─'.repeat(60))
-  console.log(reviewerResult.output)
-  console.log('─'.repeat(60))
-}

package/examples/03-task-pipeline.ts

@@ -1,201 +0,0 @@
-/**
- * Example 03 — Explicit Task Pipeline with Dependencies
- *
- * Demonstrates how to define tasks with explicit dependency chains
- * (design → implement → test → review) using runTasks(). The TaskQueue
- * automatically blocks downstream tasks until their dependencies complete.
- *
- * Run:
- *   npx tsx examples/03-task-pipeline.ts
- *
- * Prerequisites:
- *   ANTHROPIC_API_KEY env var must be set.
- */
-
-import { OpenMultiAgent } from '../src/index.js'
-import type { AgentConfig, OrchestratorEvent, Task } from '../src/types.js'
-
-// ---------------------------------------------------------------------------
-// Agents
-// ---------------------------------------------------------------------------
-
-const designer: AgentConfig = {
-  name: 'designer',
-  model: 'claude-sonnet-4-6',
-  systemPrompt: `You are a software designer. Your output is always a concise technical spec
-in markdown. Focus on interfaces, data shapes, and file structure. Be brief.`,
-  tools: ['file_write'],
-  maxTurns: 4,
-}
-
-const implementer: AgentConfig = {
-  name: 'implementer',
-  model: 'claude-sonnet-4-6',
-  systemPrompt: `You are a TypeScript developer. Read the design spec written by the designer,
-then implement it. Write all files to /tmp/pipeline-output/. Use the tools.`,
-  tools: ['bash', 'file_read', 'file_write'],
-  maxTurns: 10,
-}
-
-const tester: AgentConfig = {
-  name: 'tester',
-  model: 'claude-sonnet-4-6',
-  systemPrompt: `You are a QA engineer. Read the implemented files and run them to verify correctness.
-Report: what passed, what failed, and any bugs found.`,
-  tools: ['bash', 'file_read', 'grep'],
-  maxTurns: 6,
-}
-
-const reviewer: AgentConfig = {
-  name: 'reviewer',
-  model: 'claude-sonnet-4-6',
-  systemPrompt: `You are a code reviewer. Read all files and produce a brief structured review.
-Sections: Summary, Strengths, Issues (if any), Verdict (SHIP / NEEDS WORK).`,
-  tools: ['file_read', 'grep'],
-  maxTurns: 4,
-}
-
-// ---------------------------------------------------------------------------
-// Progress handler — shows dependency blocking/unblocking
-// ---------------------------------------------------------------------------
-
-const taskTimes = new Map<string, number>()
-
-function handleProgress(event: OrchestratorEvent): void {
-  const ts = new Date().toISOString().slice(11, 23)
-
-  switch (event.type) {
-    case 'task_start': {
-      taskTimes.set(event.task ?? '', Date.now())
-      const task = event.data as Task | undefined
-      console.log(`[${ts}] TASK READY    "${task?.title ?? event.task}" (assignee: ${task?.assignee ?? 'any'})`)
-      break
-    }
-    case 'task_complete': {
-      const elapsed = Date.now() - (taskTimes.get(event.task ?? '') ?? Date.now())
-      const task = event.data as Task | undefined
-      console.log(`[${ts}] TASK DONE     "${task?.title ?? event.task}" in ${elapsed}ms`)
-      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': {
-      const task = event.data as Task | undefined
-      console.error(`[${ts}] ERROR         ${event.agent ?? ''}  task="${task?.title ?? event.task}"`)
-      break
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Build the pipeline
-// ---------------------------------------------------------------------------
-
-const orchestrator = new OpenMultiAgent({
-  defaultModel: 'claude-sonnet-4-6',
-  maxConcurrency: 2, // allow test + review to potentially run in parallel later
-  onProgress: handleProgress,
-})
-
-const team = orchestrator.createTeam('pipeline-team', {
-  name: 'pipeline-team',
-  agents: [designer, implementer, tester, reviewer],
-  sharedMemory: true,
-})
-
-// Task IDs — use stable strings so dependsOn can reference them
-// (IDs will be generated by the framework; we capture the returned Task objects)
-const SPEC_FILE = '/tmp/pipeline-output/design-spec.md'
-
-const tasks: Array<{
-  title: string
-  description: string
-  assignee?: string
-  dependsOn?: string[]
-}> = [
-  {
-    title: 'Design: URL shortener data model',
-    description: `Design a minimal in-memory URL shortener service.
-Write a markdown spec to ${SPEC_FILE} covering:
-- TypeScript interfaces for Url and ShortenRequest
-- The shortening algorithm (hash approach is fine)
-- API contract: POST /shorten, GET /:code
-Keep the spec under 30 lines.`,
-    assignee: 'designer',
-    // no dependencies — this is the root task
-  },
-  {
-    title: 'Implement: URL shortener',
-    description: `Read the design spec at ${SPEC_FILE}.
-Implement the URL shortener in /tmp/pipeline-output/src/:
-- shortener.ts: core logic (shorten, resolve functions)
-- server.ts: tiny HTTP server using Node's built-in http module (no Express)
-  - POST /shorten  body: { url: string } → { code: string, short: string }
-  - GET  /:code    → redirect (301) or 404
-- index.ts: entry point that starts the server on port 3002
-No external dependencies beyond Node built-ins.`,
-    assignee: 'implementer',
-    dependsOn: ['Design: URL shortener data model'],
-  },
-  {
-    title: 'Test: URL shortener',
-    description: `Run the URL shortener implementation:
-1. Start the server: node /tmp/pipeline-output/src/index.ts (or tsx)
-2. POST a URL to shorten it using curl
-3. Verify the GET redirect works
-4. Report what passed and what (if anything) failed.
-Kill the server after testing.`,
-    assignee: 'tester',
-    dependsOn: ['Implement: URL shortener'],
-  },
-  {
-    title: 'Review: URL shortener',
-    description: `Read all .ts files in /tmp/pipeline-output/src/ and the design spec.
-Produce a structured code review with sections:
-- Summary (2 sentences)
-- Strengths (bullet list)
-- Issues (bullet list, or "None" if clean)
-- Verdict: SHIP or NEEDS WORK`,
-    assignee: 'reviewer',
-    dependsOn: ['Implement: URL shortener'], // runs in parallel with Test after Implement completes
-  },
-]
-
-// ---------------------------------------------------------------------------
-// Run
-// ---------------------------------------------------------------------------
-
-console.log('Starting 4-stage task pipeline...\n')
-console.log('Pipeline: design → implement → test + review (parallel)')
-console.log('='.repeat(60))
-
-const result = await orchestrator.runTasks(team, tasks)
-
-// ---------------------------------------------------------------------------
-// Summary
-// ---------------------------------------------------------------------------
-
-console.log('\n' + '='.repeat(60))
-console.log('Pipeline complete.\n')
-console.log(`Overall success: ${result.success}`)
-console.log(`Tokens — input: ${result.totalTokenUsage.input_tokens}, output: ${result.totalTokenUsage.output_tokens}`)
-
-console.log('\nPer-agent summary:')
-for (const [name, r] of result.agentResults) {
-  const icon = r.success ? 'OK  ' : 'FAIL'
-  const toolCount = r.toolCalls.map(c => c.toolName).join(', ')
-  console.log(`  [${icon}] ${name.padEnd(14)}  tools used: ${toolCount || '(none)'}`)
-}
-
-// Print the reviewer's verdict
-const review = result.agentResults.get('reviewer')
-if (review?.success) {
-  console.log('\nCode review:')
-  console.log('─'.repeat(60))
-  console.log(review.output)
-  console.log('─'.repeat(60))
-}