@jackchen_me/open-multi-agent 0.2.0 → 1.0.0

package/.github/workflows/ci.yml

@@ -18,6 +18,6 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
-      - run: npm ci
+      - run: rm -f package-lock.json && npm install
       - run: npm run lint
       - run: npm test

package/CLAUDE.md

@@ -12,7 +12,7 @@ npm test               # Run all tests (vitest run)
 npm run test:watch     # Vitest watch mode
 ```
 
-No test files exist yet in `tests/`. Examples in `examples/` are standalone scripts requiring API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
+Tests live in `tests/` (vitest). Examples in `examples/` are standalone scripts requiring API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
 
 ## Architecture
 
@@ -41,7 +41,7 @@ This is the framework's key feature. When `runTeam()` is called:
 |-------|-------|----------------|
 | Orchestrator | `orchestrator/orchestrator.ts`, `orchestrator/scheduler.ts` | Top-level API, task decomposition, coordinator pattern |
 | Team | `team/team.ts`, `team/messaging.ts` | Agent roster, MessageBus (point-to-point + broadcast), SharedMemory binding |
-| Agent | `agent/agent.ts`, `agent/runner.ts`, `agent/pool.ts` | Agent lifecycle (idle→running→completed/error), conversation loop, concurrency pool with Semaphore |
+| Agent | `agent/agent.ts`, `agent/runner.ts`, `agent/pool.ts`, `agent/structured-output.ts` | Agent lifecycle (idle→running→completed/error), conversation loop, concurrency pool with Semaphore, structured output validation |
 | Task | `task/queue.ts`, `task/task.ts` | Dependency-aware queue, auto-unblock on completion, cascade failure to dependents |
 | Tool | `tool/framework.ts`, `tool/executor.ts`, `tool/built-in/` | `defineTool()` with Zod schemas, ToolRegistry, parallel batch execution with concurrency semaphore |
 | LLM | `llm/adapter.ts`, `llm/anthropic.ts`, `llm/openai.ts` | `LLMAdapter` interface (`chat` + `stream`), factory `createAdapter()` |
@@ -57,10 +57,18 @@ This is the framework's key feature. When `runTeam()` is called:
 
 Two independent semaphores: `AgentPool` (max concurrent agent runs, default 5) and `ToolExecutor` (max concurrent tool calls, default 4).
 
+### Structured Output
+
+Optional `outputSchema` (Zod) on `AgentConfig`. When set, the agent's final output is parsed as JSON and validated. On validation failure, one retry with error feedback is attempted. Validated data is available via `result.structured`. Logic lives in `agent/structured-output.ts`, wired into `Agent.executeRun()`.
+
+### Task Retry
+
+Optional `maxRetries`, `retryDelayMs`, `retryBackoff` on task config (used via `runTasks()`). `executeWithRetry()` in `orchestrator.ts` handles the retry loop with exponential backoff (capped at 30s). Token usage is accumulated across all attempts. Emits `task_retry` event via `onProgress`.
+
 ### Error Handling
 
 - Tool errors → caught, returned as `ToolResult(isError: true)`, never thrown
-- Task failures → cascade to all dependents; independent tasks continue
+- Task failures → retry if `maxRetries > 0`, then cascade to all dependents; independent tasks continue
 - LLM API errors → propagate to caller
 
 ### Built-in Tools

package/README.md

@@ -1,24 +1,29 @@
 # Open Multi-Agent
 
-Build AI agent teams that decompose goals into tasks automatically. Define agents with roles and tools, describe a goal — the framework plans the task graph, schedules dependencies, and runs everything in parallel.
+TypeScript framework for multi-agent orchestration. One `runTeam()` call from goal to result — the framework decomposes it into tasks, resolves dependencies, and runs agents in parallel.
 
-3 runtime dependencies. 27 source files. One `runTeam()` call from goal to result.
+3 runtime dependencies · 33 source files · Deploys anywhere Node.js runs · Mentioned in [Latent Space](https://www.latent.space/p/ainews-a-quiet-april-fools) AI News
 
 [![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/)
+[![coverage](https://img.shields.io/badge/coverage-71%25-brightgreen)](https://github.com/JackChen-me/open-multi-agent/actions)
 
 **English** | [中文](./README_zh.md)
 
 ## Why Open Multi-Agent?
 
-- **Auto Task Decomposition** — Describe a goal in plain text. A built-in coordinator agent breaks it into a task DAG with dependencies and assignees — no manual orchestration needed.
-- **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, GPT, Gemma 4, and local models (Ollama, vLLM, LM Studio) in the same team. Swap models per agent via `baseURL`.
+- **Goal In, Result Out** — `runTeam(team, "Build a REST API")`. A coordinator agent auto-decomposes the goal into a task DAG with dependencies and assignees, runs independent tasks in parallel, and synthesizes the final output. No manual task definitions or graph wiring required.
+- **TypeScript-Native** — Built for the Node.js ecosystem. `npm install`, import, run. No Python runtime, no subprocess bridge, no sidecar services. Embed in Express, Next.js, serverless functions, or CI/CD pipelines.
+- **Auditable and Lightweight** — 3 runtime dependencies (`@anthropic-ai/sdk`, `openai`, `zod`). 33 source files. The entire codebase is readable in an afternoon.
+- **Model Agnostic** — Claude, GPT, Gemma 4, and local models (Ollama, vLLM, LM Studio, llama.cpp server) in the same team. Swap models per agent via `baseURL`.
+- **Multi-Agent Collaboration** — Agents with different roles, tools, and models collaborate through a message bus and shared memory.
 - **Structured Output** — Add `outputSchema` (Zod) to any agent. Output is parsed as JSON, validated, and auto-retried once on failure. Access typed results via `result.structured`.
 - **Task Retry** — Set `maxRetries` on tasks for automatic retry with exponential backoff. Failed attempts accumulate token usage for accurate billing.
-- **In-Process Execution** — No subprocess overhead. Everything runs in one Node.js process. Deploy to serverless, Docker, CI/CD.
+- **Human-in-the-Loop** — Optional `onApproval` callback on `runTasks()`. After each batch of tasks completes, your callback decides whether to proceed or abort remaining work.
+- **Lifecycle Hooks** — `beforeRun` / `afterRun` on `AgentConfig`. Intercept the prompt before execution or post-process results after. Throw from either hook to abort.
+- **Loop Detection** — `loopDetection` on `AgentConfig` catches stuck agents repeating the same tool calls or text output. Configurable action: warn (default), terminate, or custom callback.
+- **Observability** — Optional `onTrace` callback emits structured spans for every LLM call, tool execution, task, and agent run — with timing, token usage, and a shared `runId` for correlation. Zero overhead when not subscribed, zero extra dependencies.
 
 ## Quick Start
 
@@ -28,7 +33,12 @@ Requires Node.js >= 18.
 npm install @jackchen_me/open-multi-agent
 ```
 
