@open-multi-agent/core 1.4.0

package/docs/cli.md

@@ -0,0 +1,265 @@
+# Command-line interface (`oma`)
+
+The package ships a small binary **`oma`** that exposes the same primitives as the TypeScript API: `runTeam`, `runTasks`, plus a static provider reference. It is meant for **shell scripts and CI** (JSON on stdout, stable exit codes).
+
+It does **not** provide an interactive REPL, working-directory injection into tools, human approval gates, or session persistence. Those stay in application code.
+
+## Installation and invocation
+
+After installing the package, the binary is on `PATH` when using `npx` or a local `node_modules/.bin`:
+
+```bash
+npm install @open-multi-agent/core
+npx oma help
+```
+
+From a clone of the repository you need a build first:
+
+```bash
+npm run build
+node dist/cli/oma.js help
+```
+
+Set the usual provider API keys in the environment (see [README](../README.md#quick-start)); the CLI does not read secrets from flags. MiniMax additionally reads `MINIMAX_BASE_URL` to select the global (`https://api.minimax.io/v1`) or China (`https://api.minimaxi.com/v1`) endpoint.
+
+OpenRouter works through the OpenAI-compatible adapter: set `provider` to `openai`, `baseURL` to `https://openrouter.ai/api/v1`, and pass `OPENROUTER_API_KEY` as the agent or orchestrator `apiKey`.
+
+---
+
+## Commands
+
+### `oma run`
+
+Runs **`OpenMultiAgent.runTeam(team, goal)`**: coordinator decomposition, task queue, optional synthesis.
+
+When invoked with `--dashboard`, the **`oma` CLI** writes a static post-execution DAG dashboard HTML to `oma-dashboards/runTeam-<timestamp>.html` under the current working directory (the library does not write files itself; if you want this outside the CLI, call `renderTeamRunDashboard(result)` in application code — see `src/dashboard/render-team-run-dashboard.ts`).
+
+The dashboard page loads **Tailwind CSS** (Play CDN), **Google Fonts** (Space Grotesk, Inter, Material Symbols), and **Material Symbols** from the network at view time. Opening the HTML file requires an **online** environment unless you host or inline those assets yourself (a future improvement).
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--goal` | Yes | Natural-language goal passed to the team run. |
+| `--team` | Yes | Path to JSON (see [Team file](#team-file)). |
+| `--orchestrator` | No | Path to JSON merged into `new OpenMultiAgent(...)` after any orchestrator fragment from the team file. |
+| `--coordinator` | No | Path to JSON passed as `runTeam(..., { coordinator })` (`CoordinatorConfig`). |
+| `--dashboard` | No | Write a post-execution DAG dashboard HTML to `oma-dashboards/runTeam-<timestamp>.html`. |
+
+Global flags: [`--pretty`](#output-flags), [`--include-messages`](#output-flags).
+
+### `oma task`
+
+Runs **`OpenMultiAgent.runTasks(team, tasks)`** with a fixed task list (no coordinator decomposition).
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--file` | Yes | Path to [tasks file](#tasks-file). |
+| `--team` | No | Path to JSON `TeamConfig`. When set, overrides the `team` object inside `--file`. |
+
+Global flags: [`--pretty`](#output-flags), [`--include-messages`](#output-flags).
+
+### `oma provider`
+
+Read-only helper for wiring JSON configs and env vars.
+
+- **`oma provider`** or **`oma provider list`** — Prints JSON: built-in provider ids, API key environment variable names, whether `baseURL` is supported, and short notes (e.g. OpenAI-compatible servers, Copilot in CI).
+- **`oma provider template <provider>`** — Prints a JSON object with example `orchestrator` and `agent` fields plus placeholder `env` entries. `<provider>` is one of: `anthropic`, `openai`, `gemini`, `grok`, `minimax`, `deepseek`, `qiniu`, `copilot`.
+
+For OpenRouter, use the `openai` provider template, set `baseURL` to `https://openrouter.ai/api/v1`, and set `apiKey` from `OPENROUTER_API_KEY` in your JSON config.
+
+Supports `--pretty`.
+
+### `oma`, `oma help`, `oma -h`, `oma --help`
+
+Prints usage text to stdout and exits **0**.
+
+---
+
+## Configuration files
+
+Shapes match the library types `TeamConfig`, `OrchestratorConfig`, `CoordinatorConfig`, and the task objects accepted by `runTasks()`.
+
+### Team file
+
+Used with **`oma run --team`** (and optionally **`oma task --team`**).
+
+**Option A — plain `TeamConfig`**
+
+```json
+{
+  "name": "api-team",
+  "agents": [
+    {
+      "name": "architect",
+      "model": "claude-sonnet-4-6",
+      "provider": "anthropic",
+      "systemPrompt": "You design APIs.",
+      "tools": ["file_read", "file_write"],
+      "maxTurns": 6
+    }
+  ],
+  "sharedMemory": true
+}
+```
+
+**Option B — team plus default orchestrator settings**
+
+```json
+{
+  "team": {
+    "name": "api-team",
+    "agents": [{ "name": "worker", "model": "claude-sonnet-4-6", "systemPrompt": "…" }]
+  },
+  "orchestrator": {
+    "defaultModel": "claude-sonnet-4-6",
+    "defaultProvider": "anthropic",
+    "maxConcurrency": 3
+  }
+}
+```
+
+Validation rules enforced by the CLI:
+
+- Root (or `team`) must be an object.
+- `team.name` is a non-empty string.
+- `team.agents` is a non-empty array; each agent must have non-empty `name` and `model`.
+
+Any other fields are passed through to the library as in TypeScript.
+
+**SDK-only fields**: `sharedMemoryStore` (custom `MemoryStore` instance) cannot be set from JSON since it is a runtime object. Use `sharedMemory: true` for the default in-memory store, or wire a custom store in TypeScript via `orchestrator.createTeam()`.
+
+### Tasks file
+
+Used with **`oma task --file`**.
+
+```json
+{
+  "orchestrator": {
+    "defaultModel": "claude-sonnet-4-6"
+  },
+  "team": {
+    "name": "pipeline",
+    "agents": [
+      { "name": "designer", "model": "claude-sonnet-4-6", "systemPrompt": "…" },
+      { "name": "builder", "model": "claude-sonnet-4-6", "systemPrompt": "…" }
+    ],
+    "sharedMemory": true
+  },
+  "tasks": [
+    {
+      "title": "Design",
+      "description": "Produce a short spec for the feature.",
+      "assignee": "designer"
+    },
+    {
+      "title": "Implement",
+      "description": "Implement from the design.",
+      "assignee": "builder",
+      "dependsOn": ["Design"]
+    }
+  ]
+}
+```
+
+- **`dependsOn`** — Task titles (not internal ids), same convention as the coordinator output in the library.
+- Optional per-task fields: `memoryScope` (`"dependencies"` \| `"all"`), `maxRetries`, `retryDelayMs`, `retryBackoff`.
+- **`tasks`** must be a non-empty array; each item needs string `title` and `description`.
+
+If **`--team path.json`** is passed, the file’s top-level `team` property is ignored and the external file is used instead (useful when the same team definition is shared across several pipeline files).
+
+### Orchestrator and coordinator JSON
+
+These files are arbitrary JSON objects merged into **`OrchestratorConfig`** and **`CoordinatorConfig`**. Function-valued options (`onProgress`, `onApproval`, etc.) cannot appear in JSON and are not supported by the CLI.
+
+---
+
+## Output
+
+### Stdout
+
+Every invocation prints **one JSON document** to stdout, followed by a newline.
+
+**Successful `run` / `task`**
+
+```json
+{
+  "command": "run",
+  "success": true,
+  "totalTokenUsage": { "input_tokens": 0, "output_tokens": 0 },
+  "agentResults": {
+    "architect": {
+      "success": true,
+      "output": "…",
+      "tokenUsage": { "input_tokens": 0, "output_tokens": 0 },
+      "toolCalls": [],
+      "structured": null,
+      "loopDetected": false,
+      "budgetExceeded": false
+    }
+  }
+}
+```
+
+`agentResults` keys are agent names. When an agent ran multiple tasks, the library merges results; the CLI mirrors the merged `AgentRunResult` fields.
+
+**Errors (usage, validation, I/O, runtime)**
+
+```json
+{
+  "error": {
+    "kind": "usage",
+    "message": "--goal and --team are required"
+  }
+}
+```
+
+`kind` is one of: `usage`, `validation`, `io`, `runtime`, or `internal` (uncaught errors in the outer handler).
+
+### Output flags
+
+| Flag | Effect |
+|------|--------|
+| `--pretty` | Pretty-print JSON with indentation. |
+| `--include-messages` | Include each agent’s full `messages` array in `agentResults`. **Very large** for long runs; default is omit. |
+
+There is no separate progress stream; for rich telemetry use the TypeScript API with `onProgress` / `onTrace`.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Success: `run`/`task` finished with `success === true`, or help / `provider` completed normally. |
+| **1** | Run finished but **`success === false`** (agent or task failure as reported by the library). |
+| **2** | Usage, validation, readable JSON errors, or file access issues (e.g. missing file). |
+| **3** | Unexpected error, including typical LLM/API failures surfaced as thrown errors. |
+
+In scripts:
+
+```bash
+npx oma run --goal "Summarize README" --team team.json > result.json
+code=$?
+case $code in
+  0) echo "OK" ;;
+  1) echo "Run reported failure — inspect result.json" ;;
+  2) echo "Bad inputs or files" ;;
+  3) echo "Crash or API error" ;;
+esac
+```
+
+---
+
+## Argument parsing
+
+- Long options only: `--goal`, `--team`, `--file`, etc.
+- Values may be attached with `=`: `--team=./team.json`.
+- Boolean-style flags (`--pretty`, `--include-messages`) take no value; if the next token does not start with `--`, it is treated as the value of the previous option (standard `getopt`-style pairing).
+
+---
+
+## Limitations (by design)
+
+- No TTY session, history, or `stdin` goal input.
+- No built-in **`cwd`** or metadata passed into `ToolUseContext` (tools use process cwd unless the library adds other hooks later).
+- No **`onApproval`** from JSON; non-interactive batch only.
+- Coordinator **`runTeam`** path still requires network and API keys like any other run.

package/docs/context-management.md

@@ -0,0 +1,24 @@
+# Context Management
+
+Long-running agents can hit input token ceilings fast. Set `contextStrategy` on `AgentConfig` to control how the conversation shrinks as it grows:
+
+```typescript
+const agent: AgentConfig = {
+  name: 'long-runner',
+  model: 'claude-sonnet-4-6',
+  // Pick one:
+  contextStrategy: { type: 'sliding-window', maxTurns: 20 },
+  // contextStrategy: { type: 'summarize', maxTokens: 80_000, summaryModel: 'claude-haiku-4-5' },
+  // contextStrategy: { type: 'compact', maxTokens: 100_000, preserveRecentTurns: 4 },
+  // contextStrategy: { type: 'custom', compress: (messages, estimatedTokens) => ... },
+}
+```
+
+| Strategy | When to reach for it |
+|----------|----------------------|
+| `sliding-window` | Cheapest. Keep the last N turns, drop the rest. |
+| `summarize` | Send old turns to a summary model; keep the summary in place of the originals. |
+| `compact` | Rule-based: truncate large assistant text blocks and tool results, keep recent turns intact. No extra LLM call. |
+| `custom` | Supply your own `compress(messages, estimatedTokens)` function. |
+
+Pairs well with `compressToolResults` and `maxToolOutputChars`.

package/docs/featured-partner.md

@@ -0,0 +1,28 @@
+# Featured Partner program
+
+For products and platforms already integrated with `open-multi-agent`. Reserves prominent placement in the [Ecosystem](../README.md#ecosystem) section of the project README for 12 months at a time.
+
+## What you get
+
+- Logo, 100-word description, and a maintainer endorsement quote in a dedicated row above the integrations list.
+- 12-month placement, renewable.
+- Cross-link from the [English](../README.md) and [中文](../README_zh.md) README.
+
+## Eligibility
+
+- Active integration with `open-multi-agent` already in production or a publicly testable beta.
+- Aligned with the project's positioning: TypeScript multi-agent orchestration, agent infrastructure, observability, memory backends, and adjacent tooling.
+
+## Cost
+
+$3,000 USD per partner per 12-month placement. Single partner per slot at a time, renewable on the same terms.
+
+## How to apply
+
+[Open an inquiry issue](https://github.com/open-multi-agent/open-multi-agent/issues/new?title=Featured+Partner+Inquiry&labels=featured-partner-inquiry) with:
+
+- A short description of your product and how it integrates with `open-multi-agent`.
+- A link to the integration code or live deployment.
+- The contact you want us to reply to.
+
+The maintainers will follow up to review and confirm.

package/docs/observability.md

@@ -0,0 +1,56 @@
+# Observability
+
+`open-multi-agent` exposes three telemetry layers: live progress events, structured trace spans, and a static post-run dashboard.
+
+## Progress Events
+
+Use `onProgress` when you need lightweight lifecycle events for logs, terminal output, or a live UI.
+
+```typescript
+const orchestrator = new OpenMultiAgent({
+  onProgress: (event) => {
+    console.log(event.type, event.task ?? event.agent ?? '')
+  },
+})
+```
+
+Common event types include `task_start`, `task_complete`, `task_retry`, `task_skipped`, `agent_start`, `agent_complete`, `budget_exceeded`, and `error`.
+
+## Trace Spans
+
+Use `onTrace` when you need structured spans for LLM calls, tool executions, and tasks. Each span carries parent IDs, durations, token counts, and tool I/O.
+
+```typescript
+const orchestrator = new OpenMultiAgent({
+  onTrace: async (span) => {
+    await traceSink.write(span)
+  },
+})
+```
+
+Forward trace spans to OpenTelemetry, Datadog, Honeycomb, Langfuse, or your own run database. See [`integrations/trace-observability`](../examples/integrations/trace-observability.ts) for a runnable example.
+
+## Post-Run Dashboard
+
+`renderTeamRunDashboard(result)` returns a static HTML page that visualizes the executed task DAG with timing, token usage, per-task status, and task details.
+
+```typescript
+import { writeFileSync } from 'node:fs'
+import { renderTeamRunDashboard } from '@open-multi-agent/core'
+
+const result = await orchestrator.runTeam(team, goal)
+writeFileSync('run.html', renderTeamRunDashboard(result))
+```
+
+The library does not write files by itself. The CLI can write dashboard HTML for you with `oma run --dashboard`; see [docs/cli.md](./cli.md).
+
+The dashboard HTML loads Tailwind CSS and Google Fonts from the network at view time. Opening the generated HTML requires an online environment unless you host or inline those assets yourself.
+
+## What to Persist
+
+For production runs, persist enough data to reconstruct a failure without replaying the entire job:
+
+- `TeamRunResult.tasks` for the executed DAG and task states.
+- `TeamRunResult.totalTokenUsage` for cost attribution.
+- `onTrace` spans for LLM calls and tool executions.
+- The rendered dashboard HTML when you need a shareable post-mortem artifact.

package/docs/providers.md

@@ -0,0 +1,78 @@
+# Providers
+
+`open-multi-agent` keeps the agent config shape stable across hosted, cloud, and local providers. Change `provider`, `model`, and the relevant credential; the rest of your team definition stays the same.
+
+```typescript
+const agent = {
+  name: 'my-agent',
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'You are a helpful assistant.',
+}
+```
+
+## Built-In Provider Shortcuts
+
+The framework ships a wired-in provider name for each of these. Set `provider` and the env var, and the adapter handles the endpoint.
+
+> Under the hood, Anthropic, Gemini, and Bedrock use provider-specific APIs. The other built-in shortcuts are pre-configured wrappers around OpenAI-compatible endpoints; same wire format as the OpenAI-compatible table below, with the `baseURL` already supplied.
+
+| Provider | Config | Env var | Example model | Notes |
+|----------|--------|---------|---------------|-------|
+| Anthropic (Claude) | `provider: 'anthropic'` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` | Native Anthropic SDK. |
+| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | `gemini-2.5-pro` | Native Google GenAI SDK. Requires `npm install @google/genai`. |
+| OpenAI (GPT) | `provider: 'openai'` | `OPENAI_API_KEY` | `gpt-4o` | |
+| Azure OpenAI | `provider: 'azure-openai'` | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` | `gpt-4` | Optional `AZURE_OPENAI_API_VERSION`, `AZURE_OPENAI_DEPLOYMENT`. |
+| GitHub Copilot | `provider: 'copilot'` | `GITHUB_COPILOT_TOKEN` (falls back to `GITHUB_TOKEN`) | `gpt-4o` | Custom token-exchange flow on top of OpenAI protocol. |
+| Grok (xAI) | `provider: 'grok'` | `XAI_API_KEY` | `grok-4` | OpenAI-compatible; endpoint is `api.x.ai/v1`. |
+| DeepSeek | `provider: 'deepseek'` | `DEEPSEEK_API_KEY` | `deepseek-chat` | OpenAI-compatible. `deepseek-chat` (V3, coding) or `deepseek-reasoner` (thinking mode). |
+| MiniMax (global) | `provider: 'minimax'` | `MINIMAX_API_KEY` | `MiniMax-M2.7` | OpenAI-compatible. |
+| MiniMax (China) | `provider: 'minimax'` + `MINIMAX_BASE_URL` | `MINIMAX_API_KEY` | `MiniMax-M2.7` | Set `MINIMAX_BASE_URL=https://api.minimaxi.com/v1`. |
+| Qiniu | `provider: 'qiniu'` | `QINIU_API_KEY` | `deepseek-v3` | OpenAI-compatible. Endpoint `https://api.qnaigc.com/v1`; multiple model families, see [Qiniu AI docs](https://developer.qiniu.com/aitokenapi/12882/ai-inference-api). |
+| AWS Bedrock | `provider: 'bedrock'` | none (AWS SDK credential chain) | `anthropic.claude-3-5-haiku-20241022-v1:0` | No API key. Set `AWS_REGION` or pass `region` as the 4th arg to `createAdapter`. Credentials come from env vars, shared config, or IAM role. Newer Claude models can require a cross-region inference profile prefix such as `us.`. Also supports Llama, Mistral, and Cohere. See [`providers/bedrock`](../examples/providers/bedrock.ts). Requires `npm install @aws-sdk/client-bedrock-runtime`. |
+
+## OpenAI-Compatible Providers
+
+No bundled shortcut is needed when a server speaks OpenAI Chat Completions. Use `provider: 'openai'` and point `baseURL` at the service.
+
+| Service | Config | Env var | Example model | Notes |
+|---------|--------|---------|---------------|-------|
+| Ollama (local) | `provider: 'openai'` + `baseURL: 'http://localhost:11434/v1'` | none | `llama3.1` | |
+| vLLM (local) | `provider: 'openai'` + `baseURL` | none | server-loaded | |
+| LM Studio (local) | `provider: 'openai'` + `baseURL` | none | server-loaded | |
+| llama.cpp server (local) | `provider: 'openai'` + `baseURL` | none | server-loaded | |
+| OpenRouter | `provider: 'openai'` + `baseURL: 'https://openrouter.ai/api/v1'` + `apiKey` | `OPENROUTER_API_KEY` | `openai/gpt-4o-mini` | |
+| Groq | `provider: 'openai'` + `baseURL: 'https://api.groq.com/openai/v1'` | `GROQ_API_KEY` | `llama-3.3-70b-versatile` | |
+| Mistral | `provider: 'openai'` + `baseURL: 'https://api.mistral.ai/v1'` | `MISTRAL_API_KEY` | `mistral-large-latest` | See [`providers/mistral`](../examples/providers/mistral.ts). |
+
+Other services can be connected the same way if they implement the OpenAI Chat Completions API, but they are not listed as verified providers here. For services where the key is not `OPENAI_API_KEY`, pass it explicitly via `apiKey`; otherwise the `openai` adapter falls back to `OPENAI_API_KEY`.
+
+## Local Model Tool-Calling
+
+The framework supports tool-calling with local models served by Ollama, vLLM, LM Studio, or llama.cpp. Tool-calling is handled natively through the OpenAI-compatible API.
+
+Verified local models include Gemma 4, Llama 3.1, Qwen 3, Mistral, and Phi-4. Ollama publishes its tool-capable models at [ollama.com/search?c=tools](https://ollama.com/search?c=tools).
+
+If a local model returns tool calls as text instead of the `tool_calls` wire format, the framework automatically extracts them from the text output. This helps with thinking models or misconfigured local servers.
+
+Use `timeoutMs` on `AgentConfig` for slow local inference:
+
+```typescript
+const localAgent = {
+  name: 'local',
+  model: 'llama3.1',
+  provider: 'openai',
+  baseURL: 'http://localhost:11434/v1',
+  apiKey: 'ollama',
+  tools: ['bash', 'file_read'],
+  timeoutMs: 120_000,
+}
+```
+
+Highly quantized MoE models on consumer hardware can fall into repetition loops or hallucinate tool-call schemas under default sampling. `AgentConfig` exposes `topK`, `minP`, `frequencyPenalty`, `presencePenalty`, `parallelToolCalls`, and `extraBody` for server-specific knobs such as vLLM's `repetition_penalty`. See [`providers/local-quantized`](../examples/providers/local-quantized.ts) for a complete setup.
+
+## Troubleshooting
+
+- Model not calling tools? Confirm it appears in Ollama's [Tools category](https://ollama.com/search?c=tools).
+- Using Ollama? Update to the latest version with `ollama update`.
+- Proxy interfering with local servers? Use `no_proxy=localhost`.

package/docs/shared-memory.md

@@ -0,0 +1,27 @@
+# Shared Memory
+
+Teams can share a namespaced key-value store so later agents see earlier agents' findings. Enable it with a boolean for the default in-process store:
+
+```typescript
+const team = orchestrator.createTeam('research-team', {
+  name: 'research-team',
+  agents: [researcher, writer],
+  sharedMemory: true,
+})
+```
+
+For durable or cross-process backends (Redis, Postgres, Engram, etc.), implement the `MemoryStore` interface and pass it via `sharedMemoryStore`. Keys are still namespaced as `<agentName>/<key>` before reaching the store:
+
+```typescript
+import type { MemoryStore } from '@open-multi-agent/core'
+
+class RedisStore implements MemoryStore { /* get/set/list/delete/clear */ }
+
+const team = orchestrator.createTeam('durable-team', {
+  name: 'durable-team',
+  agents: [researcher, writer],
+  sharedMemoryStore: new RedisStore(),
+})
+```
+
+When both are provided, `sharedMemoryStore` wins. SDK-only: the CLI cannot pass runtime objects.

package/docs/tool-configuration.md

@@ -0,0 +1,152 @@
+# Tool Configuration
+
+Agents can be configured with fine-grained tool access control using presets, allowlists, and denylists.
+
+## Tool Presets
+
+Predefined tool sets for common use cases:
+
+```typescript
+const readonlyAgent: AgentConfig = {
+  name: 'reader',
+  model: 'claude-sonnet-4-6',
+  toolPreset: 'readonly',  // file_read, grep, glob
+}
+
+const readwriteAgent: AgentConfig = {
+  name: 'editor',
+  model: 'claude-sonnet-4-6',
+  toolPreset: 'readwrite',  // file_read, file_write, file_edit, grep, glob
+}
+
+const fullAgent: AgentConfig = {
+  name: 'executor',
+  model: 'claude-sonnet-4-6',
+  toolPreset: 'full',  // file_read, file_write, file_edit, grep, glob, bash
+}
+```
+
+## Advanced Filtering
+
+Combine presets with allowlists and denylists for precise control:
+
+```typescript
+const customAgent: AgentConfig = {
+  name: 'custom',
+  model: 'claude-sonnet-4-6',
+  toolPreset: 'readwrite',        // Start with: file_read, file_write, file_edit, grep, glob
+  tools: ['file_read', 'grep'],   // Allowlist: intersect with preset = file_read, grep
+  disallowedTools: ['grep'],      // Denylist: subtract = file_read only
+}
+```
+
+**Resolution order:** preset → allowlist → denylist → framework safety rails.
+
+## Custom Tools
+
+Two ways to give an agent a tool that is not in the built-in set.
+
+**Inject at config time** via `customTools` on `AgentConfig`. Good when the orchestrator wires up tools centrally. Tools defined here bypass preset/allowlist filtering but still respect `disallowedTools`.
+
+```typescript
+import { defineTool } from '@open-multi-agent/core'
+import { z } from 'zod'
+
+const weatherTool = defineTool({
+  name: 'get_weather',
+  description: 'Look up current weather for a city.',
+  inputSchema: z.object({ city: z.string() }),
+  execute: async ({ city }) => ({ data: await fetchWeather(city) }),
+})
+
+const agent: AgentConfig = {
+  name: 'assistant',
+  model: 'claude-sonnet-4-6',
+  customTools: [weatherTool],
+}
+```
+
+**Register at runtime** via `agent.addTool(tool)`. Tools added this way are always available, regardless of filtering.
+
+## Tool Output Control
+
+Long tool outputs can blow up conversation size and cost. Two controls work together.
+
+**Validation (optional).** Add `outputSchema` to catch malformed tool results before they are forwarded:
+
+> **Note — two different `outputSchema` fields.** The one on `defineTool()` /
+> `ToolDefinition` (shown below) validates a single **tool's** `ToolResult.data`
+> — it is always a `ZodSchema<string>` because tool output is serialised as
+> text. The `outputSchema` on [`AgentConfig`](../examples/patterns/structured-output.ts)
+> is different: it validates the **agent's final answer** as parsed JSON
+> against an arbitrary Zod schema (see _Structured output_ in `examples/`).
+> Different types, different scopes — TypeScript won't warn you if you mix
+> them up, so pick the one that matches the layer you're working at.
+
+```typescript
+const jsonTool = defineTool({
+  name: 'json_tool',
+  description: 'Return JSON payload as string.',
+  inputSchema: z.object({}),
+  outputSchema: z.string().refine((value) => {
+    try {
+      JSON.parse(value)
+      return true
+    } catch {
+      return false
+    }
+  }, 'Output must be valid JSON'),
+  execute: async () => ({ data: '{"ok": true}' }),
+})
+```
+
+**Truncation.** Cap an individual tool result to a head + tail excerpt with a marker in between:
+
+```typescript
+const agent: AgentConfig = {
+  // ...
+  maxToolOutputChars: 10_000, // applies to every tool this agent runs
+}
+
+// Per-tool override (takes priority over AgentConfig.maxToolOutputChars):
+const bigQueryTool = defineTool({
+  // ...
+  maxOutputChars: 50_000,
+})
+```
+
+**Post-consumption compression.** Once the agent has acted on a tool result, compress older copies in the transcript so they stop costing input tokens on every subsequent turn. Error results are never compressed.
+
+```typescript
+const agent: AgentConfig = {
+  // ...
+  compressToolResults: true,                 // default threshold: 500 chars
+  // or: compressToolResults: { minChars: 2_000 }
+}
+```
+
+## MCP Tools (Model Context Protocol)
+
+`open-multi-agent` can connect to stdio MCP servers and expose their tools directly to agents.
+
+```typescript
+import { connectMCPTools } from '@open-multi-agent/core/mcp'
+
+const { tools, disconnect } = await connectMCPTools({
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-github'],
+  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+  namePrefix: 'github',
+})
+
+// Register each MCP tool in your ToolRegistry, then include their names in AgentConfig.tools
+// Don't forget cleanup when done
+await disconnect()
+```
+
+Notes:
+- `@modelcontextprotocol/sdk` is an optional peer dependency, only needed when using MCP.
+- Current transport support is stdio.
+- MCP input validation is delegated to the MCP server (`inputSchema` is `z.any()`).
+
+See [`integrations/mcp-github`](../examples/integrations/mcp-github.ts) for a full runnable setup.