@migor/agentia 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -5,6 +5,284 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.10.6] - 2026-11-09
+
+### 变更
+
+本版是一次**正确性收口**，不新增能力面：修掉八类「静默失效」，其中三处会改变调用方能观察到的
+行为，需要在升级前确认。两包同步 0.10.5 → 0.10.6。
+
+- ⚠️ **MCP 反向桥默认不再暴露 `approval: 'required'` 的工具**（安全修）。MCP 没有审批挂起通道，
+  暴露即等于绕过审批。需要这些人批工具的人显式设 `exposeApprovalRequiredTools: true`；
+  被隐藏时构造期会打一行 warn **点名数量**，不静默少工具。
+- ⚠️ **所有出站请求不再跟随重定向**（安全修）。307/308 会把鉴权头与请求体原样转到另一个
+  origin。依赖 3xx 跳转的外部端点现在会**报错**而不是静默跟过去，请把最终地址配进去。
+- ⚠️ **坏值从「静默忽略」改成「响亮拒绝」**：`maxEventChars: 0` 现在真的截到空串
+  （此前被当成「不限」）；`toolTimeoutMs` / `maxEventChars` / `maxToolResultChars` /
+  `awaitTask` 的 `timeoutMs`·`intervalMs` / OTLP·metrics 的 `timeoutMs` 在入口校验，
+  NaN·负数·小数直接抛。`metricsSink.intervalMs` 的负数与 `0` 同义（立即导出），已写进
+  `LIMIT_SEMANTICS` 表。
+- 四条唤醒路径（`approve × signalTask` / `wakeDue × signalTask`）共用一把 per-task 互斥闸，
+  同一任务不再被派发两遍；`cancel` 等同一张表的 tail。
+- 审批决定带作用域：只认 `requestedAt` 与本次挂起匹配的决定，同一 `tool_use_id` 每段只消费一次
+  —— 修掉 OpenAI 兼容端点复用 `call_1` 导致的审批绕过。
+- 失败尝试的部分 usage 落账：流中断前已收到的计量挂到错误上并写 `usage.partial`，
+  `maxCostUsd` / `maxTotalTokens` 不再系统性少算。
+- 跨进程 SSE 兜底从「每连接一个 5s 定时器」提到 runner 级单例：一拍里每个任务只读一次 store，
+  定时器有登记才存在；`streamTask` 的 `pollMs` 从此是开关（`<= 0` = 该流不参与兜底）。
+- 落库剥离 `client` / `tools` 时留下可读痕迹，恢复段按 taskId 告警一次 —— 此前 per-task 自定义
+  client 的任务重启续跑会**静默**打到 runner 的端点。
+- JSON / SQLite / Redis 三条 store 的恢复路径加固（读失败出声、半行写入回滚、迁移事务化、
+  SCAN 去重、水合失败跳过回写），详见 `docs/spec.md` §10。
+- 构建面：四个 `package-lock.json` 的 `resolved` 从第三方镜像站改回官方 registry（共 463 处），
+  两个示例 `Dockerfile` 加拉包重试。此前 2026-11-09 镜像站 5xx 让「构建 deploy 示例镜像」连挂
+  两轮（`ER_NO_SUCH_TABLE` / `504`）；改后该 job 从 174–368s 降到 20s。⚠️ 它与 `src/` 无关，
+  但影响**从零安装**：`npm ci` 的 tarball 来源现在是官方源（镜像站用户仍可由自己的 npm 配置改写）。
+
+### ⚠️ 行为变更（安全修）：MCP 反向桥默认隐藏 HITL 工具（2026-11-07 ref-deep-review-2026-11-07）
+
+- **修的是什么**：`createMcpServer` 此前把 `app.tools` 整个交给 MCP 客户端。而
+  `@Tool({ approval: 'required' })` 的语义是「调用前必须有人批」，MCP 这条通道**没有**挂起与
+  回调的通道 —— 工具被列出去就等于「审批被绕过」，且没有任何一处会报错。
+- **现在**：默认过滤掉 `approval: 'required'` 的工具；确有需要（例如客户端自己实现了外部审批）
+  显式设 `exposeApprovalRequiredTools: true`。过滤发生时打一行 warn 说明数量与原因 ——
+  「明明写了 `@Tool`，MCP 客户端却看不到」不该靠猜。
+- **迁移**：升级后如果 MCP 客户端少了一批工具，先看启动日志里那行 warn。要恢复旧行为就开那个开关，
+  但请自行确保这些工具的人批在你的客户端侧成立。
+
+### ⚠️ 行为变更（安全修）：出站 `fetch` 不跟随重定向
+
+- **修的是什么**：默认的 `fetch` 跟 3xx，而 307/308 **保留方法与请求体** —— 一次被中间人控制或
+  被错误配置的重定向，会把 `Authorization` 头与 prompt 原文发到另一个 origin。这条链上没有一个
+  环节会报错，日志里只有一次成功的 `POST`。
+- **现在**：所有出站调用（模型适配器、OTLP/metrics 导出、MCP HTTP）一律 `redirect: 'error'`，
+  收到 3xx 直接失败。
+- **迁移**：如果你的模型网关 / OTLP collector 依赖 301/302/307 跳转，请把最终地址直接配进去。
+  报错信息里带原始状态码与 `Location`，照它改即可。
+
+### 唤醒互斥与取消优先（2026-11-07 ref-deep-review-2026-11-07）
+
+- **修的是什么**：`approve` 与 `signalTask`、`wakeDue` 与 `signalTask` 各自凭**同一份** suspended
+  快照判断「该我唤醒」，于是同一任务被派发两遍；两次执行都落库，后写的覆盖前写的，
+  审批决定可能凭空消失，而 usage 记了两份。
+- **现在**：四条唤醒路径共用 `transport/task-wake-gate.ts` 的 per-task 串行闸，同步段一次性登记
+  （无 await，无 TOCTOU 窗口）；`cancel` 排在同一个 key 的 tail 上，不会插进正在进行的唤醒。
+- **取消优先**：引擎的续跑段与主循环的 approval / deferred 出口统一补 abort 守卫；宿主在
+  suspended 分支再判一次取消意图 —— 修掉「cancel 等不到终态、超时定时器到点又跑一遍」。
+- **验证**：`tests/transport/wake-gate.test.ts`、`tests/transport/drain-gate.test.ts`；反向变异
+  确认「摘掉 gates」能复现双派发。
+
+### 审批决定的作用域（2026-11-07 ref-deep-review-2026-11-07）
+
+- **修的是什么**：审批决定此前只按 `tool_use_id` 匹配。OpenAI 兼容端点每次都从 `call_1` 开始编号，
+  于是**上一段**挂起时批过的 `call_1`，会被下一段的 `call_1` 当成「已批准」直接放行 ——
+  一次静默的审批绕过。
+- **现在**：`RunAgentOptions.approvalEpoch` 标出本次挂起的身份（异步宿主自动注入
+  `TaskRecord.suspendedSince`），只认 `requestedAt` 匹配的决定；同一段内每个 `tool_use_id` 也只
+  消费一次（`consumedApprovals`）。三处判据（写入时的 `requestedAt`、`fillTimeoutDenials` 的
+  stale 覆盖、`approvalsComplete(rec, since)`）用的是同一个 epoch。
+- **验证**：`tests/engine/approval-epoch.test.ts`（含「旧决定不得跨段复用」与「同段只消费一次」
+  两条正面用例）。
+
+### 失败尝试的计量落账（2026-11-07 ref-deep-review-2026-11-07）
+
+- **修的是什么**：适配器在流中断（网络断、上游 5xx、超时）时把整个 turn 判为失败，而**中断前已
+  收到的** `input_tokens` / `output_tokens` 随之丢掉。重试三次的实际花费是三次之和，
+  `maxCostUsd` 只看到最后一次 —— 预算闸系统性偏松。
+- **现在**：适配器把已收到的计量挂到错误对象上，引擎记进失败 turn 的 span 并写 `usage.partial`
+  事件；`usageTotal` 因此包含失败尝试。
+- **验证**：`tests/engine/review-fixes.test.ts` 覆盖「首两次失败 + 第三次成功」的总账。
+
+### 流生命周期与跨进程兜底（2026-11-07 / 2026-11-09 ref-stream-janitor-singleton）
+
+- **修的是什么（跨进程）**：任务被另一个副本接管或已落终态时，本进程那条 SSE 不会自己结束 ——
+  客户端永远等不到 `end` / `closed`。此前由 `streamTask` 给**每个订阅**各建一个 5s 定时器去
+  `store.get` 判断：N 个并发连接 = N 个定时器 + N/5 QPS，SQLite 下就是 N/5 次读锁；`unref()`
+  只保证不挂住进程，不减读放大。
+- **现在**：`transport/stream-janitor.ts` 改成「组」的形状 —— 一拍里每个**任务**只读一次 store，
+  再把结论分发到该任务的所有订阅；定时器**有登记才存在**，最后一条注销即停。一拍里的意外
+  （判据抛错）被 catch 住，不会变成 `unhandledRejection` 打死宿主。
+- **其余收口**：`streamTask` 的 `onDone` 补 rejection 处理（store 抖动不再打死进程）；
+  SSE 单行复用 8M 码元上限并 flush 尾字节；上限判据改成**切出来的那一帧**（此前判整个 `buf`，
+  一次 read 交付多行大 chunk 会被误报成「单行超限」）；MCP HTTP 的 SSE 改增量读
+  （server 不关流不再让 `tools/call` 永挂）。
+- **验证**：`tests/transport/stream-janitor.test.ts`（六条故障路径 + 两条结构不变量），
+  行覆盖 100%、分支 89.58%；`tests/core/sse-text-stats.test.ts` 含「单帧 9M 仍要拒」的对照。
+
+### 持久化与恢复（2026-11-07 / 2026-11-09 ref-resume-dropped-refs）
+
+- **修的是什么（落库）**：`JSON.stringify` 把 `AbortSignal` 变成 `{}`、把 `ModelClient` 变成
+  `{messages:{}}`、把 `tools` 里的 run 函数丢掉。读回后这些空壳会在恢复段被当成真对象使用
+  （`combineSignals({})` 直接 TypeError，工具菜单半残）。现在三条 JSON store 统一在落库前剥离。
+- **修的是什么（剥离的副作用）**：剥离之后，「提交时本来没传 `client`」与「传了但被剥掉」在
+  读回时**完全同形**，于是 per-task 自定义 client（典型是 OpenAI 兼容端点）的任务重启续跑时会
+  **静默**退回 runner 的端点。现在剥离时记下清单（`__agentiaDroppedRefs`），装配处按 taskId
+  去重告警一次，写明「本段已退回 runner client / 装配菜单」与出路；键在装配前剔除，不进引擎。
+- **其余加固**：FileTaskStore 读失败出声且禁止 compact、半行写入回滚；SQLite 迁移事务化、
+  `healRow` 用旧 json 做 CAS；Redis `list()` 对 SCAN 结果去重、单 key 错不再整表 reject；
+  Memory 水合失败跳过回写；runtime 的手工 HITL 续跑不再重复 load/append。
+- **验证**：`tests/store/serialize-options.test.ts`（剥离标记三态 + 告警只响一次）；
+  `tests/transport/resume-scanner.test.ts`。
+
+### 依赖
+
+- 官网构建链：`astro` 7.3.8 → 7.4.5、`gsap` 3.15.0 → 3.15.1、`lenis` 1.3.26 → 1.3.27。
+- 开发链：dev-dependencies 组 5 项升级；`@biomejs/biome` 适配到 2.6.4
+  （排除文档/YAML 格式化、`useMathMinMax`）。
+- 框架本身**运行时依赖仍为 0**。
+
+## [0.10.5] - 2026-11-05
+
+### 变更
+
+本版包含**可信边界收紧、可授权可对外暴露的生产宿主面、以及「顺序由代码定」的子循环**：
+
+- ⚠️ **行为变更（安全修）**：`POST /tasks` 的 `options` 只认 `traceContext` / `maxCostUsd` /
+  `maxTotalTokens`，**其余键一律 400 并点名**；身份与租户改由宿主新增的
+  `resolveRunOptions(req, { route, principal })` 按请求注入（`authenticate` 的返回值从此不再被丢弃）。
+  在 HTTP 的 `options` 里传过 `model` / `blackboard` / `maxIterations` 的调用方**必须改接法**，
+  迁移见下方该条目。
+- 新增**任务对象级授权** `authorizeTask`（poll / approve / cancel / event / stream 逐动作判定，
+  读任务快照不触发惰性推进）与**可信审批人** `resolveApprovalActor`（由 principal 生成 `decidedBy`，
+  覆盖请求体自报身份）；两者缺省不配 = 旧行为。
+- 新增 `responseMode: 'full' | 'public'` 与 `exposeTraceEvents`：把 trace 的**存储面**与
+  **HTTP 暴露面**分开 —— 对外服务可以不返回 trace / 任务 spec / 挂起历史 / `ownerId`，
+  而 `TaskStore` 与 sinks 仍保留完整记录。
+- 新增 `runCapabilityLoop(ctx, opts)`：顺序由**代码**定、但活不过这次请求的子循环；
+  配 `@Tool({ approval: 'required' })` 就能挂起等人批，且与调用方**同一棵** trace。
+- 新增**能力契约** `buildCapabilityManifest` / `app.getCapabilityManifest()` 与 CLI `agentia manifest`
+  （真装配、不调模型）；四类能力可标 `metadata.{owner,version,risk,sideEffect}`，
+  hash 覆盖描述 / schema / 审批 / 元数据且**与输入顺序无关**，可当 PR 留档的比较基座。
+- 挂起恢复的**预算按任务累计**（`TaskRecord.usageTotal` + 段内 `usageOffset`），恢复段的会话输入
+  随任务落库（`sessionInput`）；新增 `maxToolResultChars`，把「回模型的截断」与「记账的截断」
+  拆成两条**互相独立**的闸。
+- 新增 `docs/multi-replica.md`（三种拓扑 + 六个会坏的点 + 故障转移 runbook）与
+  `examples/super-agent` 多工单编排示例（按产物自己复算 trace 图，已纳入 e2e 门禁）。
+- 另含公共导出补齐（`parseTaskRecord`、`CLIENT_RUN_OPTION_KEYS`、`TaskHttpResponse`、
+  `CapabilityMetadata` 等类型面扩展），详细条目如下。
+
+### ⚠️ 行为变更（安全修）：`POST /tasks` 的 `options` 白名单化 + 宿主 `resolveRunOptions` 缝（2026-11-04 ref-run-options-trust-boundary）
+
+- **修的是什么**：`POST /tasks` 此前把 `body.options` **整体透传**给引擎，而它是
+  `RunInvocationOptions` 的全套旋钮。任何能调这个端点的人都能写
+  `{ blackboard: { tenant: '别人的租户' } }`，而 usage-guide §6.6 的多租户配额配方第一步正是
+  「用黑板存 tenant」⇒ 额度记到别人头上。同一件事在 `POST /run` 上却是**死路**（body 是 `RunInput`，
+  没有 options 入口）：需要身份的那条拿不到，拿得到的那条不可信。
+- **现在**：客户端只能设 `traceContext` / `maxCostUsd` / `maxTotalTokens`，**其余键一律 400 并点名**
+  （`blackboard` / `tools` / `model` / `fallbacks` / `priceOverrides` …）。身份 / 租户由新增的
+  `HttpHandlerOptions.resolveRunOptions(req, { route, principal })` 按请求注入 —— `authenticate`
+  的返回值从此**不再被丢弃**，作为 `principal` 传进该钩子（此前注释建议「存在钩子自己的闭包里」，
+  但闭包与 run 之间没有任何关联手段）。`/run` 与 `/tasks` 都过这条缝。
+- **合并语义（三条各不相同）**：`blackboard` **整体替换**（身份载体不允许与客户端键合并）；
+  `labels` 按键盘合并、服务端胜；预算与客户端值取**更严者** —— 上限不能由叫价方抬高。
+- **迁移**：若你在 HTTP 的 `options` 里传了上述按键之外的字段（例如 `maxIterations` / `model` /
+  `blackboard`），请求现在会 400。这些旋钮请改成应用级配置（`createApp` / `RunnerOptions`），
+  或由宿主在 `resolveRunOptions` 里注入。TS 侧 `TaskSubmitBody.options` 从 `RunInvocationOptions`
+  收窄为 `ClientRunOptions`，这类写法会**当场编译报错**。
+- **验证**：`tests/transport/http-run-options.test.ts`（9 例）+ `tests/transport/run-options.test.ts`（9 例）。
+  反向变异 4/4 咬住（放行未知键 / 上限取更宽 / 钩子结果不生效 / `principal` 不转交）；
+  实测读数：`options.blackboard` → 400 且任务表为空；宿主注入后工具方法体里读到的是
+  `tenant-of-u-42`（来自 `authenticate`）。决策：`docs/spec.md` §10 ref-run-options-trust-boundary。
+
+### 新增：`runCapabilityLoop(ctx, opts)` —— 代码控制顺序的子循环（2026-11-04 ref-run-capability-loop）
+
+- **补的是哪一格**：顺序由**代码**定、但活**不过**这次请求 —— `@SubAgent` / `@Skill` 的子循环审批挂不起
+  整条 run、`contextPolicy` 也不进子循环；`AsyncRunner` 的 task 能挂起能续跑，但要为它造一条任务记录。
+  中间这一格此前只能手写 `runAgentScoped` + 自己转发 `ToolRunContext` 的七个旋钮（漏一个是**静默**的）。
+- **形状**：`runCapabilityLoop(ctx, { name?, input, system?, tools?, model?, contextPolicy?, resultSchema?, onText? })`
+  → `{ text, typed, stopReason, iterations, spanId, error? }`。内部 `...forwardToolContext(ctx)` 取自唯一单源、
+  会 combine「放弃等待」信号、自建一个 `capability` span（**同树**，`runId` 不多一个）。
+- **配 `@Tool({ approval: 'required' })` 就能挂起等人批**：审批落在**外层工具调用**上，于是
+  「代码定顺序 + 子循环可裁剪 + 人批可挂起 + 同一棵树」四样可以同时要。
+- **刻意不导出 `runAgentScoped`**：它把「哪些旋钮必须下交」的责任交给调用方，而 TS 对漏写可选字段
+  不报错。公共面只给「不可能漏」的那个形状。`@SubAgent` / `@Skill` 的行为一个字没变。
+- **验证**：`tests/toolkit/capability-loop.test.ts`（5 例：同树 / `typed` / `contextPolicy` 生效 /
+  预算护栏经 ctx 透传 / 工具菜单不继承）。反向变异：去掉 `...forwardToolContext(ctx)` ⇒ 预算用例红。
+
+### 新增：`examples/super-agent` 多工单编排示例，并纳入 e2e 门禁（2026-11-03）
+
+- **示例形状**：Router 把一句目标拆成可并行工单，Worker 走 `AsyncRunner` 的 **task**（不是 `@SubAgent`）、
+  各自独立上下文；改数据的动作标 `approval: 'required'`，挂起等人批后恢复；四棵 trace 靠 `traceContext`
+  连成一条链。`npm run demo` 零网络、零 key、约 30ms 自检。
+- **门禁**：`scripts/e2e-examples.ts` 第 11 步（`verifySuperAgent`）按示例自己的 `npm run build` 构建，
+  再跑 dist 形态的 demo，然后**从它落的产物自己复算一遍 trace 图**（唯一的根 / 每条树几跳回家 /
+  哪条是恢复段），不转发 demo 的 `hopsTo` 结论。产物只在 `SUPERAGENT_DEMO_OUT` 指向文件时写，
+  交互式 demo 保持零副作用。`examples/super-agent/src` 同时进了 `tsconfig.tests.json`（类型层面也纳入门禁）。
+- **反向验证（三个变异 + 一个反方向探针）**：中和 demo 全部断言后 —— 去掉 Worker 的 `traceContext`
+  ⇒ 门禁红「每条 trace 都要沿 links 回得到 Router，断了的是 […]」；摘掉 `write_file` 的 `approval`
+  ⇒ 门禁红「要审批的工单应产生两棵 trace（挂起段 + 恢复段），实际 1」。反方向：实现不动、只让 demo 的
+  `hopsTo` 谎报一跳 ⇒ 门禁**仍绿**且自己算出 `worker-fix@2` —— 它算的是产物，不是文案。还原后 `sha256` 逐字节一致。
+
+### 文档：多副本部署参考架构（新增 `docs/multi-replica.md`）
+
+- **补的是哪一格**：`deployment.md` §8 此前只有一句话结论（「单宿主写者 + 认领语义不等于分布式锁」），
+  没有回答「那多副本到底怎么摆」。文档缺口会让每个接入方各自试错，而试错的代价是**同一任务跑两遍**。
+- **内容**：三种拓扑的选型判据（单副本 / 单机多进程 / 单写者+只读副本 / 按 `taskId` 分片）、
+  六个会坏的点（写路径交错、审批双派发、唤醒抢所有权、`cancel` 打不到 owner、跨进程 SSE、
+  定时任务每个副本各触发一次）、故障转移 runbook、粘性路由三种实现、多副本自检清单。
+- **一个此前没被写下来的陷阱**：`createHttpHandler` 的 `runner` 是可选的，缺省会造一个
+  `InMemoryTaskStore` 的 runner（`http.ts` + `async.ts` 两处缺省）。漏接线的副本表现为
+  「同一个任务 id 在 A 查得到、B 返 404」，**不报错也不告警**。
+- **如实标注的边界**：`approve` / `signal` 的互斥是**进程内**的（`#inflight` Map），
+  跨进程并发会各派发一次；`drain()` 是单向闩，停机后被拒的记录只能等下次启动认领。
+  这些是设计取舍，不是待修缺陷 —— 文档的职责是让部署方知道要自己兜。
+
+### 新增：任务对象级授权 `authorizeTask` 与可信审批人 `resolveApprovalActor`（2026-11-05 ref-http-task-authorization）
+
+- **补的是哪个洞**：`authenticate` 只回答「你是谁」，不回答「你能不能碰这个任务」。多租户宿主
+  此前只能在**每个**端点里自己查一次，漏一处的表现是「别人的任务能被取消 / 被批准 / 被读事件」。
+- **形状**：`authorizeTask(req, { action, taskId, task, principal })` —— action 取
+  `poll` / `approve` / `cancel` / `event` / `stream`，返回 `false` → 403，抛 `HttpException`
+  按其状态码回；审批与事件的判定发生在**读 body 之前**。缺省不配 = 旧行为（不拦）。
+- **为什么不走 poll 取快照**：它直接读 `runner.store.get`。走 poll 会让「查一次权限」触发
+  惰性超时判定与到期推进 —— 授权检查不该有副作用（`docs/spec.md` §10 该条有完整理由）。
+- **`decidedBy` 不再是自报字段**：配 `resolveApprovalActor` 后由 principal 生成并**覆盖**请求体；
+  返回 `undefined` = 不记审批人，空字符串算宿主配置错误（500）。不配则 `decidedBy` 仍只是
+  调用方填写的审计字段，不是可信身份。
+- **验证**：`tests/transport/http-authorization.test.ts`（五个动作 × 拒/过/抛错映射）+
+  `tests/transport/httpApproval.test.ts` 的可信审批人用例。
+
+### 新增：`responseMode: 'public'` —— trace 的存储面与 HTTP 暴露面分开（2026-11-05 ref-public-response-mode）
+
+- **补的是哪个洞**：trace 既是本框架的卖点，也是**信息泄露面** —— 它含工具入参出参、
+  任务 `spec.messages`、挂起历史与 `ownerId`。此前接对外服务只有「全关端点」或「全露」两个选择。
+- **形状**：`responseMode: 'full'`（缺省，历史形状）/ `'public'`；后者从 run / task 响应里去掉
+  trace、任务 spec、`suspendedMessages`、`ownerId` / `pendingEvents`，并**默认关闭** SSE 的
+  `trace.event` 帧。`exposeTraceEvents: true` 可单独开帧，但不会把完整 trace 加回 `run.end`。
+- **边界**：它只改 HTTP 输出 —— `TaskStore` 与 `TraceSink` 的记录**保持完整**（脱敏不是存储职责）；
+  也不能替代 `authorizeTask`，两者一个管「这条响应里有什么」，一个管「你能不能读这条任务」。
+- **单源**：公共投影只在 `http-shapes.ts` 一处实现，所有任务响应与 `task.end` 共用，
+  避免某条路由漏脱敏。验证：`tests/transport/http-response-mode.test.ts`。
+
+### 新增：能力契约 `agentia manifest` 与四类能力的 `metadata`（2026-11-05 ref-capability-manifest）
+
+- **补的是哪个洞**：多人协作时「这次 PR 到底改了哪个能力的哪个 schema」只能靠读 diff。
+- **形状**：`@Tool` / `@Skill` / `@SubAgent` / `@Prompt` 增加可选
+  `metadata: { owner?, version?, risk?, sideEffect? }`；`buildCapabilityManifest` /
+  `app.getCapabilityManifest()` 从**最终菜单**产出 `{ app, hash, capabilities }`，
+  hash 覆盖名称 / 类别 / description / schema / strict / 审批 / 元数据，**与输入顺序无关**
+  ⇒ 可以直接当 PR 留档的比较基座。CLI `agentia manifest` 真装配 `src/app.ts`、**不调用模型**。
+- **不做什么**：它是留档与比较基座，不替代 code review，也不执行安全策略。
+- **验证**：`tests/toolkit/manifest.test.ts`；`scripts/e2e-cli.ts` 真跑产物路径。
+
+### 改动：恢复段预算按任务累计 + 工具结果回模型截断（2026-11-05 ref-durable-resume-accounting / ref-tool-result-limit）
+
+- **预算**：`TaskRecord` 新增 `usageTotal`（每个已收尾段折进去）与 `sessionInput`（首个挂起段
+  存下本轮输入，恢复成功后补写会话、终态清除）。恢复段经段内 `usageOffset` 参与
+  `maxTotalTokens` / `maxCostUsd`，主/子循环同口径；`trace.totalUsage` 仍只代表本段。
+- **如实标注的边界**：进程崩在「模型已花 / 工具已执行、结果尚未落库」那个窗口时，那笔用量
+  **追不回来** —— 它不是精确的全局账单。旧版本留下的挂起记录没有 `sessionInput`，仍只能跳过补写。
+- **`maxToolResultChars`**：新旋钮，只裁**回模型**的 `tool_result`（缺省 / `false` = 不截断，
+  `0` = 截到零长度并留 `…(+N)`），经 `forwardToolContext` 透传嵌套循环；与 `maxEventChars`
+  （只管记账）**互相独立**、不改变副作用。验证：`tests/engine/tool-result-limit.test.ts`
+  真穿两回合，断言模型看到截断而 trace 仍完整。
+
+### 新增：`parseTaskRecord` 公共导出（2026-11-05 ref-task-record-parser-public）
+
+- 外部 `TaskStore` 不再用 `JSON.parse(raw) as TaskRecord` 绕过旧形状归一：
+  公共入口做 JSON 解析 + 形状守卫 + 旧版本归一，坏 JSON 抛错、非记录返回 `undefined`
+  （坏数据吞不吞仍由各 store 决定）。`docs/database.md` 的 MySQL 骨架改走该入口，代码围栏真编译。
+
 ## [Unreleased]
 
 ## [0.10.4] - 2026-10-28
