@migor/agentia 0.5.0 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ $EDITOR my-app/.env                  # 填 ANTHROPIC_API_KEY（也可直接 expo
 > 框架**不自动**读 `.env`：脚手架 `src/main.ts` 首行的 `loadEnvFile()` 负责把它读进 `process.env`。
 > 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。
 
-> **版本**：`0.5.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> **版本**：`0.6.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
 > `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
 > [`examples/README.md`](examples/README.md) 的「依赖说明」。
 

package/dist/AGENTS.md

@@ -105,7 +105,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `model` | `ctx.llm()` 的缺省模型 |
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
-| `tools` | `ctx.llm()` 可调工具：**provider token 列表**（复用该 provider 的 `@Tool` 菜单） |
+| `tools` | `ctx.llm()` 可调工具：**provider token 列表**（复用该 provider 的能力菜单），或 `'<token>/<能力名>'` 能力级路径（只引菜单里的单个能力） |
 
 技能方法体拿到的第二参是 `SkillContext`：`ctx.llm({ prompt })` 才会真正调模型（脚本式，调几次由你写死）。
 
@@ -117,7 +117,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `schema` | 主 agent 填给子 agent 的任务入参 schema |
 | `name` | 缺省取方法名 |
 | `system` | 子 agent 的角色提示：`string` / `SystemPrompt` / `(task) => SystemParam` |
-| `tools` | 子 agent 可调工具：**provider token 列表** |
+| `tools` | 子 agent 可调工具：**provider token 列表**，或 `'<token>/<能力名>'` 能力级路径 |
 | `model` | 子 agent 自己的模型 |
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
@@ -251,6 +251,25 @@ result.typed;   // { answer: string } | undefined
 
 模型没提交就是 `undefined`（不是失败）。`stopReason` 仍以 `end_turn` 正常收尾。
 
+### 5.4 消息类型族（自有公共类型，与厂商 SDK 结构兼容）
+
+`messages` 与模型响应的类型是框架**自有定义**（不从 `@anthropic-ai/sdk` 引类型），字段口径与
+Anthropic Messages API 逐字对齐（snake_case），并与 SDK 的对应类型**结构兼容**：
+手里的 `Anthropic.MessageParam[]` 可以直接喂给 `app.run` / `executeRun`；装框架**不会**连带安装厂商 SDK。
+
+| 类型 | 说明 |
+|---|---|
+| `MessageParam` | 请求消息 `{ role, content: string \| ContentBlockParam[] }`（`Role` 含 `'system'`，与 SDK 逐字对齐；发给端点仍是 user/assistant 语义） |
+| `ContentBlockParam` | 请求块联合：text / image / tool_use / tool_result + `{ type: string }` 兜底成员（厂商新块型原样携带，读字段先按 `type` 收窄） |
+| `Message` | 模型响应（`finalMessage()` 的产物）：`{ id, type, role, content, model, stop_reason, stop_sequence, usage }` |
+| `ContentBlock` | 响应块联合：text / tool_use / thinking + `{ type: string }` 兜底成员 |
+| `ToolParam` | 发给模型的工具定义（**避让 @Tool 装饰器**，故不叫 Tool） |
+| `MessageUsage` | 响应的 token 计量（**避让 trace 的 `Usage`**，故不叫 Usage） |
+| `TextBlockParam` / `ImageBlockParam` / `ToolUseBlockParam` / `ToolResultBlockParam` | 请求侧具体块（与 SDK 同名类型逐字对齐） |
+| `TextBlock` / `ToolUseBlock` / `ThinkingBlock` / `CacheControl` / `Role` | 响应侧具体块 / cache 断点标记 / 角色联合 |
+
+注意命名避让：`Tool` 是装饰器、`Usage` 是 trace 的聚合用量（camelCase）—— 消息侧对应物分别是 `ToolParam` 与 `MessageUsage`（snake_case）。
+
 ---
 
 ## 6. 运行时 API
@@ -410,7 +429,7 @@ process.on('SIGTERM', async () => {
 | `mapWithConcurrency` | 有界并发 map（结果保序）；`maxToolConcurrency` 的底座，也可自用 |
 
 - **取消**：`app.run(messages, { signal })` 传 `AbortSignal` —— 框架会 abort 在飞请求（内置 Anthropic / OpenAI 适配器都转发 `signal`），run 以 `stopReason='aborted'` 收尾（算失败）。`createHttpHandler` 已内置「客户端断开即中止」；`AsyncRunner.runTimeoutMs` 到点同样是**真中止**（构造期校验：必须 ≥ 0 的**有限**数 —— NaN/Infinity 会被 `setTimeout` 钳到 1ms，等于每个任务立即超时，故直接抛错；要「不限」传 0 或不设）。
-- **重试**：缺省自动重试可重试失败（429 / 5xx / 连接失败），指数退避 + 抖动。`retry: false` 关闭，或 `retry: { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与 SDK 内置重试叠加 —— 建议二选一调（这里 `maxAttempts: 1` 或把 SDK 的 `maxRetries` 调小）。
+- **重试**：缺省自动重试可重试失败（429 / 5xx / 连接失败），指数退避 + 抖动。`retry: false` 关闭，或 `retry: { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与底层 client 的内置重试叠加（默认 client 的 `maxRetries` 缺省 2）—— 建议二选一调（这里 `maxAttempts: 1`，或 `createAnthropicClient({ maxRetries: 0 })`）。
 - **流式**：`POST /run` 带 `Accept: text/event-stream` → SSE 逐帧下发（`text.delta` / `run.end` / `error`）；不带该头仍回一元 JSON。
 - **工具超时 / 并发闸门**：`toolTimeoutMs` 超时**不杀 run**（该条 tool_result 记 `is_error`，模型可换路）；`maxToolConcurrency` 给同回合的并行工具设上限（默认全并行）。⚠️ 超时 = **放弃等待**，`AgentTool.run` 没有 signal 参数，**副作用可能已发生** —— 想真停的工具请自行读 `ToolRunContext.signal`。
 
@@ -516,11 +535,13 @@ if (result.stopReason === 'budget_exceeded') console.warn('这次 run 被预算
 
 | API | 说明 |
 |---|---|
-| `createAnthropicClient` | 默认 ModelClient（Anthropic）：自定义只传 `apiKey` / `baseURL`，不必直接依赖厂商 SDK |
+| `createAnthropicClient` | 默认 ModelClient（Anthropic）：自定义只传 `apiKey` / `baseURL`；框架**零运行时依赖**，不装厂商 SDK |
 | `createOpenAIClient` | OpenAI 兼容端点适配（DeepSeek 等；**真流式**、图片块转 `image_url`、cache token 恒 0） |
 | `InMemoryMemoryStore` | 跨 run 的**键值黑板**记忆（`{ store, keys }` 配 `executeRun`） |
 | `InMemorySessionStore` | 跨 run 的**对话历史**（`{ store, id }` 配 `executeRun` / `app.run`）；与前者正交，可同时用 |
 | `traceToMessages` | 把 trace 还原成 messages（重放基底） |
+| `forkMessages` | 分叉重放：在主循环第 `atTurn` 回合之前截断重放历史、拼上 `append` 新消息喂回 `app.run`（「从第 N 回合换个问法重跑」的基底，**不是续跑**） |
+| `diffTraces` | 两条 trace 的 A/B 比对（prompt / 模型实验）：run 级 summary + 逐 span 字段差；纯函数，llm.turn 配对**忽略模型名**，缺省忽略墙钟 |
 | `applyMiddleware` | 手动包裹配置菜单（装配层已自动做） |
 
 ### MCP 桥（MCP 是「工具来源」，不是新机制）
@@ -602,6 +623,48 @@ agentia harvest trace.jsonl --failed --limit 5 --out evals/harvested.ts
   - 预填的 `expect` 是从原 trace **抄录的实际轨迹** —— 发生过 ≠ 应该发生；
   - `EvalCase` 没有 `expect` 字段，粘贴时把断言搬进 `defineEval({ expect })`（脚手架注释会教）。
 
+### prompt / 模型 A/B（trace diff 与分叉重放）
+
+同一份输入跑两条 run（换模型、换 `SystemPrompt` 版本、换 prompt 都行），用 `diffTraces` 比出**结构与成本差**；
+想「从第 3 回合换个问法重跑」，用 `forkMessages` 在分叉点截断、拼上新消息喂回 `app.run`：
+
+```ts
+import { diffTraces, forkMessages } from '@migor/agentia';
+
+// A/B：同输入，只换模型（或换 system 版本），各跑一条
+const a = await app.run(input, { model: 'claude-sonnet-5' });
+const b = await app.run(input, { model: 'claude-opus-5' });
+
+const diff = diffTraces(a.result.trace, b.result.trace);
+// diff.summary：status / totalUsage.* / 根 attributes 差 —— A/B 模型第一眼就看 attributes.model
+// diff.spans：逐 span 字段级差异，path 形如 run:main/llm.turn#0/capability:search
+if (!diff.equal) console.log(diff.summary, diff.spans);
+
+// 分叉重放：在主循环第 3 回合（0-based）之前截断，该回合及其后丢弃，换个问法继续
+const messages = forkMessages(a.result.trace, {
+  atTurn: 3, // 合法范围 0..主循环回合数-1，越界抛可读错误
+  append: [{ role: 'user', content: '换个思路：先给结论，再补证据。' }],
+});
+const c = await app.run(messages); // 起一条新 run，沿着分叉点前的真实 tool 历史继续
+```
+
+不落代码也可以直比两份 trace 导出：`agentia diff a.jsonl b.jsonl`（输入形态同 `agentia report`），
+打印 run 级 summary + 逐 span 差异，**有差异时退出码 1**（diff(1) 语义）——可直接进 CI 挡
+「换 prompt / 模型后轨迹漂移」。
+
+- **配对语义**（结构性配对，字段差异不影响配对）：llm.turn 按回合序配对、**忽略 span name** ——
+  name 是模型 id，而「换模型重跑」正是 A/B 主用例，按 name 配对会把两侧所有 turn 报成缺失；
+  模型差异降格为配对 turn 的 `name` 字段差。capability span 按 `kind:name` 配对
+  （`skill:foo` vs `skill:bar` 是不同能力，不该配上）。一侧多出的调用树记**一条缺侧记录**
+  （`SpanDiff.fields` 为空、`path` 照给），整支子树不再下钻。
+- **墙钟缺省不比**：`ignoreTiming` 缺省 true（A/B 不关心时序）；传 `false` 改比 span 时长
+  （`duration`），绝对时间戳永不比；`traceId` 是身份不是行为，同样永不比。
+- ⚠️ **有损边界（与 `traceToMessages` / harvest 同源）**：trace **不记 assistant 文本与 run 的
+  原始输入** —— 重放里 assistant 是标注占位（非逐字原文）、首尾说明性 user 是合成。
+  因此 `forkMessages` **不是「续跑」**：它产出的是一份喂回 `app.run` / `runAgent` 的 messages，
+  跑的是一条**新 run**，不是接着原 run 的循环位置。分叉的 blackboard 种子由调用方自带
+  （`app.run(messages, { blackboard: {…} })` —— trace 不记 blackboard）。
+
 ### 指标（从 trace 派生）
 
 | API | 说明 |
@@ -878,11 +941,13 @@ const callable = {
 | schema 校验是**子集** | 只覆盖 `type/properties/required/additionalProperties/enum/items`；`format`/`minimum`/`oneOf` 一律放行 |
 | 历史畸形就放弃裁剪 | `trimToolPairs` 遇到非严格交替历史会整体放弃（宁可少裁，也不切出孤立 tool_use 让请求 400） |
 | 缺省内存 store 不淘汰 | 长跑宿主请设 `InMemoryTaskStore({ maxRecords })` 或换 `FileTaskStore` / `SqliteTaskStore` |
-| 能力引用是 provider 粒度 | 子 agent / skill 的 `tools` 写的是 **provider token**，不是单个工具名 |
+| 能力引用两种粒度 | `tools` 写 **provider token** = 整片能力菜单；写 `'<token>/<能力名>'` = 只引单个能力（@Tool/@Skill/@SubAgent/@Prompt 都可点名，装配期校验，名字不存在即抛错并列出可用名单） |
 | 能力名有格式校验 | 装饰器能力名（`name` 或缺省的方法名）必须匹配 `^[A-Za-z0-9_-]{1,64}$`（与 MCP 桥同口径），非法名在 `createApp` **装配期即抛错** —— 含空格/点/中文的名字会让模型 API 400，宁可在启动期拦住 |
 | `discover` 入口会回落 | 能力目录里源码与编译产物并存（`index.ts` + `index.js`）时，首选 `.ts` 加载失败会**回落 `.js` 并 warn** —— 命中的可能是**陈旧编译产物**（刚改过源码时注意）；全部候选都失败才抛错并列出各自原因 |
 | `asset()` 的 rel 必须是相对路径 | 带 scheme（`file:` / `https:` …）的 rel 会让 `new URL(rel, base)` 整个忽略 base（「以为读了能力目录、实际读了别处」），显式抛错；`../` 越出能力目录是**有意放行**（共享资产如 `../../shared/x.md` 是合法用法） |
 | 取消要传进客户端才有效 | 传 `signal` 后框架会 abort 在飞请求（内置 Anthropic / OpenAI 适配器都转发）；不转发 `signal` 的自定义 `ModelClient` 只能「放弃等待」（请求在后台跑完、产物丢弃） |
+| 默认 client 的真端点验证范围 | `e2e:live` 跑在 DeepSeek 的 Anthropic **兼容**端点上；官方 Anthropic 端点的行为差异（thinking 细节、cache TTL 语义、新块型）目前只有本地假端点测试在守 —— 「mock 全绿发现不了厂商真实行为」是本框架自己记过的教训，接入官方端点前自己跑一遍 `npm run e2e:live` |
+| thinking 块「能收、不主动请求」 | 框架**从不**在请求里开 extended thinking；默认 client 能收拼 thinking 块（`signature_delta` 会累积），`redacted_thinking` 与未知块型**原样透传**不丢 —— 但官方 API 的 thinking 回灌要求带合法 `signature`，自定义 client 开 thinking 时自己验证这条链 |
 | 工具阶段的 abort 有盲区 | abort 只在三处被观察：**回合边界 / 在飞模型请求 / 重试退避 sleep**。没设 `toolTimeoutMs` 且工具挂死时，abort 之后 run 也不会返回（工具的 Promise 永不 settle）—— 挂死的工具要么设超时，要么自己读 `ToolRunContext.signal` |
 | 观测失败被吞 | sink 抛错不影响 run（观测是辅助动作）；同理记忆水合/回写失败也不击穿 run |
 | 框架不自动读 .env | 除 `AGENTIA_MODEL`（缺省模型覆盖）与 `OPENAI_API_KEY`（OpenAI 适配器）外，框架自己不去翻环境变量，也不读 `.env`；要读就在启动代码里调 `loadEnvFile()`（脚手架已内置那行），**真实环境变量优先**于文件 |
@@ -902,7 +967,7 @@ const callable = {
 | MCP 的协议层错误框架看不见 | `isError: true` 只有连接器能看见 —— 它必须转成抛错，否则模型收到的是一条「成功」的结果 |
 | MCP 超时同样是「不等了」 | 桥自带的 `timeoutMs` 取消不了 server 侧执行（拿不到取消句柄）；它与 engine 的 `toolTimeoutMs` **双重计时**，谁短谁生效 |
 | MCP 名字可能被归一化 | 原名含 `-` / `.` / 空格 → 进菜单时变成 `_`；回调 server 用的仍是原名（`mcp.tool` attribute 里查得到） |
-| MCP 工具不能进 DI 容器 | 它没有 provider token，也不能被别的能力的 `tools` 引用 —— 引用是 provider 粒度 |
+| MCP 工具不能进 DI 容器 | 它没有 provider token，也不能被别的能力的 `tools` 引用（两种引用粒度都要先有 token） |
 | 指标分位是窗口内精确值 | `*_last{quantile=...}` 只反映最近 `windowSize`（缺省 1024）条样本；要跨实例聚合请用直方图（`*_bucket` / `_sum` / `_count`，累积语义） |
 | 指标是**进程内**累加 | 不做分布式聚合与持久化：多实例各算各的（直方图可相加），重启即清零。要长期保留请把 `render()` 抓走或用 `export:'otlp'` 推给采集端 |
 | OTLP metrics 只推当前累计 | 按 `intervalMs` 周期导出**累积值**（CUMULATIVE），不做增量/背压；导出失败按 `onExportError` 处理（缺省吞掉，不重试、不阻塞 run） |
@@ -912,6 +977,7 @@ const callable = {
 | 能力标签有基数上限 | `labelMode:'capability'`（缺省）+ `maxCapabilities`（缺省 200），超出的能力归入 `capability="__other__"`；`snapshot().droppedCapabilities` 给出被归并的能力个数。要完整明细请用 `buildRunReport`（不设上限） |
 | 提示词版本只是标记 | 框架不存版本库、不回滚：`version` 只落 run 根 attribute；`system` 传已拼好的 `SystemParam` 时无版本可记 |
 | `agentia harvest` 的产物是轨迹骨架 | trace **不记 assistant 文本**（llm.turn 只记 usage/事件），故 harvest 用例脚本里的 text 块是占位、预填 `expect` 是从原 trace 抄录的实际轨迹 —— 脚手架不是成品，人工核对后再进 CI（见 §6「线上 trace 回流」） |
+| 分叉重放不是续跑 | `forkMessages` 与 `traceToMessages` / harvest **同源有损**：trace 不记 assistant 文本与 run 原始输入（重放里 assistant 是标注占位、首尾 user 是合成），也不记 blackboard（分叉种子经 `RunInvocationOptions.blackboard` 自带）；它产出喂回 `app.run` 的 messages、起的是**新 run**，不是接着原 run 的循环位置跑 |
 | 评分来自 run 之外 | `Score` 走 run 根 `score` **事件**而非 span 字段（评分通常在 run 跑完后才产生）；`attachScore` 找不到根 span 时静默忽略，多次调用即多条事件（不同维度各记各的） |
 | 配额不是框架子系统 | 只给缝（middleware + TraceSink + BudgetGuard），计数放哪（内存 / Redis / DB）与超限怎么办都是你的策略 |
 | 人工介入只到「闸门」 | `middleware` 能 `await` 审批决策再放行；**跨进程挂起/续跑框架不做** —— `RunStatus` 无「待批准」态、循环位置不落库，`traceToMessages` 重放有损，不能拿它假装续跑（要跨重启审批请上工作流引擎）|
@@ -931,7 +997,7 @@ const callable = {
 | `ctx.get('k')` 没有类型 | 没做 `Blackboard` 声明合并（见 5.1） |
 | `result.typed` 是 `unknown` | `resultSchema` 用的是裸 JsonSchema；改 `fromZod<T>`（见 5.3） |
 | TS 里想 `app.my_tool(...)` | 不要这样写：能力由模型选择，不是你的方法。要确定性调用就**直接调类方法** |
-| 子 agent 调不到工具 | `tools` 是 **provider token**（文件夹名）列表，不是工具名 |
+| 子 agent 调不到工具 | `tools` 的元素是 **provider token** 或 `'<token>/<能力名>'` 路径，不是裸工具名（裸名字会按「未注册 provider」在装配期抛错） |
 | 长跑内存涨 | 缺省内存 store 不淘汰；设 `InMemoryTaskStore({ maxRecords })` 或换耐久 store |
 | 鉴权钩子抛错，客户端只看到「未通过鉴权」 | 这是设计：非 `HttpException` 的错误原文只进服务端日志（要回给调用方就抛 `HttpException(status, body)`） |
 | 停机后 `POST /tasks` 回 503 | `drain()` 已被调用（或注入的 runner 已 drain）—— 这是「拒新单」的正常行为，任务没丢 |

package/dist/core/message.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Agentia —— 消息类型族（公共类型自有化，2026-09-17）。
+ *
+ * 框架公共面（ModelClient 契约 / RunSpec / SessionStore / replay 等）的消息与内容块
+ * 类型，字段口径与 Anthropic Messages API 逐字对齐（snake_case），与
+ * `@anthropic-ai/sdk` 的对应类型**结构兼容**（双向/单向 assignability 由
+ * `tests/types/message-compat.types.ts` 钉住，SDK 因此只留在 devDependencies 做门禁）。
+ *
+ * 两条刻意的取舍（都有硬理由，别「顺手改进」）：
+ *
+ * 1. **兜底成员不带索引签名**（`UnknownContentBlockParam` / `UnknownContentBlock` 只有
+ *    `type: string`）。带 `[key: string]: unknown` 的形态看起来更「前向兼容」，但 SDK 的
+ *    块类型全是 **interface**（无隐式索引签名），赋给带索引签名的目标直接编译失败 ——
+ *    「使用者手里的 `Anthropic.MessageParam[]` 直接喂给框架」这条承诺就会当场破产。
+ *    只有 `type` 的最小面反而两个方向都通：未知块原样携带（历史回灌不丢内容），
+ *    要读字段请自行收窄/断言。
+ * 2. **`Role` 含 `'system'`**：SDK 0.124 的 `MessageParam.role` 是
+ *    `'user' | 'assistant' | 'system'`，方向一（SDK → 自有）要求逐字对齐。
+ *    引擎自身只产出 user/assistant；给 Messages API 发 system 角色会被端点拒绝，
+ *    与 SDK 类型下的同款误用语义一致。
+ *
+ * 零依赖纯类型文件：不写运行时代码，编译后全部擦除。core 是叶子层，本文件不 import 任何模块。
+ */
+/** 消息角色（含 'system' 的原因见文件头注释 2） */
+export type Role = 'user' | 'assistant' | 'system';
+/** prompt cache 断点标记（`cache_control` 字段的值） */
+export interface CacheControl {
+    type: 'ephemeral';
+    /** 缓存 TTL；缺省 '5m'（与 SDK 的 CacheControlEphemeral 逐字对齐） */
+    ttl?: '5m' | '1h';
+}
+export interface TextBlockParam {
+    type: 'text';
+    text: string;
+    cache_control?: CacheControl | null;
+}
+export interface ImageBlockParam {
+    type: 'image';
+    /**
+     * 图片源：base64 / url 为已知形态；其余（如 file_id 源）走 `{ type: string }` 最小面兜底
+     * （理由同文件头注释 1）。读具体字段前先按 `source.type` 收窄。
+     */
+    source: {
+        type: 'base64';
+        media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+        data: string;
+    } | {
+        type: 'url';
+        url: string;
+    } | {
+        type: string;
+    };
+    cache_control?: CacheControl | null;
+}
+export interface ToolUseBlockParam {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+    cache_control?: CacheControl | null;
+}
+export interface ToolResultBlockParam {
+    type: 'tool_result';
+    tool_use_id: string;
+    /** 工具结果正文：纯文本，或 text/image 等块（未知块型走兜底成员，原样携带） */
+    content?: string | Array<TextBlockParam | ImageBlockParam | UnknownContentBlockParam>;
+    is_error?: boolean;
+    cache_control?: CacheControl | null;
+}
+/**
+ * 前向兼容兜底：厂商新增块类型的最小面。**刻意不带索引签名**（见文件头注释 1）——
+ * 未知块在消息历史里原样携带（role 交替与 tool_use/tool_result 配对不受影响），
+ * 消费方按 `type` 排除已知块后自行断言读取。
+ */
+export interface UnknownContentBlockParam {
+    type: string;
+}
+/** 请求侧内容块联合：已知块 + 兜底成员（厂商新块型原样携带） */
+export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | UnknownContentBlockParam;
+export interface MessageParam {
+    role: Role;
+    content: string | ContentBlockParam[];
+}
+/** 工具的 input_schema 形状（与 SDK 的 Tool.InputSchema 逐字对齐） */
+export interface ToolInputSchema {
+    type: 'object';
+    properties?: unknown;
+    required?: string[] | null;
+    [key: string]: unknown;
+}
+/**
+ * 发给模型的工具定义（**避让 @Tool 装饰器**，故名 ToolParam）。
+ * 引擎从 AgentTool 推导（`engine/loop.ts` 的 toApiTool）；自定义 ModelClient 只读它。
+ * 与块类型同理**不带索引签名**（文件头注释 1）：SDK 的 `Tool` 是 interface，
+ * 带索引签名会让「SDK 的工具定义数组直接喂给自定义 client」编译失败。
+ * 厂商新增的工具字段（defer_loading 等）读之前自行断言。
+ */
+export interface ToolParam {
+    name: string;
+    description?: string;
+    input_schema: ToolInputSchema;
+    strict?: boolean;
+    cache_control?: CacheControl | null;
+}
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    signature: string;
+}
+/** 响应侧兜底块（语义同 UnknownContentBlockParam，见文件头注释 1） */
+export interface UnknownContentBlock {
+    type: string;
+}
+/** 响应侧内容块联合：text / tool_use / thinking + 兜底成员 */
+export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock | UnknownContentBlock;
+/**
+ * 模型 stop_reason。已知取值与 SDK 逐字对齐；`| (string & {})` 收留端点未来的新值
+ * （引擎对未识别的 stop_reason 有 `unknown_stop_reason` 收尾分支，见 engine/loop.ts）。
+ */
+export type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal' | 'model_context_window_exceeded' | (string & {});
+/** 模型回报的 token 计量（**避让 trace 的 `Usage`**（camelCase 聚合），故名 MessageUsage） */
+export interface MessageUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+}
+/** 一次模型往返的最终响应（`ModelClient.messages.stream().finalMessage()` 的产物） */
+export interface Message {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    content: ContentBlock[];
+    model: string;
+    stop_reason: StopReason | null;
+    stop_sequence: string | null;
+    usage: MessageUsage;
+}

package/dist/core/message.js

@@ -0,0 +1,25 @@
+/**
+ * Agentia —— 消息类型族（公共类型自有化，2026-09-17）。
+ *
+ * 框架公共面（ModelClient 契约 / RunSpec / SessionStore / replay 等）的消息与内容块
+ * 类型，字段口径与 Anthropic Messages API 逐字对齐（snake_case），与
+ * `@anthropic-ai/sdk` 的对应类型**结构兼容**（双向/单向 assignability 由
+ * `tests/types/message-compat.types.ts` 钉住，SDK 因此只留在 devDependencies 做门禁）。
+ *
+ * 两条刻意的取舍（都有硬理由，别「顺手改进」）：
+ *
+ * 1. **兜底成员不带索引签名**（`UnknownContentBlockParam` / `UnknownContentBlock` 只有
+ *    `type: string`）。带 `[key: string]: unknown` 的形态看起来更「前向兼容」，但 SDK 的
+ *    块类型全是 **interface**（无隐式索引签名），赋给带索引签名的目标直接编译失败 ——
+ *    「使用者手里的 `Anthropic.MessageParam[]` 直接喂给框架」这条承诺就会当场破产。
+ *    只有 `type` 的最小面反而两个方向都通：未知块原样携带（历史回灌不丢内容），
+ *    要读字段请自行收窄/断言。
+ * 2. **`Role` 含 `'system'`**：SDK 0.124 的 `MessageParam.role` 是
+ *    `'user' | 'assistant' | 'system'`，方向一（SDK → 自有）要求逐字对齐。
+ *    引擎自身只产出 user/assistant；给 Messages API 发 system 角色会被端点拒绝，
+ *    与 SDK 类型下的同款误用语义一致。
+ *
+ * 零依赖纯类型文件：不写运行时代码，编译后全部擦除。core 是叶子层，本文件不 import 任何模块。
+ */
+export {};
+//# sourceMappingURL=message.js.map

package/dist/core/message.js.map

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

package/dist/core/tool.d.ts

@@ -1,4 +1,4 @@
-import type Anthropic from '@anthropic-ai/sdk';
+import type { Message, MessageParam, TextBlockParam, ToolParam } from './message.js';
 import type { SpanError, SpanId, SpanKind, SpanStatus, Trace, Usage } from './trace.js';
 /**
  * Agentia —— 工具定义。
@@ -56,17 +56,18 @@ export interface RecorderBackend {
     snapshot(status: SpanStatus): Trace;
 }
 /**
- * engine 对模型端的最小结构面（R4 多模型）：Anthropic SDK 天然满足，
- * 其他 provider（OpenAI 兼容端点等）只需适配出同一形态。
+ * engine 对模型端的最小结构面（R4 多模型）：消息形态由 core/message.js 的自有类型族
+ * 定义（与 Anthropic Messages API 逐字对齐），其他 provider（OpenAI 兼容端点等）
+ * 只需适配出同一形态。
  */
 export interface ModelClient {
     messages: {
         stream(params: {
             model: string;
             max_tokens: number;
-            system?: string | Anthropic.TextBlockParam[];
-            tools?: Anthropic.Tool[];
-            messages: Anthropic.MessageParam[];
+            system?: string | TextBlockParam[];
+            tools?: ToolParam[];
+            messages: MessageParam[];
             /**
              * 中断信号（可选）：实现须转发给底层请求，否则调用方无法中止在飞 run。
              *
@@ -74,14 +75,14 @@ export interface ModelClient {
              * SDK 把「传输层的 signal」放在**请求选项**里（如 `@anthropic-ai/sdk` 的
              * `stream(body, options?)` —— `signal` 只在 `RequestOptions` 里认）。若把本 params 原样
              * 交给 SDK，signal 会被**静默丢弃**，中止失效且**没有任何报错**。
-             * 参考实现：`integrations/anthropic.ts` 的 `splitSignal()`（把 signal 摘出来搬到 options），
-             * 以及 `integrations/openai.ts`（手写 fetch，直接透传）。
+             * 参考实现：`integrations/anthropic.ts`（手写 fetch，signal 摘出 body 直接传给 fetch），
+             * 以及 `integrations/openai.ts`（同款）。
              * 门禁：`tests/integrations/anthropic.test.ts`（零 key 本地假端点，abort 后必须断开）。
              */
             signal?: AbortSignal;
         }): {
             on(event: 'text', cb: (delta: string) => void): void;
-            finalMessage(): Promise<Anthropic.Message>;
+            finalMessage(): Promise<Message>;
         };
     };
 }

package/dist/engine/errors.d.ts

@@ -1,4 +1,16 @@
 import type { SpanError } from '../core/trace.js';
+/**
+ * Agentia —— 异常分类（engine 对厂商 SDK 零运行时 import）。
+ *
+ * 分类是**鸭子类型**：默认 client（`integrations/anthropic.ts`）自研化后抛的是
+ * 带数值 `status` 的 `AnthropicApiError` 与 fetch 的原生网络错误（TypeError 带 cause），
+ * 不再是 SDK 错误类。同套判法对第三方 SDK 错误同样适用（它们的错误类也带 `status`）。
+ *
+ * 历史教训（2026-09-13 实测，当时因此保留 instanceof）：厂商 SDK 的错误类
+ * `name` 恒为 `'Error'`、`type` 为 null，鸭子类型只能靠 `constructor.name` ——
+ * **压缩即失效**。所以这里只认**数据属性**（`status` 数值 / `cause` / errno `code` /
+ * 内建 DOMException 的 `name`），一概不碰构造函数名。
+ */
 /** 是否中断异常（DOMException / 普通 Error 都可能是，靠 name 判定） */
 export declare function isAbortError(e: unknown): boolean;
 /** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */

package/dist/engine/errors.js

@@ -1,25 +1,58 @@
-import Anthropic from '@anthropic-ai/sdk';
+/**
+ * Agentia —— 异常分类（engine 对厂商 SDK 零运行时 import）。
+ *
+ * 分类是**鸭子类型**：默认 client（`integrations/anthropic.ts`）自研化后抛的是
+ * 带数值 `status` 的 `AnthropicApiError` 与 fetch 的原生网络错误（TypeError 带 cause），
+ * 不再是 SDK 错误类。同套判法对第三方 SDK 错误同样适用（它们的错误类也带 `status`）。
+ *
+ * 历史教训（2026-09-13 实测，当时因此保留 instanceof）：厂商 SDK 的错误类
+ * `name` 恒为 `'Error'`、`type` 为 null，鸭子类型只能靠 `constructor.name` ——
+ * **压缩即失效**。所以这里只认**数据属性**（`status` 数值 / `cause` / errno `code` /
+ * 内建 DOMException 的 `name`），一概不碰构造函数名。
+ */
 /** 是否中断异常（DOMException / 普通 Error 都可能是，靠 name 判定） */
 export function isAbortError(e) {
     return typeof e === 'object' && e !== null && e.name === 'AbortError';
 }
+/** 取错误的可读 message（Error 取 .message，其余 String 兜底） */
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** errno 形态的连接错误码（Node 网络层稳定产出，不靠 message 文案） */
+const CONNECTION_CODES = /^(ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|EPIPE|ENETUNREACH|EHOSTUNREACH|ECONNABORTED)$/;
+/**
+ * 无 status 的网络型错误 → connection。
+ * 稳的判法（不过拟合 message 字符串）：
+ * - fetch 的网络失败是 `TypeError` 且带 `cause`（undici 保证，cause 里常有 errno）；
+ * - 带 errno `code` 属性的 Error（Node 网络层直接抛的形态）；
+ * - `name === 'TimeoutError'` 的 DOMException（`AbortSignal.timeout` / 默认 client 的
+ *   timeout 合成信号）—— 内建 name 是规范值，不受压缩影响。
+ */
+function isConnectionError(e) {
+    if (e instanceof TypeError && e.cause != null)
+        return true;
+    const code = e.code;
+    if (typeof code === 'string' && CONNECTION_CODES.test(code))
+        return true;
+    return e.name === 'TimeoutError';
+}
 /** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */
 export function classifyError(e) {
     if (isAbortError(e)) {
         return { type: 'aborted', message: 'run 已被取消', retryable: false };
     }
-    if (e instanceof Anthropic.RateLimitError) {
-        return { type: 'rate_limit', message: e.message, retryable: true };
-    }
-    if (e instanceof Anthropic.APIConnectionError) {
-        return { type: 'connection', message: e.message, retryable: true };
-    }
-    if (e instanceof Anthropic.InternalServerError) {
-        return { type: 'server', message: e.message, retryable: true };
-    }
-    if (e instanceof Anthropic.APIError) {
-        const status = e.status ?? 0;
-        return { type: 'api', message: e.message, retryable: status >= 500 || status === 429 };
+    if (typeof e === 'object' && e !== null) {
+        const status = e.status;
+        if (typeof status === 'number' && Number.isFinite(status)) {
+            if (status === 429)
+                return { type: 'rate_limit', message: messageOf(e), retryable: true };
+            if (status >= 500)
+                return { type: 'server', message: messageOf(e), retryable: true };
+            return { type: 'api', message: messageOf(e), retryable: false };
+        }
+        if (isConnectionError(e)) {
+            return { type: 'connection', message: messageOf(e), retryable: true };
+        }
     }
     if (e instanceof Error) {
         return { type: 'unknown', message: e.message, retryable: false };

package/dist/engine/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAG1C,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAwB,CAAC,IAAI,KAAK,YAAY,CAAC;AAChG,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,kBAAkB,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,mBAAmB,EAAE,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAwB,CAAC,IAAI,KAAK,YAAY,CAAC;AAChG,CAAC;AAED,oDAAoD;AACpD,SAAS,SAAS,CAAC,CAAU;IAC3B,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,iDAAiD;AACjD,MAAM,gBAAgB,GACpB,uGAAuG,CAAC;AAE1G;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,CAAS;IAClC,IAAI,CAAC,YAAY,SAAS,IAAK,CAAyB,CAAC,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACpF,MAAM,IAAI,GAAI,CAAwB,CAAC,IAAI,CAAC;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,OAAQ,CAAwB,CAAC,IAAI,KAAK,cAAc,CAAC;AAC3D,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QACxC,MAAM,MAAM,GAAI,CAA0B,CAAC,MAAM,CAAC;QAClD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,IAAI,MAAM,KAAK,GAAG;gBAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC1F,IAAI,MAAM,IAAI,GAAG;gBAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YACrF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAClE,CAAC;QACD,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACxE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}

package/dist/engine/loop.d.ts

@@ -1,4 +1,4 @@
-import type Anthropic from '@anthropic-ai/sdk';
+import type { MessageParam } from '../core/message.js';
 import type { AgentTool, JsonSchema, ModelClient, ModelPricing, RecorderBackend, SchemaType } from '../core/tool.js';
 import type { SpanError, SpanId } from '../core/trace.js';
 import type { RetryOptions } from './retry.js';
@@ -9,6 +9,21 @@ import type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, S
  * export AGENTIA_MODEL=deepseek-… 即可全局覆盖，无需逐处传 model。
  */
 export declare function resolveDefaultModel(over?: string): string;
+/**
+ * Agentia —— 主循环（manual loop，流式）—— spec §5。
+ *
+ * 结构：核心是 `agentLoop` —— 不自开 run 根，所有 llm.turn 挂在给定的
+ * parentSpanId 下。同一套循环既能当主 agent（run 根为其父，由 runAgent 开），
+ * 也能当子 agent（capability span 为其父，见 toolkit/subagent.ts），llm.turn 与 usage
+ * 递归进同一条 trace（spec §9：子 agent = 一个 capability span，内部能力递归成它的子孙）。
+ *
+ * 工具执行经 ctx: ToolRunContext 把 {client, recorder, parentSpanId: 当前 turn}
+ * 交给 tool.run —— 普通工具忽略；子 agent 用它在正确位置开 capability span。
+ *
+ * 文件分工：本文件只留入口（runAgent / runAgentScoped）与 agentLoop 编排骨架 +
+ * 缺省旋钮；「一回合执行步骤」的实现机（回合上下文、请求/重试、记账、stop_reason
+ * 分流、工具执行）拆在同层 turn.ts，依赖方向单向 loop.ts → turn.ts。
+ */
 export interface AgentLoopResult<T = unknown> {
     stopReason: AgentStopReason;
     finalText: string;
@@ -28,7 +43,7 @@ export declare function runAgent<S extends JsonSchema = JsonSchema>(options: Run
 export declare function runAgentScoped<S extends JsonSchema = JsonSchema>(opts: {
     client?: ModelClient;
     system?: SystemParam;
-    messages: Anthropic.MessageParam[];
+    messages: MessageParam[];
     tools?: AgentTool[];
     model?: string;
     maxTokens?: number;
@@ -66,12 +81,3 @@ export declare function runAgentScoped<S extends JsonSchema = JsonSchema>(opts:
     /** 成本硬管控（C1）：累计成本（美元）上限；同 maxTotalTokens */
     maxCostUsd?: number;
 }): Promise<AgentLoopResult<SchemaType<S>>>;
-/**
- * 用 `next` 原地替换 `target` 的全部内容（保持数组引用不变 —— 循环各处持同一数组）。
- *
- * **不要**写回 `target.splice(0, target.length, ...next)`：展开传参受 V8 实参个数上限
- * 约束，`next` 超过约 12 万项即抛 `RangeError: Maximum call stack size exceeded`
- * （实测 12 万 ok、30 万抛）。`next` 来自调用方注入的 `contextPolicy`，长度不受框架
- * 控制，所以用循环逐项写，彻底没有这个上限。
- */
-export declare function replaceMessages(target: Anthropic.MessageParam[], next: readonly Anthropic.MessageParam[]): void;