@open-multi-agent/core 1.4.2 → 1.6.0

package/docs/providers.md

@@ -1,80 +0,0 @@
-# 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). |
-| Zhipu GLM | `provider: 'openai'` + `baseURL: 'https://open.bigmodel.cn/api/paas/v4'` | `ZHIPU_API_KEY` | `glm-4-plus` | See [`providers/zhipu`](../examples/providers/zhipu.ts). |
-| Doubao (ByteDance) | `provider: 'openai'` + `baseURL: 'https://ark.cn-beijing.volces.com/api/v3'` | `ARK_API_KEY` | `doubao-1-5-pro-32k-250115` | See [`providers/doubao`](../examples/providers/doubao.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

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

@@ -1,152 +0,0 @@
-# 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.