@@ -4148,7 +4426,9 @@ toolkit 142 / runtime 55 / engine 403 / container 10 / store 55 —— 全绿。
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.4...HEAD
+[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.6...HEAD
+[0.10.6]: https://github.com/migoric/agentia/releases/tag/v0.10.6
+[0.10.5]: https://github.com/migoric/agentia/releases/tag/v0.10.5
 [0.10.4]: https://github.com/migoric/agentia/releases/tag/v0.10.4
 [0.10.3]: https://github.com/migoric/agentia/releases/tag/v0.10.3
 [0.10.2]: https://github.com/migoric/agentia/releases/tag/v0.10.2

package/README.en.md

@@ -8,7 +8,7 @@
 with decorators + DI and a main agent orchestrates them; every run yields structured output and an
 observable call tree (trace, cost, metrics).
 
-**1 package · ≈2 MB · 0 runtime dependencies · 90+ guards** — recomputed by
+**1 package · ≈3 MB · 0 runtime dependencies · 90+ guards** — recomputed by
 `tests/docs/scoreboard.test.ts` on every run.
 
 > This is a **summary**, kept short on purpose (a hand-maintained full translation drifts). The

package/README.md

@@ -10,7 +10,7 @@ observable call tree (trace, cost, metrics).
 
 面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。
 
-**1 个包 · ≈2 MB · 0 运行时依赖 · 90+ 条守卫** —— 由 `tests/docs/scoreboard.test.ts` 每次现场复算。
+**1 个包 · ≈3 MB · 0 运行时依赖 · 90+ 条守卫** —— 由 `tests/docs/scoreboard.test.ts` 每次现场复算。
 
 - [安装与配置](#安装与配置)
 - [快速开始](#快速开始)
@@ -43,7 +43,7 @@ npm run dev -- "你的问题"               # = tsx src/main.ts，跑一次并
 - 工程内命令：`npx agentia g tool fetch-weather` / `npx agentia doctor` / `npx agentia --version`；
   想全局装：`npm i -g @migor/cli`。
 
-> **版本**：`0.10.4`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。
+> **版本**：`0.10.6`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。
 
 ## 快速开始