-Set `ANTHROPIC_API_KEY` (and optionally `OPENAI_API_KEY` or `GITHUB_TOKEN` for Copilot) in your environment. Local models via Ollama require no API key — see [example 06](examples/06-local-model.ts).
+Set the API key for your provider. Local models via Ollama require no API key — see [example 06](examples/06-local-model.ts).
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY`
+- `GITHUB_TOKEN` (for Copilot)
 
 Three agents, one goal — the framework handles the rest:
 
@@ -100,12 +110,6 @@ Tokens: 12847 output tokens
 | Auto-orchestrated team | `runTeam()` | Give a goal, framework plans and executes |
 | Explicit pipeline | `runTasks()` | You define the task graph and assignments |
 
-## Contributors
-
-<a href="https://github.com/JackChen-me/open-multi-agent/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=JackChen-me/open-multi-agent" />
-</a>
-
 ## Examples
 
 All examples are runnable scripts in [`examples/`](./examples/). Run any of them with `npx tsx`:
@@ -123,8 +127,12 @@ npx tsx examples/01-single-agent.ts
 | [05 — Copilot](examples/05-copilot-test.ts) | GitHub Copilot as an LLM provider |
 | [06 — Local Model](examples/06-local-model.ts) | Ollama + Claude in one pipeline via `baseURL` (works with vLLM, LM Studio, etc.) |
 | [07 — Fan-Out / Aggregate](examples/07-fan-out-aggregate.ts) | `runParallel()` MapReduce — 3 analysts in parallel, then synthesize |
-| [08 — Gemma 4 Local](examples/08-gemma4-local.ts) | Pure-local Gemma 4 agent team with tool-calling — zero API cost |
-| [09 — Gemma 4 Auto-Orchestration](examples/09-gemma4-auto-orchestration.ts) | `runTeam()` with Gemma 4 as coordinator — auto task decomposition, fully local |
+| [08 — Gemma 4 Local](examples/08-gemma4-local.ts) | `runTasks()` + `runTeam()` with local Gemma 4 via Ollama — zero API cost |
+| [09 — Structured Output](examples/09-structured-output.ts) | `outputSchema` (Zod) on AgentConfig — validated JSON via `result.structured` |
+| [10 — Task Retry](examples/10-task-retry.ts) | `maxRetries` / `retryDelayMs` / `retryBackoff` with `task_retry` progress events |
+| [11 — Trace Observability](examples/11-trace-observability.ts) | `onTrace` callback — structured spans for LLM calls, tools, tasks, and agents |
+| [12 — Grok](examples/12-grok.ts) | Same as example 02 (`runTeam()` collaboration) with Grok (`XAI_API_KEY`) |
+| [13 — Gemini](examples/13-gemini.ts) | Gemini adapter smoke test with `gemini-2.5-flash` (`GEMINI_API_KEY`) |
 
 ## Architecture
 
@@ -158,6 +166,8 @@ npx tsx examples/01-single-agent.ts
 │  - stream()       │    │  - AnthropicAdapter  │
 └────────┬──────────┘    │  - OpenAIAdapter     │
          │               │  - CopilotAdapter    │
+         │               │  - GeminiAdapter     │
+         │               │  - GrokAdapter       │
          │               └──────────────────────┘
 ┌────────▼──────────┐
 │  AgentRunner      │    ┌──────────────────────┐
@@ -183,12 +193,55 @@ npx tsx examples/01-single-agent.ts
 |----------|--------|---------|--------|
 | Anthropic (Claude) | `provider: 'anthropic'` | `ANTHROPIC_API_KEY` | Verified |
 | OpenAI (GPT) | `provider: 'openai'` | `OPENAI_API_KEY` | Verified |
+| Grok (xAI)   | `provider: 'grok'` | `XAI_API_KEY` | Verified |
 | GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | Verified |
+| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | Verified |
 | Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | Verified |
+| llama.cpp server | `provider: 'openai'` + `baseURL` | — | Verified |
 
 Verified local models with tool-calling: **Gemma 4** (see [example 08](examples/08-gemma4-local.ts)).
 
-Any OpenAI-compatible API should work via `provider: 'openai'` + `baseURL` (DeepSeek, Groq, Mistral, Qwen, MiniMax, etc.). These providers have not been fully verified yet — contributions welcome via [#25](https://github.com/JackChen-me/open-multi-agent/issues/25).
+Any OpenAI-compatible API should work via `provider: 'openai'` + `baseURL` (DeepSeek, Groq, Mistral, Qwen, MiniMax, etc.). **Grok now has first-class support** via `provider: 'grok'`.
+
+### 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 by these servers via the OpenAI-compatible API.
+
+**Verified models:** Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4. See the full list at [ollama.com/search?c=tools](https://ollama.com/search?c=tools).
+
+**Fallback extraction:** If a local model returns tool calls as text instead of using the `tool_calls` wire format (common with thinking models or misconfigured servers), the framework automatically extracts them from the text output.
+
+**Timeout:** Local inference can be slow. Use `timeoutMs` on `AgentConfig` to prevent indefinite hangs:
+
+```typescript
+const localAgent: AgentConfig = {
+  name: 'local',
+  model: 'llama3.1',
+  provider: 'openai',
+  baseURL: 'http://localhost:11434/v1',
+  apiKey: 'ollama',
+  tools: ['bash', 'file_read'],
+  timeoutMs: 120_000, // abort after 2 minutes
+}
+```
+
+**Troubleshooting:**
+- Model not calling tools? Ensure it appears in Ollama's [Tools category](https://ollama.com/search?c=tools). Not all models support tool-calling.
+- Using Ollama? Update to the latest version (`ollama update`) — older versions have known tool-calling bugs.
+- Proxy interfering? Use `no_proxy=localhost` when running against local servers.
+
+### LLM Configuration Examples
+
+```typescript
+const grokAgent: AgentConfig = {
+  name: 'grok-agent',
+  provider: 'grok',
+  model: 'grok-4',
+  systemPrompt: 'You are a helpful assistant.',
+}
+```
+
+(Set your `XAI_API_KEY` environment variable — no `baseURL` needed anymore.)
 
 ## Contributing
 
@@ -198,16 +251,30 @@ Issues, feature requests, and PRs are welcome. Some areas where contributions wo
 - **Examples** — Real-world workflows and use cases.
 - **Documentation** — Guides, tutorials, and API docs.
 
+## Author
+
+> JackChen — Ex PM (¥100M+ revenue), now indie builder. Follow on [X](https://x.com/JackChen_x) for AI Agent insights.
+
+## Contributors
+
+<a href="https://github.com/JackChen-me/open-multi-agent/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=JackChen-me/open-multi-agent&v=20260405" />
+</a>
+
 ## Star History
 
 <a href="https://star-history.com/#JackChen-me/open-multi-agent&Date">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&theme=dark&v=20260403" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260403" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260403" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&theme=dark&v=20260405" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260405" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260405" />
  </picture>
 </a>
 
+## Translations
+
+Help translate this README — [open a PR](https://github.com/JackChen-me/open-multi-agent/pulls).
+
 ## License
 
 MIT

package/README_zh.md

@@ -1,24 +1,29 @@
 # Open Multi-Agent
 
-构建能自动拆解目标的 AI 智能体团队。定义智能体的角色和工具，描述一个目标——框架自动规划任务图、调度依赖、并行执行。
+TypeScript 多智能体编排框架。一次 `runTeam()` 调用从目标到结果——框架自动拆解任务、解析依赖、并行执行。
 
-3 个运行时依赖，27 个源文件，一次 `runTeam()` 调用从目标到结果。
+3 个运行时依赖 · 33 个源文件 · Node.js 能跑的地方都能部署 · 被 [Latent Space](https://www.latent.space/p/ainews-a-quiet-april-fools) AI News 提及（AI 工程领域头部 Newsletter，17 万+订阅者）
 
 [![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/)
+[![coverage](https://img.shields.io/badge/coverage-71%25-brightgreen)](https://github.com/JackChen-me/open-multi-agent/actions)
 
 [English](./README.md) | **中文**
 
 ## 为什么选择 Open Multi-Agent？
 
-- **自动任务拆解** — 用自然语言描述目标，内置的协调者智能体自动将其拆解为带依赖关系和分配的任务图——无需手动编排。
-- **多智能体团队** — 定义不同角色、工具甚至不同模型的智能体。它们通过消息总线和共享内存协作。
-- **任务 DAG 调度** — 任务之间存在依赖关系。框架进行拓扑排序——有依赖的任务等待，无依赖的任务并行执行。
-- **模型无关** — Claude、GPT、Gemma 4 和本地模型（Ollama、vLLM、LM Studio）可以在同一个团队中使用。通过 `baseURL` 即可接入任何 OpenAI 兼容服务。
+- **目标进，结果出** — `runTeam(team, "构建一个 REST API")`。协调者智能体自动将目标拆解为带依赖关系的任务图，分配给对应智能体，独立任务并行执行，最终合成输出。无需手动定义任务或编排流程图。
+- **TypeScript 原生** — 为 Node.js 生态而生。`npm install` 即用，无需 Python 运行时、无子进程桥接、无额外基础设施。可嵌入 Express、Next.js、Serverless 函数或 CI/CD 流水线。
+- **可审计、极轻量** — 3 个运行时依赖（`@anthropic-ai/sdk`、`openai`、`zod`），33 个源文件。一个下午就能读完全部源码。
+- **模型无关** — Claude、GPT、Gemma 4 和本地模型（Ollama、vLLM、LM Studio、llama.cpp server）可以在同一个团队中使用。通过 `baseURL` 即可接入任何 OpenAI 兼容服务。
+- **多智能体协作** — 定义不同角色、工具和模型的智能体，通过消息总线和共享内存协作。
 - **结构化输出** — 为任意智能体添加 `outputSchema`（Zod），输出自动解析为 JSON 并校验，校验失败自动重试一次。通过 `result.structured` 获取类型化结果。
 - **任务重试** — 为任务设置 `maxRetries`，失败时自动指数退避重试。所有尝试的 token 用量累计，确保计费准确。
-- **进程内执行** — 没有子进程开销。所有内容在一个 Node.js 进程中运行。可部署到 Serverless、Docker、CI/CD。
+- **人机协同** — `runTasks()` 支持可选的 `onApproval` 回调。每批任务完成后，由你的回调决定是否继续执行后续任务。
+- **生命周期钩子** — `AgentConfig` 上的 `beforeRun` / `afterRun`。在执行前拦截 prompt，或在执行后处理结果。从钩子中 throw 可中止运行。
+- **循环检测** — `AgentConfig` 上的 `loopDetection` 可检测智能体重复相同工具调用或文本输出的卡死循环。可配置行为：警告（默认）、终止、或自定义回调。
+- **可观测性** — 可选的 `onTrace` 回调为每次 LLM 调用、工具执行、任务和智能体运行发出结构化 span 事件——包含耗时、token 用量和共享的 `runId` 用于关联追踪。未订阅时零开销，零额外依赖。
 
 ## 快速开始
 
@@ -28,7 +33,13 @@
 npm install @jackchen_me/open-multi-agent
 ```
 
