@jackchen_me/open-multi-agent 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @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';
+/** 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;
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/** 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>;
+}
+/** Static configuration for a single agent. */
+export interface AgentConfig {
+    readonly name: string;
+    readonly model: string;
+    readonly provider?: 'anthropic' | 'openai';
+    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;
+}
+/** 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[];
+}
+/** 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;
+}
+/** 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;
+}
+/** Progress event emitted by the orchestrator during a run. */
+export interface OrchestratorEvent {
+    readonly type: 'agent_start' | 'agent_complete' | 'task_start' | 'task_complete' | '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' | 'openai';
+    onProgress?: (event: OrchestratorEvent) => void;
+}
+/** 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>;
+}
+/** 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * @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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/utils/semaphore.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare class Semaphore {
+    private readonly max;
+    private current;
+    private readonly queue;
+    /**
+     * @param max - Maximum number of concurrent holders. Must be >= 1.
+     */
+    constructor(max: number);
+    /**
+     * Acquire a slot. Resolves immediately when one is free, or waits until a
+     * holder calls `release()`.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release a previously acquired slot.
+     * If callers are queued, the next one is unblocked synchronously.
+     */
+    release(): void;
+    /**
+     * Run `fn` while holding one slot, automatically releasing it afterward
+     * even if `fn` throws.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Number of slots currently in use. */
+    get active(): number;
+    /** Number of callers waiting for a slot. */
+    get pending(): number;
+}
+//# sourceMappingURL=semaphore.d.ts.map

package/dist/utils/semaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../src/utils/semaphore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAOR,OAAO,CAAC,QAAQ,CAAC,GAAG;IANhC,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAE9C;;OAEG;gBAC0B,GAAG,EAAE,MAAM;IAMxC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAWxB;;;OAGG;IACH,OAAO,IAAI,IAAI;IAWf;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS9C,wCAAwC;IACxC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,4CAA4C;IAC5C,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}

package/dist/utils/semaphore.js

@@ -0,0 +1,85 @@
+/**
+ * @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 {
+    max;
+    current = 0;
+    queue = [];
+    /**
+     * @param max - Maximum number of concurrent holders. Must be >= 1.
+     */
+    constructor(max) {
+        this.max = max;
+        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() {
+        if (this.current < this.max) {
+            this.current++;
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            this.queue.push(resolve);
+        });
+    }
+    /**
+     * Release a previously acquired slot.
+     * If callers are queued, the next one is unblocked synchronously.
+     */
+    release() {
+        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(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    /** Number of slots currently in use. */
+    get active() {
+        return this.current;
+    }
+    /** Number of callers waiting for a slot. */
+    get pending() {
+        return this.queue.length;
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/utils/semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../../src/utils/semaphore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAS;IAOS;IANrB,OAAO,GAAG,CAAC,CAAA;IACF,KAAK,GAAsB,EAAE,CAAA;IAE9C;;OAEG;IACH,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;QACtC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAA;QACtE,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,EAAE,CAAA;YACd,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;QAED,OAAO,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;YACjC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;QAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,6DAA6D;YAC7D,8DAA8D;YAC9D,IAAI,EAAE,CAAA;QACR,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAI,EAAoB;QAC/B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACpB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IAED,4CAA4C;IAC5C,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAA;IAC1B,CAAC;CACF"}

package/examples/01-single-agent.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.')