@jackchen_me/open-multi-agent 0.1.0

package/src/agent/runner.ts

@@ -0,0 +1,413 @@
+/**
+ * @fileoverview Core conversation loop engine for open-multi-agent.
+ *
+ * {@link AgentRunner} is the heart of the framework. It handles:
+ *  - Sending messages to the LLM adapter
+ *  - Extracting tool-use blocks from the response
+ *  - Executing tool calls in parallel via {@link ToolExecutor}
+ *  - Appending tool results and looping back until `end_turn`
+ *  - Accumulating token usage and timing data across all turns
+ *
+ * The loop follows a standard agentic conversation pattern:
+ * one outer `while (true)` that breaks on `end_turn` or maxTurns exhaustion.
+ */
+
+import type {
+  LLMMessage,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  ToolCallRecord,
+  TokenUsage,
+  StreamEvent,
+  ToolResult,
+  ToolUseContext,
+  LLMAdapter,
+  LLMChatOptions,
+} from '../types.js'
+import type { ToolRegistry } from '../tool/framework.js'
+import type { ToolExecutor } from '../tool/executor.js'
+
+// ---------------------------------------------------------------------------
+// Public interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * Static configuration for an {@link AgentRunner} instance.
+ * These values are constant across every `run` / `stream` call.
+ */
+export interface RunnerOptions {
+  /** LLM model identifier, e.g. `'claude-opus-4-6'`. */
+  readonly model: string
+  /** Optional system prompt prepended to every conversation. */
+  readonly systemPrompt?: string
+  /**
+   * Maximum number of tool-call round-trips before the runner stops.
+   * Prevents unbounded loops. Defaults to `10`.
+   */
+  readonly maxTurns?: number
+  /** Maximum output tokens per LLM response. */
+  readonly maxTokens?: number
+  /** Sampling temperature passed to the adapter. */
+  readonly temperature?: number
+  /** AbortSignal that cancels any in-flight adapter call and stops the loop. */
+  readonly abortSignal?: AbortSignal
+  /**
+   * Whitelist of tool names this runner is allowed to use.
+   * When provided, only tools whose name appears in this list are sent to the
+   * LLM. When omitted, all registered tools are available.
+   */
+  readonly allowedTools?: readonly string[]
+  /** Display name of the agent driving this runner (used in tool context). */
+  readonly agentName?: string
+  /** Short role description of the agent (used in tool context). */
+  readonly agentRole?: string
+}
+
+/**
+ * Per-call callbacks for observing tool execution in real time.
+ * All callbacks are optional; unused ones are simply skipped.
+ */
+export interface RunOptions {
+  /** Fired just before each tool is dispatched. */
+  readonly onToolCall?: (name: string, input: Record<string, unknown>) => void
+  /** Fired after each tool result is received. */
+  readonly onToolResult?: (name: string, result: ToolResult) => void
+  /** Fired after each complete {@link LLMMessage} is appended. */
+  readonly onMessage?: (message: LLMMessage) => void
+}
+
+/** The aggregated result returned when a full run completes. */
+export interface RunResult {
+  /** All messages accumulated during this run (assistant + tool results). */
+  readonly messages: LLMMessage[]
+  /** The final text output from the last assistant turn. */
+  readonly output: string
+  /** All tool calls made during this run, in execution order. */
+  readonly toolCalls: ToolCallRecord[]
+  /** Aggregated token counts across every LLM call in this run. */
+  readonly tokenUsage: TokenUsage
+  /** Total number of LLM turns (including tool-call follow-ups). */
+  readonly turns: number
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Extract every TextBlock from a content array and join them. */
+function extractText(content: readonly ContentBlock[]): string {
+  return content
+    .filter((b): b is TextBlock => b.type === 'text')
+    .map(b => b.text)
+    .join('')
+}
+
+/** Extract every ToolUseBlock from a content array. */
+function extractToolUseBlocks(content: readonly ContentBlock[]): ToolUseBlock[] {
+  return content.filter((b): b is ToolUseBlock => b.type === 'tool_use')
+}
+
+/** Add two {@link TokenUsage} values together, returning a new object. */
+function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    input_tokens: a.input_tokens + b.input_tokens,
+    output_tokens: a.output_tokens + b.output_tokens,
+  }
+}
+
+const ZERO_USAGE: TokenUsage = { input_tokens: 0, output_tokens: 0 }
+
+// ---------------------------------------------------------------------------
+// AgentRunner
+// ---------------------------------------------------------------------------
+
+/**
+ * Drives a full agentic conversation: LLM calls, tool execution, and looping.
+ *
+ * @example
+ * ```ts
+ * const runner = new AgentRunner(adapter, registry, executor, {
+ *   model: 'claude-opus-4-6',
+ *   maxTurns: 10,
+ * })
+ * const result = await runner.run(messages)
+ * console.log(result.output)
+ * ```
+ */
+export class AgentRunner {
+  private readonly maxTurns: number
+
+  constructor(
+    private readonly adapter: LLMAdapter,
+    private readonly toolRegistry: ToolRegistry,
+    private readonly toolExecutor: ToolExecutor,
+    private readonly options: RunnerOptions,
+  ) {
+    this.maxTurns = options.maxTurns ?? 10
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Run a complete conversation starting from `messages`.
+   *
+   * The call may internally make multiple LLM requests (one per tool-call
+   * round-trip). It returns only when:
+   *  - The LLM emits `end_turn` with no tool-use blocks, or
+   *  - `maxTurns` is exceeded, or
+   *  - The abort signal is triggered.
+   */
+  async run(
+    messages: LLMMessage[],
+    options: RunOptions = {},
+  ): Promise<RunResult> {
+    // Collect everything yielded by the internal streaming loop.
+    const accumulated: {
+      messages: LLMMessage[]
+      output: string
+      toolCalls: ToolCallRecord[]
+      tokenUsage: TokenUsage
+      turns: number
+    } = {
+      messages: [],
+      output: '',
+      toolCalls: [],
+      tokenUsage: ZERO_USAGE,
+      turns: 0,
+    }
+
+    for await (const event of this.stream(messages, options)) {
+      if (event.type === 'done') {
+        const result = event.data as RunResult
+        accumulated.messages = result.messages
+        accumulated.output = result.output
+        accumulated.toolCalls = result.toolCalls
+        accumulated.tokenUsage = result.tokenUsage
+        accumulated.turns = result.turns
+      }
+    }
+
+    return accumulated
+  }
+
+  /**
+   * Run the conversation and yield {@link StreamEvent}s incrementally.
+   *
+   * Callers receive:
+   *  - `{ type: 'text', data: string }` for each text delta
+   *  - `{ type: 'tool_use', data: ToolUseBlock }` when the model requests a tool
+   *  - `{ type: 'tool_result', data: ToolResultBlock }` after each execution
+   *  - `{ type: 'done', data: RunResult }` at the very end
+   *  - `{ type: 'error', data: Error }` on unrecoverable failure
+   */
+  async *stream(
+    initialMessages: LLMMessage[],
+    options: RunOptions = {},
+  ): AsyncGenerator<StreamEvent> {
+    // Working copy of the conversation — mutated as turns progress.
+    const conversationMessages: LLMMessage[] = [...initialMessages]
+
+    // Accumulated state across all turns.
+    let totalUsage: TokenUsage = ZERO_USAGE
+    const allToolCalls: ToolCallRecord[] = []
+    let finalOutput = ''
+    let turns = 0
+
+    // Build the stable LLM options once; model / tokens / temp don't change.
+    // toToolDefs() returns LLMToolDef[] (inputSchema, camelCase) — matches
+    // LLMChatOptions.tools from types.ts directly.
+    const allDefs = this.toolRegistry.toToolDefs()
+    const toolDefs = this.options.allowedTools
+      ? allDefs.filter(d => this.options.allowedTools!.includes(d.name))
+      : allDefs
+
+    const baseChatOptions: LLMChatOptions = {
+      model: this.options.model,
+      tools: toolDefs.length > 0 ? toolDefs : undefined,
+      maxTokens: this.options.maxTokens,
+      temperature: this.options.temperature,
+      systemPrompt: this.options.systemPrompt,
+      abortSignal: this.options.abortSignal,
+    }
+
+    try {
+      // -----------------------------------------------------------------
+      // Main agentic loop — `while (true)` until end_turn or maxTurns
+      // -----------------------------------------------------------------
+      while (true) {
+        // Respect abort before each LLM call.
+        if (this.options.abortSignal?.aborted) {
+          break
+        }
+
+        // Guard against unbounded loops.
+        if (turns >= this.maxTurns) {
+          break
+        }
+
+        turns++
+
+        // ------------------------------------------------------------------
+        // Step 1: Call the LLM and collect the full response for this turn.
+        // ------------------------------------------------------------------
+        const response = await this.adapter.chat(conversationMessages, baseChatOptions)
+
+        totalUsage = addTokenUsage(totalUsage, response.usage)
+
+        // ------------------------------------------------------------------
+        // Step 2: Build the assistant message from the response content.
+        // ------------------------------------------------------------------
+        const assistantMessage: LLMMessage = {
+          role: 'assistant',
+          content: response.content,
+        }
+
+        conversationMessages.push(assistantMessage)
+        options.onMessage?.(assistantMessage)
+
+        // Yield text deltas so streaming callers can display them promptly.
+        const turnText = extractText(response.content)
+        if (turnText.length > 0) {
+          yield { type: 'text', data: turnText } satisfies StreamEvent
+        }
+
+        // Announce each tool-use block the model requested.
+        const toolUseBlocks = extractToolUseBlocks(response.content)
+        for (const block of toolUseBlocks) {
+          yield { type: 'tool_use', data: block } satisfies StreamEvent
+        }
+
+        // ------------------------------------------------------------------
+        // Step 3: Decide whether to continue looping.
+        // ------------------------------------------------------------------
+        if (toolUseBlocks.length === 0) {
+          // No tools requested — this is the terminal assistant turn.
+          finalOutput = turnText
+          break
+        }
+
+        // ------------------------------------------------------------------
+        // Step 4: Execute all tool calls in PARALLEL.
+        //
+        // Parallel execution is critical for multi-tool responses where the
+        // tools are independent (e.g. reading several files at once).
+        // ------------------------------------------------------------------
+        const toolContext: ToolUseContext = this.buildToolContext()
+
+        const executionPromises = toolUseBlocks.map(async (block): Promise<{
+          resultBlock: ToolResultBlock
+          record: ToolCallRecord
+        }> => {
+          options.onToolCall?.(block.name, block.input)
+
+          const startTime = Date.now()
+          let result: ToolResult
+
+          try {
+            result = await this.toolExecutor.execute(
+              block.name,
+              block.input,
+              toolContext,
+            )
+          } catch (err) {
+            // Tool executor errors become error results — the loop continues.
+            const message = err instanceof Error ? err.message : String(err)
+            result = { data: message, isError: true }
+          }
+
+          const duration = Date.now() - startTime
+
+          options.onToolResult?.(block.name, result)
+
+          const record: ToolCallRecord = {
+            toolName: block.name,
+            input: block.input,
+            output: result.data,
+            duration,
+          }
+
+          const resultBlock: ToolResultBlock = {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: result.data,
+            is_error: result.isError,
+          }
+
+          return { resultBlock, record }
+        })
+
+        // Wait for every tool in this turn to finish.
+        const executions = await Promise.all(executionPromises)
+
+        // ------------------------------------------------------------------
+        // Step 5: Accumulate results and build the user message that carries
+        //         them back to the LLM in the next turn.
+        // ------------------------------------------------------------------
+        const toolResultBlocks: ContentBlock[] = executions.map(e => e.resultBlock)
+
+        for (const { record, resultBlock } of executions) {
+          allToolCalls.push(record)
+          yield { type: 'tool_result', data: resultBlock } satisfies StreamEvent
+        }
+
+        const toolResultMessage: LLMMessage = {
+          role: 'user',
+          content: toolResultBlocks,
+        }
+
+        conversationMessages.push(toolResultMessage)
+        options.onMessage?.(toolResultMessage)
+
+        // Loop back to Step 1 — send updated conversation to the LLM.
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      yield { type: 'error', data: error } satisfies StreamEvent
+      return
+    }
+
+    // If the loop exited due to maxTurns, use whatever text was last emitted.
+    if (finalOutput === '' && conversationMessages.length > 0) {
+      const lastAssistant = [...conversationMessages]
+        .reverse()
+        .find(m => m.role === 'assistant')
+      if (lastAssistant !== undefined) {
+        finalOutput = extractText(lastAssistant.content)
+      }
+    }
+
+    const runResult: RunResult = {
+      // Return only the messages added during this run (not the initial seed).
+      messages: conversationMessages.slice(initialMessages.length),
+      output: finalOutput,
+      toolCalls: allToolCalls,
+      tokenUsage: totalUsage,
+      turns,
+    }
+
+    yield { type: 'done', data: runResult } satisfies StreamEvent
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Build the {@link ToolUseContext} passed to every tool execution.
+   * Identifies this runner as the invoking agent.
+   */
+  private buildToolContext(): ToolUseContext {
+    return {
+      agent: {
+        name: this.options.agentName ?? 'runner',
+        role: this.options.agentRole ?? 'assistant',
+        model: this.options.model,
+      },
+      abortSignal: this.options.abortSignal,
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview open-multi-agent — public API surface.
+ *
+ * Import from `'open-multi-agent'` to access everything you need:
+ *
+ * ```ts
+ * import { OpenMultiAgent, Agent, Team, defineTool } from 'open-multi-agent'
+ * ```
+ *
+ * ## Quickstart
+ *
+ * ### Single agent
+ * ```ts
+ * const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-opus-4-6' })
+ * const result = await orchestrator.runAgent(
+ *   { name: 'assistant', model: 'claude-opus-4-6' },
+ *   'Explain monads in one paragraph.',
+ * )
+ * console.log(result.output)
+ * ```
+ *
+ * ### Multi-agent team (auto-orchestrated)
+ * ```ts
+ * const orchestrator = new OpenMultiAgent()
+ * const team = orchestrator.createTeam('writers', {
+ *   name: 'writers',
+ *   agents: [
+ *     { name: 'researcher', model: 'claude-opus-4-6', systemPrompt: 'You research topics thoroughly.' },
+ *     { name: 'writer',     model: 'claude-opus-4-6', systemPrompt: 'You write clear documentation.' },
+ *   ],
+ *   sharedMemory: true,
+ * })
+ * const result = await orchestrator.runTeam(team, 'Write a guide on TypeScript generics.')
+ * console.log(result.agentResults.get('coordinator')?.output)
+ * ```
+ *
+ * ### Custom tools
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const myTool = defineTool({
+ *   name: 'fetch_data',
+ *   description: 'Fetch JSON data from a URL.',
+ *   inputSchema: z.object({ url: z.string().url() }),
+ *   execute: async ({ url }) => {
+ *     const res = await fetch(url)
+ *     return { data: await res.text() }
+ *   },
+ * })
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Orchestrator (primary entry point)
+// ---------------------------------------------------------------------------
+
+export { OpenMultiAgent } from './orchestrator/orchestrator.js'
+export { Scheduler } from './orchestrator/scheduler.js'
+export type { SchedulingStrategy } from './orchestrator/scheduler.js'
+
+// ---------------------------------------------------------------------------
+// Agent layer
+// ---------------------------------------------------------------------------
+
+export { Agent } from './agent/agent.js'
+export { AgentPool, Semaphore } from './agent/pool.js'
+export type { PoolStatus } from './agent/pool.js'
+
+// ---------------------------------------------------------------------------
+// Team layer
+// ---------------------------------------------------------------------------
+
+export { Team } from './team/team.js'
+export { MessageBus } from './team/messaging.js'
+export type { Message } from './team/messaging.js'
+
+// ---------------------------------------------------------------------------
+// Task layer
+// ---------------------------------------------------------------------------
+
+export { TaskQueue } from './task/queue.js'
+export { createTask, isTaskReady, getTaskDependencyOrder, validateTaskDependencies } from './task/task.js'
+export type { TaskQueueEvent } from './task/queue.js'
+
+// ---------------------------------------------------------------------------
+// Tool system
+// ---------------------------------------------------------------------------
+
+export { defineTool, ToolRegistry, zodToJsonSchema } from './tool/framework.js'
+export { ToolExecutor } from './tool/executor.js'
+export type { ToolExecutorOptions, BatchToolCall } from './tool/executor.js'
+export {
+  registerBuiltInTools,
+  BUILT_IN_TOOLS,
+  bashTool,
+  fileReadTool,
+  fileWriteTool,
+  fileEditTool,
+  grepTool,
+} from './tool/built-in/index.js'
+
+// ---------------------------------------------------------------------------
+// LLM adapters
+// ---------------------------------------------------------------------------
+
+export { createAdapter } from './llm/adapter.js'
+export type { SupportedProvider } from './llm/adapter.js'
+
+// ---------------------------------------------------------------------------
+// Memory
+// ---------------------------------------------------------------------------
+
+export { InMemoryStore } from './memory/store.js'
+export { SharedMemory } from './memory/shared.js'
+
+// ---------------------------------------------------------------------------
+// Types — all public interfaces re-exported for consumer type-checking
+// ---------------------------------------------------------------------------
+
+export type {
+  // Content blocks
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  ImageBlock,
+  ContentBlock,
+
+  // LLM
+  LLMMessage,
+  LLMResponse,
+  LLMAdapter,
+  LLMChatOptions,
+  LLMStreamOptions,
+  LLMToolDef,
+  TokenUsage,
+  StreamEvent,
+
+  // Tools
+  ToolDefinition,
+  ToolResult,
+  ToolUseContext,
+  AgentInfo,
+  TeamInfo,
+
+  // Agent
+  AgentConfig,
+  AgentState,
+  AgentRunResult,
+  ToolCallRecord,
+
+  // Team
+  TeamConfig,
+  TeamRunResult,
+
+  // Task
+  Task,
+  TaskStatus,
+
+  // Orchestrator
+  OrchestratorConfig,
+  OrchestratorEvent,
+
+  // Memory
+  MemoryEntry,
+  MemoryStore,
+} from './types.js'

package/src/llm/adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview LLM adapter factory.
+ *
+ * Re-exports the {@link LLMAdapter} interface and provides a
+ * {@link createAdapter} factory that returns the correct concrete
+ * implementation based on the requested provider.
+ *
+ * @example
+ * ```ts
+ * import { createAdapter } from './adapter.js'
+ *
+ * const anthropic = createAdapter('anthropic')
+ * const openai    = createAdapter('openai', process.env.OPENAI_API_KEY)
+ * ```
+ */
+
+export type {
+  LLMAdapter,
+  LLMChatOptions,
+  LLMStreamOptions,
+  LLMToolDef,
+  LLMMessage,
+  LLMResponse,
+  StreamEvent,
+  TokenUsage,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  ImageBlock,
+} from '../types.js'
+
+import type { LLMAdapter } from '../types.js'
+
+/**
+ * The set of LLM providers supported out of the box.
+ * Additional providers can be integrated by implementing {@link LLMAdapter}
+ * directly and bypassing this factory.
+ */
+export type SupportedProvider = 'anthropic' | '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.
+ *
+ * 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.
+ * @throws {Error} When the provider string is not recognised.
+ */
+export async function createAdapter(
+  provider: SupportedProvider,
+  apiKey?: string,
+): Promise<LLMAdapter> {
+  switch (provider) {
+    case 'anthropic': {
+      const { AnthropicAdapter } = await import('./anthropic.js')
+      return new AnthropicAdapter(apiKey)
+    }
+    case 'openai': {
+      const { OpenAIAdapter } = await import('./openai.js')
+      return new OpenAIAdapter(apiKey)
+    }
+    default: {
+      // The `never` cast here makes TypeScript enforce exhaustiveness.
+      const _exhaustive: never = provider
+      throw new Error(`Unsupported LLM provider: ${String(_exhaustive)}`)
+    }
+  }
+}