-在环境变量中设置 `ANTHROPIC_API_KEY`（以及可选的 `OPENAI_API_KEY` 或用于 Copilot 的 `GITHUB_TOKEN`）。通过 Ollama 使用本地模型无需 API key — 参见 [example 06](examples/06-local-model.ts)。
+根据使用的 Provider 设置对应的 API key。通过 Ollama 使用本地模型无需 API key — 参见 [example 06](examples/06-local-model.ts)。
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY`
+- `XAI_API_KEY`（Grok）
+- `GITHUB_TOKEN`（Copilot）
 
 三个智能体，一个目标——框架处理剩下的一切：
 
@@ -92,10 +103,6 @@ Success: true
 Tokens: 12847 output tokens
 ```
 
-## 作者
-
-> JackChen — 前 WPS 产品经理，现独立创业者。关注小红书[「杰克西｜硅基杠杆」](https://www.xiaohongshu.com/user/profile/5a1bdc1e4eacab4aa39ea6d6)，持续获取我的 AI Agent 观点和思考。
-
 ## 三种运行模式
 
 | 模式 | 方法 | 适用场景 |
@@ -104,12 +111,6 @@ Tokens: 12847 output tokens
 | 自动编排团队 | `runTeam()` | 给一个目标，框架自动规划和执行 |
 | 显式任务管线 | `runTasks()` | 你自己定义任务图和分配 |
 
-## 贡献者
-
-<a href="https://github.com/JackChen-me/open-multi-agent/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=JackChen-me/open-multi-agent" />
-</a>
-
 ## 示例
 
 所有示例都是可运行脚本，位于 [`examples/`](./examples/) 目录。使用 `npx tsx` 运行：
@@ -127,8 +128,12 @@ npx tsx examples/01-single-agent.ts
 | [05 — Copilot](examples/05-copilot-test.ts) | GitHub Copilot 作为 LLM 提供者 |
 | [06 — 本地模型](examples/06-local-model.ts) | Ollama + Claude 混合流水线，通过 `baseURL` 接入（兼容 vLLM、LM Studio 等） |
 | [07 — 扇出聚合](examples/07-fan-out-aggregate.ts) | `runParallel()` MapReduce — 3 个分析师并行，然后综合 |
-| [08 — Gemma 4 本地](examples/08-gemma4-local.ts) | 纯本地 Gemma 4 智能体团队 + tool-calling — 零 API 费用 |
-| [09 — Gemma 4 自动编排](examples/09-gemma4-auto-orchestration.ts) | `runTeam()` 用 Gemma 4 当 coordinator — 自动任务拆解，完全本地 |
+| [08 — Gemma 4 本地](examples/08-gemma4-local.ts) | `runTasks()` + `runTeam()` 本地 Gemma 4 via Ollama — 零 API 费用 |
+| [09 — 结构化输出](examples/09-structured-output.ts) | `outputSchema`（Zod）— 校验 JSON 输出，通过 `result.structured` 获取 |
+| [10 — 任务重试](examples/10-task-retry.ts) | `maxRetries` / `retryDelayMs` / `retryBackoff` + `task_retry` 进度事件 |
+| [11 — 可观测性](examples/11-trace-observability.ts) | `onTrace` 回调 — LLM 调用、工具、任务、智能体的结构化 span 事件 |
+| [12 — Grok](examples/12-grok.ts) | 同示例 02（`runTeam()` 团队协作），使用 Grok（`XAI_API_KEY`） |
+| [13 — Gemini](examples/13-gemini.ts) | Gemini 适配器测试，使用 `gemini-2.5-flash`（`GEMINI_API_KEY`） |
 
 ## 架构
 
@@ -162,6 +167,8 @@ npx tsx examples/01-single-agent.ts
 │  - stream()       │    │  - AnthropicAdapter  │
 └────────┬──────────┘    │  - OpenAIAdapter     │
          │               │  - CopilotAdapter    │
+         │               │  - GeminiAdapter     │
+         │               │  - GrokAdapter       │
          │               └──────────────────────┘
 ┌────────▼──────────┐
 │  AgentRunner      │    ┌──────────────────────┐
@@ -187,28 +194,81 @@ npx tsx examples/01-single-agent.ts
 |----------|------|----------|------|
 | Anthropic (Claude) | `provider: 'anthropic'` | `ANTHROPIC_API_KEY` | 已验证 |
 | OpenAI (GPT) | `provider: 'openai'` | `OPENAI_API_KEY` | 已验证 |
+| Grok (xAI)   | `provider: 'grok'` | `XAI_API_KEY` | 已验证 |
 | GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | 已验证 |
+| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | 已验证 |
 | Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | 已验证 |
+| llama.cpp server | `provider: 'openai'` + `baseURL` | — | 已验证 |
 
 已验证支持 tool-calling 的本地模型：**Gemma 4**（见[示例 08](examples/08-gemma4-local.ts)）。
 
-任何 OpenAI 兼容 API 均可通过 `provider: 'openai'` + `baseURL` 接入（DeepSeek、Groq、Mistral、Qwen、MiniMax 等）。这些 Provider 尚未完整验证——欢迎通过 [#25](https://github.com/JackChen-me/open-multi-agent/issues/25) 贡献验证。
+任何 OpenAI 兼容 API 均可通过 `provider: 'openai'` + `baseURL` 接入（DeepSeek、Groq、Mistral、Qwen、MiniMax 等）。**Grok 现已原生支持**，使用 `provider: 'grok'`。
+
+### 本地模型 Tool-Calling
+
+框架支持通过 Ollama、vLLM、LM Studio 或 llama.cpp 运行的本地模型进行 tool-calling。Tool-calling 由这些服务通过 OpenAI 兼容 API 原生处理。
+
+**已验证模型：** Gemma 4、Llama 3.1、Qwen 3、Mistral、Phi-4。完整列表见 [ollama.com/search?c=tools](https://ollama.com/search?c=tools)。
+
+**兜底提取：** 如果本地模型以文本形式返回工具调用，而非使用 `tool_calls` 协议格式（常见于 thinking 模型或配置不当的服务），框架会自动从文本输出中提取。
+
+**超时设置：** 本地推理可能较慢。使用 `AgentConfig` 上的 `timeoutMs` 防止无限等待：
+
+```typescript
+const localAgent: AgentConfig = {
+  name: 'local',
+  model: 'llama3.1',
+  provider: 'openai',
+  baseURL: 'http://localhost:11434/v1',
+  apiKey: 'ollama',
+  tools: ['bash', 'file_read'],
+  timeoutMs: 120_000, // 2 分钟后中止
+}
+```
+
+**常见问题：**
+- 模型不调用工具？确保该模型出现在 Ollama 的 [Tools 分类](https://ollama.com/search?c=tools)中。并非所有模型都支持 tool-calling。
+- 使用 Ollama？更新到最新版（`ollama update`）——旧版本有已知的 tool-calling bug。
+- 代理干扰？本地服务使用 `no_proxy=localhost`。
+
+### LLM 配置示例
+
+```typescript
+const grokAgent: AgentConfig = {
+  name: 'grok-agent',
+  provider: 'grok',
+  model: 'grok-4',
+  systemPrompt: 'You are a helpful assistant.',
+}
+```
+
+（设置 `XAI_API_KEY` 环境变量即可，无需 `baseURL`。）
 
 ## 参与贡献
 
 欢迎提 Issue、功能需求和 PR。以下方向的贡献尤其有价值：
 
-- **Provider 集成** — 验证并文档化 OpenAI 兼容 Provider（DeepSeek、Groq、Qwen、MiniMax 等）通过 `baseURL` 接入。详见 [#25](https://github.com/JackChen-me/open-multi-agent/issues/25)。对于非 OpenAI 兼容的 Provider（如 Gemini），欢迎贡献新的 `LLMAdapter` 实现——接口只需两个方法：`chat()` 和 `stream()`。
+- **Provider 集成** — 验证并文档化 OpenAI 兼容 Provider（DeepSeek、Groq、Qwen、MiniMax 等）通过 `baseURL` 接入。详见 [#25](https://github.com/JackChen-me/open-multi-agent/issues/25)。对于非 OpenAI 兼容的 Provider，欢迎贡献新的 `LLMAdapter` 实现——接口只需两个方法：`chat()` 和 `stream()`。
 - **示例** — 真实场景的工作流和用例。
 - **文档** — 指南、教程和 API 文档。
 
+## 作者
+
+> JackChen — 前 WPS 产品经理，现独立创业者。关注小红书[「杰克西｜硅基杠杆」](https://www.xiaohongshu.com/user/profile/5a1bdc1e4eacab4aa39ea6d6)，持续获取我的 AI Agent 观点和思考。
+
+## 贡献者
+
+<a href="https://github.com/JackChen-me/open-multi-agent/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=JackChen-me/open-multi-agent&v=20260405" />
+</a>
+
 ## Star 趋势
 
 <a href="https://star-history.com/#JackChen-me/open-multi-agent&Date">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&theme=dark&v=20260403" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260403" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260403" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&theme=dark&v=20260405" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260405" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&v=20260405" />
  </picture>
 </a>
 

package/dist/agent/agent.d.ts

@@ -25,6 +25,7 @@
 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';
+import { type RunOptions } from './runner.js';
 /**
  * High-level wrapper around {@link AgentRunner} that manages conversation
  * history, state transitions, and tool lifecycle.
@@ -61,7 +62,7 @@ export declare class Agent {
      *
      * Use this for one-shot queries where past context is irrelevant.
      */
-    run(prompt: string): Promise<AgentRunResult>;
+    run(prompt: string, runOptions?: Partial<RunOptions>): Promise<AgentRunResult>;
     /**
      * Run `prompt` as part of the ongoing conversation.
      *
@@ -104,6 +105,8 @@ export declare class Agent {
      * Handles state transitions and error wrapping.
      */
     private executeRun;
+    /** Emit an `agent` trace event if `onTrace` is provided. */
+    private emitAgentTrace;
     /**
      * Validate agent output against the configured `outputSchema`.
      * On first validation failure, retry once with error feedback.
@@ -114,6 +117,17 @@ export declare class Agent {
      * Handles state transitions and error wrapping.
      */
     private executeStream;
+    /** Extract the prompt text from the last user message to build hook context. */
+    private buildBeforeRunHookContext;
+    /**
+     * Apply a (possibly modified) hook context back to the messages array.
+     *
+     * Only text blocks in the last user message are replaced; non-text content
+     * (images, tool results) is preserved. The array element is replaced (not
+     * mutated in place) so that shallow copies of the original array (e.g. from
+     * `prompt()`) are not affected.
+     */
+    private applyHookContext;
     private transitionTo;
     private transitionToError;
     private toAgentRunResult;

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

@@ -1 +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;AA0BvD;;;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;IA0CvB;;;;;;;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;IAyCxB;;;OAGG;YACW,wBAAwB;IA+EtC;;;OAGG;YACY,aAAa;IA+B5B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,gBAAgB;IAmBxB;;;OAGG;IACH,gBAAgB,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,cAAc;CAU5D"}
+{"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,EAEd,UAAU,EACV,WAAW,EAEX,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,cAAc,IAAI,uBAAuB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,EAAmC,KAAK,UAAU,EAAkB,MAAM,aAAa,CAAA;AAqC9F;;;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;IA2CvB;;;;;;;OAOG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAQpF;;;;;;;OAOG;IAEG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBtD;;;;OAIG;IAEI,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;IAuFxB,4DAA4D;IAC5D,OAAO,CAAC,cAAc;IAqBtB;;;OAGG;YACW,wBAAwB;IA+EtC;;;OAGG;YACY,aAAa;IAiD5B,gFAAgF;IAChF,OAAO,CAAC,yBAAyB;IAgBjC;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,gBAAgB;IAoBxB;;;OAGG;IACH,gBAAgB,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,cAAc;CAU5D"}