@jackchen_me/open-multi-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 open-multi-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# Open Multi-Agent
+
+Build AI agent teams that work together. One agent plans, another implements, a third reviews — the framework handles task scheduling, dependencies, and communication automatically.
+
+[![GitHub stars](https://img.shields.io/github/stars/JackChen-me/open-multi-agent)](https://github.com/JackChen-me/open-multi-agent/stargazers)
+[![license](https://img.shields.io/github/license/JackChen-me/open-multi-agent)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
+
+## Why Open Multi-Agent?
+
+- **Multi-Agent Teams** — Define agents with different roles, tools, and even different models. They collaborate through a message bus and shared memory.
+- **Task DAG Scheduling** — Tasks have dependencies. The framework resolves them topologically — dependent tasks wait, independent tasks run in parallel.
+- **Model Agnostic** — Claude and GPT in the same team. Swap models per agent. Bring your own adapter for any LLM.
+- **In-Process Execution** — No subprocess overhead. Everything runs in one Node.js process. Deploy to serverless, Docker, CI/CD.
+
+## Quick Start
+
+```bash
+npm install @jackchen_me/open-multi-agent
+```
+
+Set `ANTHROPIC_API_KEY` (and optionally `OPENAI_API_KEY`) in your environment.
+
+```typescript
+import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
+
+const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
+
+// One agent, one task
+const result = await orchestrator.runAgent(
+  {
+    name: 'coder',
+    model: 'claude-sonnet-4-6',
+    tools: ['bash', 'file_write'],
+  },
+  'Write a TypeScript function that reverses a string, save it to /tmp/reverse.ts, and run it.',
+)
+
+console.log(result.output)
+```
+
+## Multi-Agent Team
+
+This is where it gets interesting. Three agents, one goal:
+
+```typescript
+import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
+import type { AgentConfig } from '@jackchen_me/open-multi-agent'
+
+const architect: AgentConfig = {
+  name: 'architect',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You design clean API contracts and file structures.',
+  tools: ['file_write'],
+}
+
+const developer: AgentConfig = {
+  name: 'developer',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You implement what the architect designs.',
+  tools: ['bash', 'file_read', 'file_write', 'file_edit'],
+}
+
+const reviewer: AgentConfig = {
+  name: 'reviewer',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You review code for correctness and clarity.',
+  tools: ['file_read', 'grep'],
+}
+
+const orchestrator = new OpenMultiAgent({
+  defaultModel: 'claude-sonnet-4-6',
+  onProgress: (event) => console.log(event.type, event.agent ?? event.task ?? ''),
+})
+
+const team = orchestrator.createTeam('api-team', {
+  name: 'api-team',
+  agents: [architect, developer, reviewer],
+  sharedMemory: true,
+})
+
+// Describe a goal — the framework breaks it into tasks and orchestrates execution
+const result = await orchestrator.runTeam(team, 'Create a REST API for a todo list in /tmp/todo-api/')
+
+console.log(`Success: ${result.success}`)
+console.log(`Tokens: ${result.totalTokenUsage.output_tokens} output tokens`)
+```
+
+## More Examples
+
+<details>
+<summary><b>Task Pipeline</b> — explicit control over task graph and assignments</summary>
+
+```typescript
+const result = await orchestrator.runTasks(team, [
+  {
+    title: 'Design the data model',
+    description: 'Write a TypeScript interface spec to /tmp/spec.md',
+    assignee: 'architect',
+  },
+  {
+    title: 'Implement the module',
+    description: 'Read /tmp/spec.md and implement the module in /tmp/src/',
+    assignee: 'developer',
+    dependsOn: ['Design the data model'], // blocked until design completes
+  },
+  {
+    title: 'Write tests',
+    description: 'Read the implementation and write Vitest tests.',
+    assignee: 'developer',
+    dependsOn: ['Implement the module'],
+  },
+  {
+    title: 'Review code',
+    description: 'Review /tmp/src/ and produce a structured code review.',
+    assignee: 'reviewer',
+    dependsOn: ['Implement the module'], // can run in parallel with tests
+  },
+])
+```
+
+</details>
+
+<details>
+<summary><b>Custom Tools</b> — define tools with Zod schemas</summary>
+
+```typescript
+import { z } from 'zod'
+import { defineTool, Agent, ToolRegistry, ToolExecutor, registerBuiltInTools } from '@jackchen_me/open-multi-agent'
+
+const searchTool = defineTool({
+  name: 'web_search',
+  description: 'Search the web and return the top results.',
+  inputSchema: z.object({
+    query: z.string().describe('The search query.'),
+    maxResults: z.number().optional().describe('Number of results (default 5).'),
+  }),
+  execute: async ({ query, maxResults = 5 }) => {
+    const results = await mySearchProvider(query, maxResults)
+    return { data: JSON.stringify(results), isError: false }
+  },
+})
+
+const registry = new ToolRegistry()
+registerBuiltInTools(registry)
+registry.register(searchTool)
+
+const executor = new ToolExecutor(registry)
+const agent = new Agent(
+  { name: 'researcher', model: 'claude-sonnet-4-6', tools: ['web_search'] },
+  registry,
+  executor,
+)
+
+const result = await agent.run('Find the three most recent TypeScript releases.')
+```
+
+</details>
+
+<details>
+<summary><b>Multi-Model Teams</b> — mix Claude and GPT in one workflow</summary>
+
+```typescript
+const claudeAgent: AgentConfig = {
+  name: 'strategist',
+  model: 'claude-opus-4-6',
+  provider: 'anthropic',
+  systemPrompt: 'You plan high-level approaches.',
+  tools: ['file_write'],
+}
+
+const gptAgent: AgentConfig = {
+  name: 'implementer',
+  model: 'gpt-5.4',
+  provider: 'openai',
+  systemPrompt: 'You implement plans as working code.',
+  tools: ['bash', 'file_read', 'file_write'],
+}
+
+const team = orchestrator.createTeam('mixed-team', {
+  name: 'mixed-team',
+  agents: [claudeAgent, gptAgent],
+  sharedMemory: true,
+})
+
+const result = await orchestrator.runTeam(team, 'Build a CLI tool that converts JSON to CSV.')
+```
+
+</details>
+
+<details>
+<summary><b>Streaming Output</b></summary>
+
+```typescript
+import { Agent, ToolRegistry, ToolExecutor, registerBuiltInTools } from '@jackchen_me/open-multi-agent'
+
+const registry = new ToolRegistry()
+registerBuiltInTools(registry)
+const executor = new ToolExecutor(registry)
+
+const agent = new Agent(
+  { name: 'writer', model: 'claude-sonnet-4-6', maxTurns: 3 },
+  registry,
+  executor,
+)
+
+for await (const event of agent.stream('Explain monads in two sentences.')) {
+  if (event.type === 'text' && typeof event.data === 'string') {
+    process.stdout.write(event.data)
+  }
+}
+```
+
+</details>
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  OpenMultiAgent (Orchestrator)                                  │
+│                                                                 │
+│  createTeam()  runTeam()  runTasks()  runAgent()  getStatus()   │
+└──────────────────────┬──────────────────────────────────────────┘
+                       │
+            ┌──────────▼──────────┐
+            │  Team               │
+            │  - AgentConfig[]    │
+            │  - MessageBus       │
+            │  - TaskQueue        │
+            │  - SharedMemory     │
+            └──────────┬──────────┘
+                       │
+         ┌─────────────┴─────────────┐
+         │                           │
+┌────────▼──────────┐    ┌───────────▼───────────┐
+│  AgentPool        │    │  TaskQueue             │
+│  - Semaphore      │    │  - dependency graph    │
+│  - runParallel()  │    │  - auto unblock        │
+└────────┬──────────┘    │  - cascade failure     │
+         │               └───────────────────────┘
+┌────────▼──────────┐
+│  Agent            │
+│  - run()          │    ┌──────────────────────┐
+│  - prompt()       │───►│  LLMAdapter          │
+│  - stream()       │    │  - AnthropicAdapter  │
+└────────┬──────────┘    │  - OpenAIAdapter     │
+         │               └──────────────────────┘
+┌────────▼──────────┐
+│  AgentRunner      │    ┌──────────────────────┐
+│  - conversation   │───►│  ToolRegistry        │
+│    loop           │    │  - defineTool()      │
+│  - tool dispatch  │    │  - 5 built-in tools  │
+└───────────────────┘    └──────────────────────┘
+```
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Execute shell commands. Returns stdout + stderr. Supports timeout and cwd. |
+| `file_read` | Read file contents at an absolute path. Supports offset/limit for large files. |
+| `file_write` | Write or create a file. Auto-creates parent directories. |
+| `file_edit` | Edit a file by replacing an exact string match. |
+| `grep` | Search file contents with regex. Uses ripgrep when available, falls back to Node.js. |
+
+## Contributing
+
+Issues, feature requests, and PRs are welcome. Some areas where contributions would be especially valuable:
+
+- **LLM Adapters** — Ollama, llama.cpp, vLLM, Gemini. The `LLMAdapter` interface requires just two methods: `chat()` and `stream()`.
+- **Examples** — Real-world workflows and use cases.
+- **Documentation** — Guides, tutorials, and API docs.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date)](https://star-history.com/#JackChen-me/open-multi-agent&Date)
+
+## License
+
+MIT

package/dist/agent/agent.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview High-level Agent class for open-multi-agent.
+ *
+ * {@link Agent} is the primary interface most consumers interact with.
+ * It wraps {@link AgentRunner} with:
+ *  - Persistent conversation history (`prompt()`)
+ *  - Fresh-conversation semantics (`run()`)
+ *  - Streaming support (`stream()`)
+ *  - Dynamic tool registration at runtime
+ *  - Full lifecycle state tracking (`idle → running → completed | error`)
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({
+ *   name: 'researcher',
+ *   model: 'claude-opus-4-6',
+ *   systemPrompt: 'You are a rigorous research assistant.',
+ *   tools: ['web_search', 'read_file'],
+ * })
+ *
+ * const result = await agent.run('Summarise the last 3 IPCC reports.')
+ * console.log(result.output)
+ * ```
+ */
+import type { AgentConfig, AgentState, AgentRunResult, LLMMessage, StreamEvent, ToolUseContext } from '../types.js';
+import type { ToolDefinition as FrameworkToolDefinition, ToolRegistry } from '../tool/framework.js';
+import type { ToolExecutor } from '../tool/executor.js';
+/**
+ * High-level wrapper around {@link AgentRunner} that manages conversation
+ * history, state transitions, and tool lifecycle.
+ */
+export declare class Agent {
+    readonly name: string;
+    readonly config: AgentConfig;
+    private runner;
+    private state;
+    private readonly _toolRegistry;
+    private readonly _toolExecutor;
+    private messageHistory;
+    /**
+     * @param config       - Static configuration for this agent.
+     * @param toolRegistry - Registry used to resolve and manage tools.
+     * @param toolExecutor - Executor that dispatches tool calls.
+     *
+     * `toolRegistry` and `toolExecutor` are injected rather than instantiated
+     * internally so that teams of agents can share a single registry.
+     */
+    constructor(config: AgentConfig, toolRegistry: ToolRegistry, toolExecutor: ToolExecutor);
+    /**
+     * Lazily create the {@link AgentRunner}.
+     *
+     * The adapter is created asynchronously (it may lazy-import provider SDKs),
+     * so we defer construction until the first `run` / `prompt` / `stream` call.
+     */
+    private getRunner;
+    /**
+     * Run `prompt` in a fresh conversation (history is NOT used).
+     *
+     * Equivalent to constructing a brand-new messages array `[{ role:'user', … }]`
+     * and calling the runner once. The agent's persistent history is not modified.
+     *
+     * Use this for one-shot queries where past context is irrelevant.
+     */
+    run(prompt: string): Promise<AgentRunResult>;
+    /**
+     * Run `prompt` as part of the ongoing conversation.
+     *
+     * Appends the user message to the persistent history, runs the agent, then
+     * appends the resulting messages to the history for the next call.
+     *
+     * Use this for multi-turn interactions.
+     */
+    prompt(message: string): Promise<AgentRunResult>;
+    /**
+     * Stream a fresh-conversation response, yielding {@link StreamEvent}s.
+     *
+     * Like {@link run}, this does not use or update the persistent history.
+     */
+    stream(prompt: string): AsyncGenerator<StreamEvent>;
+    /** Return a snapshot of the current agent state (does not clone nested objects). */
+    getState(): AgentState;
+    /** Return a copy of the persistent message history. */
+    getHistory(): LLMMessage[];
+    /**
+     * Clear the persistent conversation history and reset state to `idle`.
+     * Does NOT discard the runner instance — the adapter connection is reused.
+     */
+    reset(): void;
+    /**
+     * Register a new tool with this agent's tool registry at runtime.
+     *
+     * The tool becomes available to the next LLM call — no restart required.
+     */
+    addTool(tool: FrameworkToolDefinition): void;
+    /**
+     * Deregister a tool by name.
+     * If the tool is not registered this is a no-op (no error is thrown).
+     */
+    removeTool(name: string): void;
+    /** Return the names of all currently registered tools. */
+    getTools(): string[];
+    /**
+     * Shared execution path used by both `run` and `prompt`.
+     * Handles state transitions and error wrapping.
+     */
+    private executeRun;
+    /**
+     * Shared streaming path used by `stream`.
+     * Handles state transitions and error wrapping.
+     */
+    private executeStream;
+    private transitionTo;
+    private transitionToError;
+    private toAgentRunResult;
+    /**
+     * Build a {@link ToolUseContext} that identifies this agent.
+     * Exposed so team orchestrators can inject richer context (e.g. `TeamInfo`).
+     */
+    buildToolContext(abortSignal?: AbortSignal): ToolUseContext;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EAEX,cAAc,EACf,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,cAAc,IAAI,uBAAuB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAqBvD;;;GAGG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAE5B,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;IAC5C,OAAO,CAAC,cAAc,CAAmB;IAEzC;;;;;;;OAOG;gBAED,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY;IAkB5B;;;;;OAKG;YACW,SAAS;IAiCvB;;;;;;;OAOG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAQlD;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBtD;;;;OAIG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,WAAW,CAAC;IAY1D,oFAAoF;IACpF,QAAQ,IAAI,UAAU;IAItB,uDAAuD;IACvD,UAAU,IAAI,UAAU,EAAE;IAI1B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAab;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI;IAI5C;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,0DAA0D;IAC1D,QAAQ,IAAI,MAAM,EAAE;IAQpB;;;OAGG;YACW,UAAU;IA+BxB;;;OAGG;YACY,aAAa;IA+B5B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,gBAAgB;IAiBxB;;;OAGG;IACH,gBAAgB,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,cAAc;CAU5D"}