@jackchen_me/open-multi-agent 0.2.0 → 1.0.1

package/src/types.ts

@@ -1,391 +0,0 @@
-/**
- * @fileoverview Core type definitions for the open-multi-agent orchestration framework.
- *
- * All public types are exported from this single module. Downstream modules
- * import only what they need, keeping the dependency graph acyclic.
- */
-
-import type { ZodSchema } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Content blocks
-// ---------------------------------------------------------------------------
-
-/** Plain-text content produced by a model or supplied by the user. */
-export interface TextBlock {
-  readonly type: 'text'
-  readonly text: string
-}
-
-/**
- * A request by the model to invoke a named tool with a structured input.
- * The `id` is unique per turn and is referenced by {@link ToolResultBlock}.
- */
-export interface ToolUseBlock {
-  readonly type: 'tool_use'
-  readonly id: string
-  readonly name: string
-  readonly input: Record<string, unknown>
-}
-
-/**
- * The result of executing a tool, keyed back to the originating
- * {@link ToolUseBlock} via `tool_use_id`.
- */
-export interface ToolResultBlock {
-  readonly type: 'tool_result'
-  readonly tool_use_id: string
-  readonly content: string
-  readonly is_error?: boolean
-}
-
-/** A base64-encoded image passed to or returned from a model. */
-export interface ImageBlock {
-  readonly type: 'image'
-  readonly source: {
-    readonly type: 'base64'
-    readonly media_type: string
-    readonly data: string
-  }
-}
-
-/** Union of all content block variants that may appear in a message. */
-export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ImageBlock
-
-// ---------------------------------------------------------------------------
-// LLM messages & responses
-// ---------------------------------------------------------------------------
-
-/**
- * A single message in a conversation thread.
- * System messages are passed separately via {@link LLMChatOptions.systemPrompt}.
- */
-export interface LLMMessage {
-  readonly role: 'user' | 'assistant'
-  readonly content: ContentBlock[]
-}
-
-/** Token accounting for a single API call. */
-export interface TokenUsage {
-  readonly input_tokens: number
-  readonly output_tokens: number
-}
-
-/** Normalised response returned by every {@link LLMAdapter} implementation. */
-export interface LLMResponse {
-  readonly id: string
-  readonly content: ContentBlock[]
-  readonly model: string
-  readonly stop_reason: string
-  readonly usage: TokenUsage
-}
-
-// ---------------------------------------------------------------------------
-// Streaming
-// ---------------------------------------------------------------------------
-
-/**
- * A discrete event emitted during streaming generation.
- *
- * - `text`        — incremental text delta
- * - `tool_use`    — the model has begun or completed a tool-use block
- * - `tool_result` — a tool result has been appended to the stream
- * - `done`        — the stream has ended; `data` is the final {@link LLMResponse}
- * - `error`       — an unrecoverable error occurred; `data` is an `Error`
- */
-export interface StreamEvent {
-  readonly type: 'text' | 'tool_use' | 'tool_result' | 'done' | 'error'
-  readonly data: unknown
-}
-
-// ---------------------------------------------------------------------------
-// Tool definitions
-// ---------------------------------------------------------------------------
-
-/** The serialisable tool schema sent to the LLM provider. */
-export interface LLMToolDef {
-  readonly name: string
-  readonly description: string
-  /** JSON Schema object describing the tool's `input` parameter. */
-  readonly inputSchema: Record<string, unknown>
-}
-
-/**
- * Context injected into every tool execution.
- *
- * Both `abortSignal` and `abortController` are provided so that tools and the
- * executor can choose the most ergonomic API for their use-case:
- *
- * - Long-running shell commands that need to kill a child process can use
- *   `abortController.signal` directly.
- * - Simple cancellation checks can read `abortSignal?.aborted`.
- *
- * When constructing a context, set `abortController` and derive `abortSignal`
- * from it, or provide both independently.
- */
-export interface ToolUseContext {
-  /** High-level description of the agent invoking this tool. */
-  readonly agent: AgentInfo
-  /** Team context, present when the tool runs inside a multi-agent team. */
-  readonly team?: TeamInfo
-  /**
-   * Convenience reference to the abort signal.
-   * Equivalent to `abortController?.signal` when an `abortController` is set.
-   */
-  readonly abortSignal?: AbortSignal
-  /**
-   * Full abort controller, available when the caller needs to inspect or
-   * programmatically abort the signal.
-   * Tools should prefer `abortSignal` for simple cancellation checks.
-   */
-  readonly abortController?: AbortController
-  /** Working directory hint for file-system tools. */
-  readonly cwd?: string
-  /** Arbitrary caller-supplied metadata (session ID, request ID, etc.). */
-  readonly metadata?: Readonly<Record<string, unknown>>
-}
-
-/** Minimal descriptor for the agent that is invoking a tool. */
-export interface AgentInfo {
-  readonly name: string
-  readonly role: string
-  readonly model: string
-}
-
-/** Descriptor for a team of agents with shared memory. */
-export interface TeamInfo {
-  readonly name: string
-  readonly agents: readonly string[]
-  readonly sharedMemory: MemoryStore
-}
-
-/** Value returned by a tool's `execute` function. */
-export interface ToolResult {
-  readonly data: string
-  readonly isError?: boolean
-}
-
-/**
- * A tool registered with the framework.
- *
- * `inputSchema` is a Zod schema used for validation before `execute` is called.
- * At API call time it is converted to JSON Schema via {@link LLMToolDef}.
- */
-export interface ToolDefinition<TInput = Record<string, unknown>> {
-  readonly name: string
-  readonly description: string
-  readonly inputSchema: ZodSchema<TInput>
-  execute(input: TInput, context: ToolUseContext): Promise<ToolResult>
-}
-
-// ---------------------------------------------------------------------------
-// Agent
-// ---------------------------------------------------------------------------
-
-/** Static configuration for a single agent. */
-export interface AgentConfig {
-  readonly name: string
-  readonly model: string
-  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. */
-export interface AgentState {
-  status: 'idle' | 'running' | 'completed' | 'error'
-  messages: LLMMessage[]
-  tokenUsage: TokenUsage
-  error?: Error
-}
-
-/** A single recorded tool invocation within a run. */
-export interface ToolCallRecord {
-  readonly toolName: string
-  readonly input: Record<string, unknown>
-  readonly output: string
-  /** Wall-clock duration in milliseconds. */
-  readonly duration: number
-}
-
-/** The final result produced when an agent run completes (or fails). */
-export interface AgentRunResult {
-  readonly success: boolean
-  readonly output: string
-  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
-}
-
-// ---------------------------------------------------------------------------
-// Team
-// ---------------------------------------------------------------------------
-
-/** Static configuration for a team of cooperating agents. */
-export interface TeamConfig {
-  readonly name: string
-  readonly agents: readonly AgentConfig[]
-  readonly sharedMemory?: boolean
-  readonly maxConcurrency?: number
-}
-
-/** Aggregated result for a full team run. */
-export interface TeamRunResult {
-  readonly success: boolean
-  /** Keyed by agent name. */
-  readonly agentResults: Map<string, AgentRunResult>
-  readonly totalTokenUsage: TokenUsage
-}
-
-// ---------------------------------------------------------------------------
-// Task
-// ---------------------------------------------------------------------------
-
-/** Valid states for a {@link Task}. */
-export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'blocked'
-
-/** A discrete unit of work tracked by the orchestrator. */
-export interface Task {
-  readonly id: string
-  readonly title: string
-  readonly description: string
-  status: TaskStatus
-  /** Agent name responsible for executing this task. */
-  assignee?: string
-  /** IDs of tasks that must complete before this one can start. */
-  dependsOn?: readonly string[]
-  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
-}
-
-// ---------------------------------------------------------------------------
-// Orchestrator
-// ---------------------------------------------------------------------------
-
-/** Progress event emitted by the orchestrator during a run. */
-export interface OrchestratorEvent {
-  readonly type:
-    | 'agent_start'
-    | 'agent_complete'
-    | 'task_start'
-    | 'task_complete'
-    | 'task_retry'
-    | 'message'
-    | 'error'
-  readonly agent?: string
-  readonly task?: string
-  readonly data?: unknown
-}
-
-/** Top-level configuration for the orchestrator. */
-export interface OrchestratorConfig {
-  readonly maxConcurrency?: number
-  readonly defaultModel?: string
-  readonly defaultProvider?: 'anthropic' | 'copilot' | 'openai'
-  readonly defaultBaseURL?: string
-  readonly defaultApiKey?: string
-  onProgress?: (event: OrchestratorEvent) => void
-}
-
-// ---------------------------------------------------------------------------
-// Memory
-// ---------------------------------------------------------------------------
-
-/** A single key-value record stored in a {@link MemoryStore}. */
-export interface MemoryEntry {
-  readonly key: string
-  readonly value: string
-  readonly metadata?: Readonly<Record<string, unknown>>
-  readonly createdAt: Date
-}
-
-/**
- * Persistent (or in-memory) key-value store shared across agents.
- * Implementations may be backed by Redis, SQLite, or plain objects.
- */
-export interface MemoryStore {
-  get(key: string): Promise<MemoryEntry | null>
-  set(key: string, value: string, metadata?: Record<string, unknown>): Promise<void>
-  list(): Promise<MemoryEntry[]>
-  delete(key: string): Promise<void>
-  clear(): Promise<void>
-}
-
-// ---------------------------------------------------------------------------
-// LLM adapter
-// ---------------------------------------------------------------------------
-
-/** Options shared by both chat and streaming calls. */
-export interface LLMChatOptions {
-  readonly model: string
-  readonly tools?: readonly LLMToolDef[]
-  readonly maxTokens?: number
-  readonly temperature?: number
-  readonly systemPrompt?: string
-  readonly abortSignal?: AbortSignal
-}
-
-/**
- * Options for streaming calls.
- * Extends {@link LLMChatOptions} without additional fields — the separation
- * exists so callers can type-narrow and implementations can diverge later.
- */
-export interface LLMStreamOptions extends LLMChatOptions {}
-
-/**
- * Provider-agnostic interface that every LLM backend must implement.
- *
- * @example
- * ```ts
- * const adapter: LLMAdapter = createAdapter('anthropic')
- * const response = await adapter.chat(messages, { model: 'claude-opus-4-6' })
- * ```
- */
-export interface LLMAdapter {
-  /** Human-readable provider name, e.g. `'anthropic'` or `'openai'`. */
-  readonly name: string
-
-  /**
-   * Send a chat request and return the complete response.
-   * Throws on non-retryable API errors.
-   */
-  chat(messages: LLMMessage[], options: LLMChatOptions): Promise<LLMResponse>
-
-  /**
-   * Send a chat request and yield {@link StreamEvent}s incrementally.
-   * The final event in the sequence always has `type === 'done'` on success,
-   * or `type === 'error'` on failure.
-   */
-  stream(messages: LLMMessage[], options: LLMStreamOptions): AsyncIterable<StreamEvent>
-}

package/src/utils/semaphore.ts

@@ -1,89 +0,0 @@
-/**
- * @fileoverview Shared counting semaphore for concurrency control.
- *
- * Used by both {@link ToolExecutor} and {@link AgentPool} to cap the number of
- * concurrent async operations without requiring any third-party dependencies.
- *
- * This is intentionally self-contained and tuned for Promise/async use —
- * not a general OS-semaphore replacement.
- */
-
-// ---------------------------------------------------------------------------
-// Semaphore
-// ---------------------------------------------------------------------------
-
-/**
- * Classic counting semaphore for concurrency control.
- *
- * `acquire()` resolves immediately if a slot is free, otherwise queues the
- * caller. `release()` unblocks the next waiter in FIFO order.
- *
- * Node.js is single-threaded, so this is safe without atomics or mutex
- * primitives — the semaphore gates concurrent async operations, not CPU threads.
- */
-export class Semaphore {
-  private current = 0
-  private readonly queue: Array<() => void> = []
-
-  /**
-   * @param max - Maximum number of concurrent holders. Must be >= 1.
-   */
-  constructor(private readonly max: number) {
-    if (max < 1) {
-      throw new RangeError(`Semaphore max must be at least 1, got ${max}`)
-    }
-  }
-
-  /**
-   * Acquire a slot. Resolves immediately when one is free, or waits until a
-   * holder calls `release()`.
-   */
-  acquire(): Promise<void> {
-    if (this.current < this.max) {
-      this.current++
-      return Promise.resolve()
-    }
-
-    return new Promise<void>(resolve => {
-      this.queue.push(resolve)
-    })
-  }
-
-  /**
-   * Release a previously acquired slot.
-   * If callers are queued, the next one is unblocked synchronously.
-   */
-  release(): void {
-    const next = this.queue.shift()
-    if (next !== undefined) {
-      // A queued caller is waiting — hand the slot directly to it.
-      // `current` stays the same: we consumed the slot immediately.
-      next()
-    } else {
-      this.current--
-    }
-  }
-
-  /**
-   * Run `fn` while holding one slot, automatically releasing it afterward
-   * even if `fn` throws.
-   */
-  async run<T>(fn: () => Promise<T>): Promise<T> {
-    await this.acquire()
-    try {
-      return await fn()
-    } finally {
-      this.release()
-    }
-  }
-
-  /** Number of slots currently in use. */
-  get active(): number {
-    return this.current
-  }
-
-  /** Number of callers waiting for a slot. */
-  get pending(): number {
-    return this.queue.length
-  }
-}

package/tests/semaphore.test.ts

@@ -1,57 +0,0 @@
-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

@@ -1,122 +0,0 @@
-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)
-  })
-})