@migor/agentia 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -5,6 +5,158 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [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 +4300,8 @@ 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.5...HEAD
+[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.5`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。
 
 ## 快速开始
 

package/dist/AGENTS.md

@@ -123,6 +123,7 @@ cd my-service && npm install
 npm run dev                      # = agentia dev：本地 inspector 面板（输入 prompt / 选能力 / 选工作目录）
 npx agentia g tool fetch-weather # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
 npx agentia doctor               # 静态体检（未登记/悬空/命名/重复）
+npx agentia manifest             # 真实装配 → 能力契约 JSON（不调用模型）
 npx agentia --version            # CLI 版本（= -v）
 ```
 
@@ -326,6 +327,7 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `name` | 模型可见的工具名，缺省取方法名（建议 snake_case） |
 | `strict` | 透传给 Anthropic 的 strict 模式（**框架不校验 schema 合规性**） |
 | `approval` | `'required'` = 每次调用先挂起等人工审批（HITL，见 §6.6「人工审批」） |
+| `metadata` | 可选 `{ owner?, version?, risk?: 'read'\|'write'\|'external', sideEffect?: 'none'\|'idempotent'\|'non-idempotent' }`；进能力 manifest，供 owner 分工与变更审查 |
 
 ### `@Skill(spec: SkillSpec)`
 
@@ -338,6 +340,7 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
 | `tools` | `ctx.llm()` 可调工具：**provider token 列表**（复用该 provider 的能力菜单），或 `'<token>/<能力名>'` 能力级路径（只引菜单里的单个能力） |
+| `metadata` | 同 `@Tool`：owner / 版本 / 风险 / 副作用幂等性，进能力 manifest |
 
 技能方法体拿到的第二参是 `SkillContext`：`ctx.llm({ prompt })` 才会真正调模型（脚本式，调几次由你写死）。
 
@@ -354,6 +357,7 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
 | `resultSchema` | 给出后子 agent 用隐藏 `submit_result` 提交结构化结果 |
+| `metadata` | 同 `@Tool`：owner / 版本 / 风险 / 副作用幂等性，进能力 manifest |
 
 子 agent 是**独立循环 + 裁剪上下文**：主 agent 的历史它看不到，只有最终文本（或 `{ report, result }`）以 tool_result 回流。
 
@@ -365,6 +369,7 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `name` | 缺省取方法名 |
 | `schema` | 模板化入参 schema；缺省空对象（无参资产） |
 | `version` | 资产版本号（git hash / `'v3'` 等）；装配期随能力名收集，每次 run 落 run 根 span 的 `prompts.versions` attribute —— 见 §6「提示词版本化」。缺省（无版本）则该能力不进表 |
+| `metadata` | 同 `@Tool`；`metadata.version` 缺省回落 `version`，两项都给时以 metadata 为准 |
 
 `@Prompt` **只支持方法形态**（标准装饰器下字段拿不到值/类引用）。实例方法与静态方法都**沿继承链**收集（父类的 `@Prompt` 资产子类自动带上）。方法体内用 `asset(import.meta.url, './x.md')` 读同目录长文本。
 
@@ -401,6 +406,7 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `toolTimeoutMs` | 缺省单工具超时（毫秒）；超时该条 tool_result 记 is_error，不杀 run |
 | `maxToolConcurrency` | 缺省同回合并行工具上限；不设 = 不限（全并行） |
 | `maxEventChars` | 缺省 trace 事件正文截断上限（可被单次 run 覆盖）：数字 = 入参/出参统一用该上限，`false` = **不截断**（完整正文进 trace，面板里能展开看全文）；不设 = 框架缺省 |
+| `maxToolResultChars` | 缺省单条工具结果**回模型**的字符上限：非负安全整数；`false` / 不设 = 不截断，0 = 截到零长度并留 `…(+N)`。与 maxEventChars 正交，会透传子循环 |
 | `traceLimits` | **记账的数量上限** `{ maxEvents? }`（可被单次 run 覆盖）：整条 trace 的事件总数闸。超限即停止记账，并在 run 根留**两笔** `trace.truncated` —— **起点标记** `{limit}`（断点在这里）＋ **收尾摘要** `{droppedEvents, limit}`（丢了多少），两笔**同时**进交付的 trace 与 `onTraceEvent` 增量流。缺口位置可预测（尾巴）且**有计数**。与管**长度**的 `maxEventChars` 正交（一个管「多长」、一个管「多少」）；不设 = 不限（全量记账是本框架的承诺）。坏值（NaN / 负数 / 小数）在 run 入口抛 `TypeError` |
 
 ### `app.run(messages, opts?: RunAppOptions)`
@@ -433,7 +439,9 @@ run 在**文件末尾** —— 取最早那种写法在长跑 dev 环里等于
 | `onUnpricedModel` | 单次覆盖未定价回调（**是函数，因此不在 transport 的 `RunInvocationOptions` 里** —— 异步宿主不会替你传） |
 | `toolTimeoutMs` | 单个工具执行超时（毫秒）；超时该条 tool_result 记 is_error，run 继续 |
 | `maxToolConcurrency` | 同回合并行工具上限；缺省不限 |
-| `maxEventChars` | trace 事件正文截断上限（字符）：数字 = 入参/出参统一用该上限，`false` = **不截断**；缺省按类型收敛（入参/成功出参 2000、失败出参 1000）。**透传给子 agent/skill 的子循环** —— 同一棵调用树上口径一致。只影响**记账**，回给模型的 tool_result 永远完整 |
+| `maxEventChars` | trace 事件正文截断上限（字符）：数字 = 入参/出参统一用该上限，`false` = **不截断**；缺省按类型收敛（入参/成功出参 2000、失败出参 1000）。**透传给子 agent/skill 的子循环** —— 同一棵调用树上口径一致。只影响**记账**；回模型上限另看 `maxToolResultChars` |
+| `maxToolResultChars` | 单次覆盖工具结果回模型的字符上限；缺省 / false = 不截断，0 = 截到零长度 |
+| `usageOffset` | 本段之前已落账的 `Usage`；通常只由 AsyncRunner 在挂起恢复时注入，让预算按整任务累计。HTTP 客户端不能自填 |
 | `session` | 会话持久化 `{ store, id }`：run 前拼历史、成功收尾追加本轮（见 `SessionStore`） |
 | `sessionId` | 会话**引用**（可序列化）：**只被异步宿主消费** —— 「`sessionId` + runner 的 `sessionStore`」那条路（任务里只落 id，store 实例不可序列化；runner 没配 `sessionStore` 而任务带了它 ⇒ submit 当场报错）。⚠️ 直接 `app.run` 传它**不生效**（不建 `session.id`、不接历史），入口会 `console.warn` 一次指出改用上一行的 `session: { store, id }`；只要 run 根的 `session.id` 标记而不要历史，直连 `executeRun` / `runAgent` 的引擎级 `sessionId`（见 §6.4「提示词版本化与会话标记」） |
 | `memory` | 跨 run 记忆 `{ store, keys }`：run 前水合进 blackboard（用户种子优先）、收尾写回；与 `session` 正交（见 `MemoryStore`） |
@@ -557,12 +565,56 @@ run 内取上下文（黑板 / `@Skill` 第二参）、把装饰器装配成 app
 | `model` | 本次技能的缺省模型 |
 | `llm` | 受限子运行：`await ctx.llm({ prompt })` / `{ messages, system, model, maxTokens, maxIterations }` |
 
+#### `runCapabilityLoop(ctx, opts)` —— 代码控制顺序的子循环（2026-11-04）
+
+四类能力之外还有一格：**顺序由你的代码定、但活不过这次请求**。`@SubAgent` / `@Skill` 的流程由
+模型或方法体驱动、子循环里的审批挂不起整条 run；`AsyncRunner` 的 task 能挂起能续跑，但要为它
+造一条任务记录。中间这一格就是本原语（它把 `runAgentScoped` 包成「旋钮不可漏」的形状 ——
+`ToolRunContext` 上那七个必须原样下交的键一次取自单源，使用方接触不到）。
+
+| 选哪个 | 判据 |
+|---|---|
+| `@SubAgent` | 流程交给**模型**决定，子 agent 自己挑工具 |
+| `@Skill` + `ctx.llm()` | 流程由方法体定，但**不要**结构化结果 / 裁剪 / 人批 |
+| **`runCapabilityLoop`** | 流程由方法体定，且需要 `contextPolicy`（长跑不撞上限）/ `resultSchema` / 同一棵树 |
+| `AsyncRunner.submit` | 这件事会**活过这次请求**（耐久、崩溃续跑、审批原生） |
+
+```ts
+@Tool({
+  name: 'approve_invoice',
+  description: '核对并批准一张发票（会改账，需人工批准）',
+  inputSchema: INVOICE_SCHEMA,
+  approval: 'required', // 审批落在**这个工具调用**上 ⇒ 整条 run 可挂起等人批
+})
+class InvoiceTool {
+  constructor(private readonly client: ModelClient) {}
+
+  async run(input: { id: string }, ctx: ToolRunContext) {
+    const ledger = await runCapabilityLoop(ctx, {
+      name: 'invoice-review', // trace 里那个 capability span 的名字
+      input: `核对发票 ${input.id}：先查合同，再比对金额`,
+      tools: [contractTool, ledgerTool], // 子循环自己的菜单（不继承主菜单）
+      contextPolicy: createBudgetPolicy({ maxTokens: 40_000 }), // 长跑子循环不撞上限
+      resultSchema: VERDICT_SCHEMA,
+    });
+    // 成败自己判（框架不替它抛）：非正常收尾时 stopReason 会告诉你为什么
+    if (!isSuccessStopReason(ledger.stopReason)) throw new Error(`核对失败：${ledger.stopReason}`);
+    return ledger.typed;
+  }
+}
+```
+
+三条边界（都是刻意）：**不自开 run 根**（`llm.turn` 挂在本条 run 的树里，`runId` 不会多一个）；
+**不继承主 run 的 `fallbacks` 链**（同 `runAgentScoped` 的有意边界）；**挂起不穿透** ——
+子循环里触发 `deferUntil` / 审批挂起时，语义同其它嵌套能力（以 `is_error` 交回，整条 run 不挂起）。
+
 #### 装配与执行
 
 | API | 说明 |
 |---|---|
 | `createApp` | 装配应用（同步；带 `discover` 时为 `Promise<AgentApp>`） |
-| `AgentApp` | `run` / `tools` / `container` / `name` |
+| `AgentApp` | `run` / `tools` / `container` / `name` / `getCapabilityManifest()` |
+| `buildCapabilityManifest` | 从最终菜单生成 `{ app, hash, capabilities }`；hash 覆盖描述/schema/审批/元数据且与顺序无关，适合 PR 留档比较 |
 | `defineModule` | 定义能力包 |
 | `executeRun` | 低层 run 入口（自己管 `Run`/trace sink/记忆） |
 | `runAgent` | 更底层：只要一个循环 + trace，不管 run 生命周期 |
@@ -621,6 +673,7 @@ const app = await createApp({ ... });
 | `FileTaskStore` | JSONL 耐久存储（`compact()` 可压实日志） |
 | `SqliteTaskStore` | `node:sqlite` 耐久存储（WAL + busy_timeout） |
 | `RedisTaskStore` | duck-typed Redis 存储（可设 `ttlSeconds`）；客户端结构面 `get` / `set` / `del` / `keys`（或 `scanIterator`），外加设 TTL 时必需的 `expire`。`set` **只传两参** —— 尾参的选项形状两家相反：ioredis 认位置参数 `('EX', n)`、node-redis 认对象 `{ EX: n }`，取任何一种都会在另一家上失效（ioredis 会把对象字符串化成 `"[object Object]"` 报语法错；**node-redis 的 `SET` 只声明三个形参，位置参数被静默丢弃**）。所以 TTL 一律走 `expire(key, seconds)`（两家同名同形）；设了 `ttlSeconds > 0` 却没给 `expire` 时**构造期抛错**，不静默丢掉 TTL |
+| `parseTaskRecord` | 自定义 store 的公共读回入口：JSON 解析 + 形状守卫 + 旧版本归一；坏 JSON 抛错，非记录返回 undefined |
 
 **`compact()` / `close()` 是接口上的可选能力，但由宿主按需调**：`FileTaskStore.compact()`
 （压实 JSONL：一 task 一行、丢掉历史覆写行）与 `SqliteTaskStore.close()` 此前只活在具体类上 ——
@@ -713,7 +766,7 @@ npm run client    # 另一个终端：把四个 RPC 跑一遍
 | 端点 | 请求 | 响应 |
 |---|---|---|
 | `POST /run` | body 是 `RunInput`（string / messages / `{prompt\|text\|messages}`）；带 `Accept: text/event-stream` 则走 SSE | 200 `{ runId, status, stopReason, finalText, typed?, trace, error? }` —— **`status=failed` 也照返 200**（`rethrow:false` 语义：硬失败以 `error` 字段表达，不用 HTTP 错误码） |
-| `POST /tasks` | `{ input, idempotencyKey?, options? }` —— `input` 同 `RunInput`；`options` 是 `RunInvocationOptions` | 202 `TaskRecord`（`status: 'queued'`）；同 `idempotencyKey` 未失败则去重、直接返回既有记录（**同步 store** 当场判定；**异步 store** 下只保证**同进程内并发提交**不重复执行，跨进程与终态后重提仍是 at-least-once —— 见 §7「同键去重的能力边界」） |
+| `POST /tasks` | `{ input, idempotencyKey?, options? }` —— `input` 同 `RunInput`；`options` 只接受**白名单**：`traceContext` / `maxCostUsd` / `maxTotalTokens`（多一个键 → 400，含 `blackboard` / `tools` / `model`）。**身份与租户不走 body** —— 由宿主的 `resolveRunOptions` 按请求注入 | 202 `TaskRecord`（`status: 'queued'`）；同 `idempotencyKey` 未失败则去重、直接返回既有记录（**同步 store** 当场判定；**异步 store** 下只保证**同进程内并发提交**不重复执行，跨进程与终态后重提仍是 at-least-once —— 见 §7「同键去重的能力边界」） |
 | `GET /tasks/:id` | — | 200 `TaskRecord`；不存在 → 404。**停机中仍可轮询**（否则拿不到在飞任务的结果） |
 | `GET /tasks/:id/stream` | — | **任务进度流（SSE）**：先在 `id:` 里给流序号，逐帧下发 `trace.event`（body 即 `TraceRecordEvent`），终态发 `task.end` 并关闭。断线重连带 `Last-Event-ID`（或 `?from=<序号>`）即可续订 —— 只补该序号之后的事件。缓冲超限先发一帧 `stream.truncated{droppedBefore}`；别的进程在跑的任务发 `stream.unavailable` 后收口（**不假装实时**）。任务不存在 → 404；方法不对 → 405。⚠️ 它的读者是**旁观者**：背压/断开只收口这条流，**不中止任务** |
 | `POST /tasks/:id/approve` | `{ decisions: { <tool_use_id>: { approved, reason? } }, decidedBy? }` | 200 `TaskRecord`（HITL 审批：批准/拒绝挂起任务，见 §6.6「人工审批」）；任务不存在 → 404；**挂起原因不是 `approval`**（含未挂起）→ 409；`decisions` 里有不在该任务 `pendingApprovals` 里的 id → **400（整批拒，记录一字不动）**；body 非法 → 400。**停机中仍可审批**（与 GET 轮询同理由） |
@@ -725,6 +778,10 @@ npm run client    # 另一个终端：把四个 RPC 跑一遍
 方法不符 → 405（带 `Allow` 头）；路径不符 → 404；body 非法 JSON → 400；body 超 `maxBodyBytes` → 413；
 `POST /run` 超 `maxConcurrentRuns` → 503 + `Retry-After`；停机中 `POST /run`、`POST /tasks` → 503。
 
+上表是缺省 `responseMode:'full'` 的兼容形状。对外多租户服务建议 `responseMode:'public'`：
+run/task 响应不再携带 trace、spec.messages、suspendedMessages 与 ownerId，SSE 的 trace 帧也默认关；
+它不改变任务库和 sinks 的完整记录。对象级授权由 `authorizeTask` 另行决定，两者不能互相替代。
+
 #### 本地怎么调（可直接复制的命令）
 
 ⚠️ 先认下这条，否则会照着别的框架的经验找错东西：**没有「一个业务一个 URL」的接口层**。
@@ -774,7 +831,12 @@ const handler = createHttpHandler(callable, { runner });
 
 | 选项 | 说明 |
 |---|---|
-| `authenticate` | 入口鉴权钩子：**除 `/healthz` 与 `/metrics` 外所有路径**都过它，且在**读 body 之前**（未通过就不收 body）。正常返回即通过；抛 `HttpException` 按其 `status`/`body` 回；抛别的错误回 401，原文只进服务端日志。框架**不实现策略**（不读 env、不碰凭据） |
+| `authenticate` | 入口鉴权钩子：**除 `/healthz` 与 `/metrics` 外所有路径**都过它，且在**读 body 之前**（未通过就不收 body）。正常返回即通过，**返回值作为 `principal` 交给 `resolveRunOptions`**；抛 `HttpException` 按其 `status`/`body` 回；抛别的错误回 401，原文只进服务端日志。框架**不实现策略**（不读 env、不碰凭据） |
+| `resolveRunOptions` | `(req, { route, principal }) => { blackboard?, labels?, maxCostUsd?, maxTotalTokens? }` —— **身份 / 租户 / 配额封顶的唯一可信通道**（`/run` 与 `/tasks` 都生效）。`blackboard` **整体替换**、`labels` 按键盘合并（服务端胜）、预算与客户端值取**更严者**（上限不能由叫价方抬高）。抛 `HttpException` 按其状态码回。为什么必须有它：`POST /tasks` 的 `body.options` 走白名单之后，客户端已经**设不了** `blackboard` —— 身份不从这里进就没有地方进了（见 §6.6「多租户配额」） |
+| `authorizeTask` | `(req, { action, taskId, task, principal })`：任务控制面的**对象级授权**，action 为 `poll/approve/cancel/event/stream`；返回 false → 403，抛 HttpException 按状态码回。审批/事件在读 body 之前判；缺省不拦（旧行为） |
+| `resolveApprovalActor` | `(req, principal) => string\|undefined`：从认证结果生成可信审批人；配置后**覆盖**审批 body 的自报 `decidedBy`。空字符串按宿主配置错误 500 |
+| `responseMode` | `'full'`（缺省，旧形状）/ `'public'`：公共模式去掉 run/task 响应的 trace、任务 spec、挂起历史与 ownerId；TaskStore/sinks 仍保留完整记录 |
+| `exposeTraceEvents` | 是否开放 `/run` 与 `/tasks/:id/stream` 的 trace 事件；缺省 = `responseMode==='full'`。公共模式下显式 true 可单独开放，但不会把完整 trace 加回 run.end |
 | `metrics` | 指标出口：给 `metricsSink()`（或任意 `{ render() }` / 返回字符串的闭包）后，`GET /metrics` 回它的 Prometheus 文本。**不鉴权**（拉取端在集群内网）；要保护请放反代后面。不给则该路径 404。⚠️ 这只管**渲染** —— 数字要真的累计，必须把**同一个** sink 注册进 `createApp({ sinks: [metrics] })`（它靠 run 收尾投递，不自己埋点），否则 `/metrics` 恒为 0 **且不报错** |
 | `maxBodyBytes` | 请求 body 上限（字节），超限回 413；缺省 1 MiB。构造期校验：必须 > 0 或 `Infinity` —— 0 会让**每个带 body 的请求**都 413（`POST /run` / `POST /tasks` / 审批全废），故直接抛错。⚠️ 还挡 `Number('') === 0`：从**空的环境变量**读出来的配置会静默变成「拒绝一切」 |
 | `maxConcurrentRuns` | 同时在跑的 `POST /run` 上限，超限回 503 + `Retry-After`；缺省 32（传 `Infinity` 恢复无上限）。构造期校验：必须 > 0 或 Infinity —— NaN 会让闸门静默失效、0/负数会全部 503，故直接抛错 |
@@ -809,6 +871,13 @@ const handler = createHttpHandler(app, {
   // 只给缝：token/JWT/签名策略由你的宿主或反代实现
   authenticate: (req) => {
     if (req.headers['x-api-key'] !== expected) throw new HttpException(401, { error: '无效凭据' });
+    // 返回值不是白抛的：它就是 principal，下一步交给 resolveRunOptions
+    return { userId: String(req.headers['x-user-id'] ?? '') };
+  },
+  // 身份 / 租户进 run 的唯一可信通道（客户端在 body 里填不了黑板）
+  resolveRunOptions: (_req, { principal }) => {
+    const { userId } = principal as { userId: string };
+    return { blackboard: { tenant: tenantOf(userId) }, labels: { user: userId } };
   },
 });
 
@@ -1679,6 +1748,9 @@ createApp({ system, providers: [...], middleware: [quota], sinks: [billing] });
 
 - 拦下来的那次 run **仍然要记账**（模型的钱已经花了）—— 记账在 sink 里、拦截在 middleware 里，两者独立。
 - 被拦下的能力**不会执行**（副作用不发生），但 run 继续跑（模型可以换路）。
+- ⚠️ **`tenant` 从哪来**（2026-11-04 起）：只能由宿主注入 —— `createHttpHandler({ authenticate, resolveRunOptions })` 里
+  `resolveRunOptions` 返回 `{ blackboard: { tenant } }`。客户端在 `POST /tasks` 的 `options` 里**填不了黑板**
+  （白名单外即 400）：这条配方此前照着抄会被绕过 —— 谁能调 `/tasks` 谁就能自填 `tenant`，额度记到别人头上。
 
 #### 人工审批
 
@@ -1733,7 +1805,9 @@ class DeployTools {
    `{ decisions: { '<tool_use_id>': { approved: true } }, decidedBy: 'alice' }`
    （或直接 `runner.approve(taskId, decisions, { decidedBy })`）。**逐 tool_use_id 幂等**
    （第一次决定赢，重复提交不推翻）。决定**随任务落库**（`TaskRecord.approvals`，
-   进程重启不丢）；待决集合齐了任务自动恢复执行。
+   进程重启不丢）；待决集合齐了任务自动恢复执行。生产 HTTP 端建议同时配置
+   `authorizeTask`（谁能批这个任务）与 `resolveApprovalActor`（从 principal 生成 decidedBy，
+   覆盖请求体自报身份）；否则 `decidedBy` 只是调用方填写的审计字段，不是可信身份。
 4. 恢复时：**批准**的工具正常执行（工具体内经 `ToolRunContext.approval` 读到自己的决定 —
    谁批的、什么时候、什么理由）；**拒绝**的工具得到 `tool_result(is_error: true,
    content: '审批被拒绝：…')` —— 理由回给模型，可自行换路。恢复后再遇未决审批 ⇒
@@ -1901,7 +1975,7 @@ const callable = {
 | 任务进度流的边界（内存 / 跨进程） | `GET /tasks/:id/stream` 的事件缓冲在**跑任务的进程内存**里：每任务最近 500 条（可用 `AsyncRunner` 的 `streamBufferEvents` 调，须为正整数，坏值构造期抛错），超限丢**最旧**并先发一帧 `stream.truncated`；终态流只留最近 16 条。**没跑完**的流另有一道**缓冲配额**（`streamNonTerminalBuffers`，缺省 32 条流；`0` = 不留）：超出即从最旧、**没有订阅者**的流开始回收**回放历史** —— 表项与序号都留着，连上来的读者先收一帧 `stream.truncated` 再转实时（**不会**变成 `stream.unavailable`，那是对别的进程说的话）；正在被订阅的流不受配额约束（不抽走正在读的数据）。**跨进程**（队列消费者在别的进程）时没有实时流：发一帧 `stream.unavailable` 后**立即收口** —— 任务已终态则补 `task.end`（随后关连接）；**非终态**则补一帧 `stream.closed`（流级收尾，不是伪造终态）并关连接，客户端此后应转去轮询 `GET /tasks/:id`。要跨进程实时请用 `onTraceEvent` 把事件转发到宿主自己的总线（Redis Streams / Kafka） |
 | 异步任务的**排队段**边界（内存） | `concurrency` 管「同时在跑几个」，**不管**「跑不上、排在后面」那一段 —— 缺省**排队段无上限**：`submit` 总是收单、`POST /tasks` 总是 202，灌多少就在内存里排多少（每条 = 一条记录 + 一棵悬挂的 `#execute` promise + 一个槽位等待者）。要背压就配 `AsyncRunner({ maxQueued })`：超限 `submit` 抛 `TaskQueueFullError`、HTTP 回 **503 + `Retry-After`**（**只在 `submit` 判** —— 恢复路径推进的是已受理任务，拦下来等于把它搁死在 store 里；幂等键命中的重复提交也不吃 503）。`runner.queued` 是实时读数（与闸同一判据）。⚠️ 进程内拒单**不等于**集群级背压：多副本各算各的，要全局就得上队列 |
 | `traceLimits` 与 `maxEventChars` 各管一头 | `maxEventChars` 管**单个事件正文多长**（既有），`traceLimits.maxEvents` 管**整条 trace 记多少条记录事件**（本版）。两者正交、都「不设 = 不限」；超限即**停止记账**，并在 run 根留**两笔** `trace.truncated`：**起点标记** `{limit}`（断点在这里）+ **收尾摘要** `{droppedEvents, limit}`（丢了多少）—— 两笔**同时**进交付的 trace 与 `onTraceEvent` 增量流（⇒ 按 `seq` 折回仍逐字等于收尾那份；两笔簿记**不占** `maxEvents` 配额）。⚠️ 实测 `maxEventChars: false` + 大出参会让 trace 放大 **13.7×**（`npm run bench:trace` 可复现）—— 先收长度再谈采样，收益顺序比反过来大 |
-| 回给模型的 `tool_result` **不截断、也没有大小闸** | `maxEventChars` / `traceContent` 管的是**记账侧**（trace 记多长、记不记正文）—— 回给模型的工具结果**永远完整**，框架里没有「单条工具结果超过多大就裁」的那条缝。一次 `cat` 大文件、一次刷屏回显就能让**下一回合**的输入爆掉上下文窗口，以 api 错误收尾（长跑里尤其容易撞）。要设输出上限请在**工具实现内部**做（按行数 / 字节截断并附「已截断」标记）—— 框架不替你兜 |
+| 工具结果缺省不截断；上限要显式开 | `maxEventChars` / `traceContent` 管**记账侧**；`maxToolResultChars` 管回模型的单条结果，缺省/false = 不截断，给非负整数即截并附 `…(+N)`。它按字符而非 token/业务行数计费；要语义化摘要仍在工具内做 |
 | **采样是导出决策，不是记账决策** | 采样在 `sink` 外做（配方见 `docs/observability.md` 2.3）：被采样掉的 trace 在框架内**仍然完整记账**，只是没发给下游。所以别拿「有采样」当「可以少记账」；也正因如此，出站 `traceparent` 的 flags 恒 `00`（记录/导出决策发生在收尾之后，运行期不可知——不替下游声明） |
 | 菜单漂移只**标记**、不判失败 | 续跑时未决 tool_use 的工具不在当前菜单 ⇒ 三处信号（`menu.drift` 事件 / 父 span attribute / `console.warn`），run **照常收尾**（那些 tool_use 以 `unknown tool` 回给模型）。**射程如实标注**：判据只看**名字** —— 「工具还在、schema 变了」能被 `tools.menuHash` 比出来，但**不会**在续跑时报 `menu.drift`；**只改 `description`** 连签名都不变（有意：润色文案不算漂移）。严格模式（带具名 error 的收尾）与「结果级字段」记在 spec §11 开放项 |
 | `approve` 只收**待决的** id（多一个 → 400 整批拒） | `decisions` 的键必须都在该任务的 `pendingApprovals` 里（调用方从记录的 `pendingApprovals` 读）。多出任何一个 ⇒ **400 + 整批拒 + 记录一字不动**。不校验的代价（已修，2026-09-28 外部深评）：多出来的键会写进 `TaskRecord.approvals`，随每次 `save` 全文重写、且终态也不清 ⇒ 一个**认证调用方**单次请求就能把记录撑大（实证：一次 5000 个无关键 = +419 KB），反复调用可无限叠加 |
@@ -1969,15 +2043,15 @@ const callable = {
 | 审批超时是**惰性**判定 | `approvalTimeoutMs` 不起定时器：`approve` / `poll` / `resumePending` 读到过期挂起任务时才自动全拒并重派 —— 没人读的任务不会自己超时（要定期扫就调 `resumePending()`） |
 | 挂起段与恢复段是两棵 trace | 每段执行一棵独立的树（`traceId == runId`），恢复段经根 span 的 `links` 挂到上一段；指标按段计（挂起段算一次 ok 的 run —— 「等人」不算失败，区分看 `stop_reason` attribute） |
 | 审批是 at-least-once | 崩溃发生在「批准后、恢复执行中」时，副作用工具会重执行（与 `resumePending` 续跑同口径）—— 副作用工具自己保证幂等 |
-| 挂起/恢复间预算重新起算 | `maxTotalTokens` / `maxCostUsd` 在恢复段从 0 重新计（新树新账，与 `resumePending` 续跑同口径） |
-| 恢复段的会话回写是进程内快照 | 带 `sessionId` 的任务挂起时，「本轮用户输入」快照只存进程内存（恢复段由 AsyncRunner 自己补写「用户输入 + 最终回复」，不再经 run 层重复拼历史）—— 进程崩在「挂起 → 重启 → approve」之间会**丢这一次会话回写**（会话少一轮，但绝不写进坏历史；审批决定本身已落库） |
-| 嵌套能力内的审批不支持挂起 | @SubAgent / @Skill 子循环里的 `approval: 'required'` 工具无法把整个 run 挂起 —— 子循环挂起会以 `is_error` 交回主 agent（要审批的能力请放主菜单） |
+| 恢复预算按任务累计，但崩溃未落账段不可追回 | 每个已收尾段折进 `TaskRecord.usageTotal`；恢复段经 `usageOffset` 参与 maxTotalTokens/maxCostUsd，trace 仍每段一棵。进程崩在「模型已花、结果未落库」窗口时那笔无从恢复，不能把它当全局精确账单 |
+| 恢复段的会话输入随任务落库 | 首个挂起段把本轮输入写进 `TaskRecord.sessionInput`，恢复成功后由 AsyncRunner 补写并终态清除；挂起期间重启不再丢这一轮。旧版本留下的挂起记录没有该字段，仍只能跳过补写 |
+| 嵌套能力内的审批不支持挂起 | @SubAgent / @Skill 子循环里的 `approval: 'required'` 工具无法把整个 run 挂起 —— 子循环挂起会以 `is_error` 交回主 agent（要审批的能力请放主菜单）。要「代码定顺序 + 人批」两样都要：把 `runCapabilityLoop` 放进一个 `@Tool({ approval: 'required' })` —— 审批落在**外层工具调用**上，于是照样能挂起等人批 |
 | 同步 `/run` 撞上审批没人可批 | 同步 RPC 会带着 `stopReason: 'suspended'` 收尾返回 —— 但响应体（`toHttpBody`）**不含** `suspendedMessages`，也没有任务记录可审批（待决清单只能去 trace 的 `approval.requested` 事件里看）。**要审批请走 `POST /tasks` 异步宿主** |
 | Scheduler 调度表不落库 | `every` / `at` 的调度本身只在内存：已 submit 的任务记录能经 `resumePending` 续跑，但「未来某刻再触发」的调度在重启后不存在（远期单发由宿主自己的 cron 驱动）。另：`drain()` 不停 Scheduler —— 停机窗口内到点的 tick 会打一条触发失败日志（无害但吵），介意就 `scheduler.stop()` 先行 |
 | file store 的撕裂写只在启动时自愈 | 写入中途失败（磁盘满等）留下的残行由 `healTail` 在**构造期**修复；同进程内继续 append 会把新记录粘在残行尾部、下次启动时一起丢弃 —— 磁盘满告警后先恢复写入能力再继续依赖它 |
 | 终态落库失败 ⇒ 重启会重跑 | AsyncRunner 终态 `save` 失败**不遮罩主流程**（「不击穿业务」的代价）：store 抖动时任务可能永远停在 `running`，重启后 `resumePending` 会重跑一个**实际已成功**（副作用已发生）的任务 —— 所以副作用工具必须自身幂等。**但失败本身不再静默**：`new AsyncRunner(app, { onPersistError })` 会收到 `{ record, error, phase }`（`phase: 'initial' \| 'outcome'`，后者就是这条）。⚠️ 框架**修不了**它（写不进去就是写不进去）—— 出口的职责是让你能对账、让「记录无声丢失」不再是默认行为（与 `createOtlpExporter({ onExportError })` 同因同形） |
 | 缺省**不裁剪**上下文（长跑每回合重发全量历史 ⇒ 成本随回合数平方增长） | `contextPolicy` 不注入就一个回合都不裁：每回合把**整段历史**重发给模型，于是回合数翻倍、总输入约翻两番。框架给了缝与一份参考实现（`createBudgetPolicy`），但**不替你决定** —— 裁剪有损（截在哪、留什么会影响答案），是宿主的策略。长任务（几十回合以上）请在 `createApp` 里显式注入 `contextPolicy` |
-| `contextPolicy` 不进子循环 | 应用级 `contextPolicy` / `onText` 只对主循环生效：@SubAgent / @Skill 的子运行不做上下文裁剪（长跑子 agent 撞上下文上限会以 api 错误收尾）。预算护栏（`maxTotalTokens` / `maxCostUsd`）正常透传 |
+| `contextPolicy` 不进子循环 | 应用级 `contextPolicy` / `onText` 只对主循环生效：@SubAgent / @Skill 的子运行不做上下文裁剪（长跑子 agent 撞上下文上限会以 api 错误收尾）。预算护栏（`maxTotalTokens` / `maxCostUsd`）正常透传。要裁剪就显式给：`runCapabilityLoop(ctx, { contextPolicy })`（不继承应用级 —— 子循环的策略是调用点的决策） |
 | 记忆没有删除语义 | `MemoryStore` 只有 load/save：run 内 `ctx.delete` 掉的键回写时不会从 store 移除（下一轮水合会复活）。要真删请直接操作 store 实现 |
 | 同 keys 的并发回写不合并 | CAS（`loadWithRev` + `saveIfRev`）只做到「冲突时**不写 + 出声**」：框架**不合并、不重试**（合并语义是 store 与宿主的决定，配方见 §6.5）。只有 `load` / `save` 的 store 连冲突都**看不见** —— 版本号是唯一依据，没有它就检测不了覆盖；`InMemoryMemoryStore` 的版本粒度是**整店一个计数**（宁可多报冲突，不漏报真实覆盖） |
 | 内容护栏不给实现 | 同「配额」：只给缝（入参包 `app.run` / 工具前 `middleware` / 出参包返回值或 `sinks`），策略（正则 / 分类器 / 外部 API）是你的 |

package/dist/core/limits.d.ts

@@ -166,6 +166,14 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 截到零长度；false = 不截断';
     readonly badValue: 'none';
     readonly note: '两个「关掉」的写法语义不同：`false` 才是「不截断」（调试期看全文），`0` 是把正文截成空串。⚠️ 靠 `!= null` 判定透传（真值判定会吃掉 `false`）。';
+}, {
+    readonly knob: 'maxToolResultChars';
+    readonly where: 'engine/tool-events.ts（toolResultBlock / validateMaxToolResultChars）';
+    readonly unit: 'chars';
+    readonly zero: 'disabled';
+    readonly zeroClause: '0 = 截到零长度；false = 不截断';
+    readonly badValue: 'throws';
+    readonly note: '与 maxEventChars 同读法但不同保护面：这个裁回模型的 tool_result，那个裁 trace。NaN/负数/小数在第一次模型调用前拒，否则上限可能静默失效或行为不定。';
 }, {
     readonly knob: 'runAgent.maxIterations';
     readonly where: 'engine/loop.ts';

package/dist/core/limits.js

@@ -132,6 +132,15 @@ export const LIMIT_SEMANTICS = [
         badValue: 'none',
         note: '两个「关掉」的写法语义不同：`false` 才是「不截断」（调试期看全文），`0` 是把正文截成空串。⚠️ 靠 `!= null` 判定透传（真值判定会吃掉 `false`）。',
     },
+    {
+        knob: 'maxToolResultChars',
+        where: 'engine/tool-events.ts（toolResultBlock / validateMaxToolResultChars）',
+        unit: 'chars',
+        zero: 'disabled',
+        zeroClause: '0 = 截到零长度；false = 不截断',
+        badValue: 'throws',
+        note: '与 maxEventChars 同读法但不同保护面：这个裁回模型的 tool_result，那个裁 trace。NaN/负数/小数在第一次模型调用前拒，否则上限可能静默失效或行为不定。',
+    },
     {
         knob: 'runAgent.maxIterations',
         where: 'engine/loop.ts',

package/dist/core/limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"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"}

package/dist/core/tool.d.ts

@@ -169,6 +169,8 @@ export interface ToolRunContext {
      * 不设（undefined）= 子循环用各自缺省（不是"不截断"）。
      */
     maxEventChars?: number | false;
+    /** 单条工具结果回模型的字符上限；嵌套能力必须原样转发，缺省 / false = 不截断 */
+    maxToolResultChars?: number | false;
     /**
      * 本 run 是否记录 assistant 文本进 llm.turn span（`RunAgentOptions.traceContent`，R8-P3a）。
      * 嵌套能力（@SubAgent / @Skill）拉起自己的 llm 循环时必须原样传下去 —— 否则同一棵
@@ -183,6 +185,8 @@ export interface ToolRunContext {
      * **整条 run（含各级子 agent）** 的口径，子循环不拿到它就等于护栏在子循环期间离线
      * （最坏可超一整个子 run 的用量）。各级循环共享同一 recorder，按同一份累计账单判断。
      */
+    /** 本任务此前 run 段的账单；嵌套循环的预算判定也要把它算进去 */
+    usageOffset?: Usage;
     maxTotalTokens?: number;
     /** 成本硬管控（C1）透传：累计成本（美元）上限；同 maxTotalTokens 的透传语义 */
     maxCostUsd?: number;
@@ -240,11 +244,25 @@ export interface ApprovalDecision {
      */
     requestedAt?: number;
 }
+export interface CapabilityMetadata {
+    /** 责任团队 / CODEOWNERS 对应的稳定标识 */
+    owner?: string;
+    /** 能力契约版本（prompt 的旧 version 字段可与它二选一） */
+    version?: string;
+    /** 主要风险面：读业务数据 / 写业务状态 / 调外部系统 */
+    risk?: 'read' | 'write' | 'external';
+    /** 副作用是否可安全重放；非幂等能力必须有业务侧幂等/对账 */
+    sideEffect?: 'none' | 'idempotent' | 'non-idempotent';
+}
 export interface AgentTool<I = unknown, O = unknown> {
     /** 模型可见的唯一名（建议 snake_case） */
     name: string;
     description: string;
     inputSchema: JsonSchema;
+    /** 能力类别；裸工具缺省按 tool，装饰器/MCP 装配时显式填入 */
+    capability?: import('./trace.js').CapabilityType;
+    /** 团队协作与变更审查元数据；不改变运行行为 */
+    metadata?: CapabilityMetadata;
     /** 开启严格参数校验（schema 需 additionalProperties:false + required） */
     strict?: boolean;
     /**

package/dist/core/trace.d.ts

@@ -174,6 +174,8 @@ export interface Trace {
     status: SpanStatus;
     totalUsage: Usage;
 }
+/** 跨 run 段累加账单；任一段有成本读数才保留 costEstimate，口径与 TraceRecorder.usage 一致。 */
+export declare function addUsage(before: Usage | undefined, current: Usage): Usage;
 /**
  * 质量评分（R7 质量闭环）：LLM-judge / 人工标注 / eval 结论挂到 trace 上，
  * 让「这条 run 好不好」与「这条 run 发生了什么」同处一份数据。

package/dist/core/trace.js

@@ -96,6 +96,20 @@ export function wireSpanId(id) {
 export function formatTraceparent(traceId, spanId) {
     return `00-${wireTraceId(traceId)}-${wireSpanId(spanId)}-00`;
 }
+/** 跨 run 段累加账单；任一段有成本读数才保留 costEstimate，口径与 TraceRecorder.usage 一致。 */
+export function addUsage(before, current) {
+    const out = {
+        inputTokens: (before?.inputTokens ?? 0) + current.inputTokens,
+        outputTokens: (before?.outputTokens ?? 0) + current.outputTokens,
+        cacheReadTokens: (before?.cacheReadTokens ?? 0) + current.cacheReadTokens,
+        cacheCreationTokens: (before?.cacheCreationTokens ?? 0) + current.cacheCreationTokens,
+    };
+    if (before?.costEstimate != null || current.costEstimate != null) {
+        out.costEstimate =
+            Math.round(((before?.costEstimate ?? 0) + (current.costEstimate ?? 0)) * 1e6) / 1e6;
+    }
+    return out;
+}
 /**
  * 把评分挂到 trace 根 span（一条 `score` 事件，body 即 Score）。
  * trace 找不到根 span 时静默忽略（观测不击穿业务）；多次调用即多条事件（不同维度各记各的）。

package/dist/core/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}