@migor/agentia 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -5,6 +5,143 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.8.2] - 2026-09-21
+
+### 变更
+
+> 本版主题（窗口 `0.8.1 → 0.8.2`，含 #112）：**外部双模型复核逐条复现收口** —— 9 条真缺陷
+> （7 条复核成立 + 改的过程中照出的 2 条），全部落在「不报错地不干活」这一类：静默丢观测数据、
+> 静默无限重试、无声永久挂起、生成出来的工程一跑就崩。
+> **框架 API 无破坏性变更**：只新增一个选项（`createOtlpExporter({ onExportError })`），
+> 既有签名与行为在「你没传坏值 / 没按 200 当全部成功」的前提下逐字不变。
+> **一处需要你确认的收紧**：`maxRetries` 的坏值改在**构造期抛错**（见「修复」与「迁移」）。
+
+### 修复（观测出口 —— 三条都属于「看板少数据而框架说一切正常」）
+
+- **OTLP 导出的 `status.code` 从名字符串改成整数**（`'STATUS_CODE_OK'` / `'STATUS_CODE_ERROR'`
+  → `1` / `2`）。OTLP 规范对此是**明文 MUST**，而且专门点出它与 protobuf 的通用 JSON 映射不同：
+
+  > *Values of enum fields MUST be encoded as integer values.*
+  > *Unlike the standard Protobuf JSON Mapping, which allows values of enum fields to be encoded as
+  > either integer values or as enum name strings, only integer enum values are allowed in OTLP JSON
+  > Protobuf Encoding; the enum name strings MUST NOT be used.*
+  > —— [OTLP 规范 · JSON Protobuf Encoding](https://opentelemetry.io/docs/specs/otlp/)
+
+  （同期 `kind` 一直是整数 1，只有 `status` 漏了。）**后果取决于你那侧 collector 的宽容度**：
+  照规范校验的实现会判非法并**整批拒收**（也就说这些 span 在采集端**根本没落库**，而框架侧只看得到
+  「HTTP 200」）；按通用 protobuf JSON 映射的宽容实现（enum 名与整数都收）能落库。
+  受影响范围：**`v0.2.2` → `v0.8.1`**（`createOtlpExporter` 自 `v0.2.2` 起就带这个错）。
+  动作：升级即可，不需要改代码。**但请顺手去采集端确认一眼**这期间（用严格 collector 的话）
+  的 trace 是否为空 —— 你的实现属于哪一档，看那里比看本文档准；丢掉的**历史数据补不回来**。
+- **HTTP 200 不再等于「全部接收」**：collector 可以回 `200 + partialSuccess` 表示「收了一部分」。
+  此前 `res.ok` 为真就算成功 ⇒ 少了一半数据也没人知道。现在「**真拒收**（键在场且值 > 0）
+  **或**非空 `errorMessage`」判为导出失败；`{}` 与 `rejectedSpans: 0` 仍算全部接收
+  （有 collector 恒发这种形状，不能反着误报）。
+- **新增 `createOtlpExporter({ onExportError })`**（与 `metricsSink` 的同名选项对称）：
+  不给，维持既有行为（抛出 → `flushSinks` 吞掉，观测失败不击穿业务）；给了，**所有**导出失败
+  （非 2xx / 超时 / **HTTP 200 但部分接收**）都交给它。存在的理由：`TraceSink` 的失败缺省是
+  **静默**的，「导出其实少了一半数据」这类消息得有人能收到 —— 否则它和「一切正常」在监控上
+  看不出区别。
+- **`metricsSink` 的 `reset()` 语义明确为「开启新窗口」**：计数清零**且**数据点起点前移。
+  此前 `reset()` 只清计数、而数据点的 `startTimeUnixNano` 取自 sink **创建时刻的常量** ⇒
+  同一 `startTime` 下 counter 从 2 退到 1（CUMULATIVE 指标的契约是「同一区间单调不减」，
+  后端会算出负增量或直接丢样本）。同一毫秒内连按两次 `reset()` 时起点也**严格**前进。
+
+### 修复（其余）
+
+- **`maxRetries` 的坏值改在构造期抛 `TypeError`**（`createAnthropicClient` /
+  `createOpenAIClient`，两条适配器共用一份判定）。重试判定是 `attempt >= maxRetries`，于是
+  四类坏值此前被**静默接受**、后果各不相同：`NaN` ⇒ 比较恒假 ⇒ **无限重试**；`Infinity` ⇒
+  永不达到 ⇒ **无限重试**；`-1` ⇒ 静默变成「不重试」；`1.5` ⇒ 实际只允许 1 次（读数上看不出来）。
+  使用者以为自己设了上限，实际没有 —— 429 场景下每多一次重试都是真金白银。
+  **`0` 与不传仍然合法**（`0` = 不重试，是有意义的值；缺省 2）；坏的是「非整数 / 负数 / 非有限」。
+- **已中止的 MCP 调用不再发请求、不再永久挂起**：此前的写法是「把 pending 条目删掉、然后照样
+  `write`」⇒ ① 副作用请求**仍然送达** server（取消在传输层是无效的）；② 返回的 Promise
+  **永远不 settle**（条目已删，没人能 resolve/reject）⇒ 调用方**永久挂起**
+  （引擎侧靠 `toolTimeoutMs` 兜底才没炸）。现在判据在 `write()` **之前**，以 `AbortError` 收场
+  （取消不是超时，记账仍归 `aborted`）。发送**之后**才中止的，请求已在路上、取消不了 ——
+  那是「不等了」，与 `toolTimeoutMs` 同口径。
+- **异步 store 下同键并发提交不再重复执行**：`submit` 是**同步门面**、无法 await 异步 store 的
+  `byIdempotency`，而 `#executeInner` 只采纳已 `succeeded` 的既有记录 ⇒ 「同时提交两个相同
+  `idempotencyKey`」在异步 store（Redis / SQLite）下**两次都执行**（文档承诺的同键去重实际只对
+  同步 store 成立）。现在补一张**进程内认领表**：认领在同步前段完成（两次连续 `submit` 之间
+  没有窗口），且**只在终态释放**（挂起还在等人，放了会让同键另起一个任务）。
+  **边界（同时写进 `usage-guide` §7）**：修的是「同进程内并发提交」这一档；**跨进程并发**与
+  **终态之后重提同键**仍是 at-least-once（store 的 idem 索引 last-wins）。
+- **`@migor/cli`：模板漏写 `scripts/clean.mjs`**。本版首次给脚手架模板加「构建前先清 dist」，
+  并在发布前发现 `create.ts` 忘了把该脚本写出去 —— 生成的新工程 `npm run build` **第一步就
+  `MODULE_NOT_FOUND`**。**已发布版本（≤0.8.1）的模板不含这一步，你此前生成的工程不受影响**，
+  也不需要改；本版发布的是修好的形态。仓库自身与模板的构建现在都先清 dist（`tsc` 不会删除
+  它不再产出的文件 —— 目录重构后旧产物会原样进包），并新增「模板目录 ↔ 源码双向引用」守卫
+  （模板文件必须被引用、每个 accessor 必须有调用方）与 e2e 的**真删能力再重建**对照。
+
+### 仓库自身（不面向使用者）
+
+- e2e-cli 的构建步骤从「测试复刻 `clean → tsc → copy-assets` 三步」改成**字面跑产物自己的
+  `npm run typecheck` / `npm run build`** —— 这条改法当场照出上面那条真缺陷（测试复刻命令的
+  版本照不出来）。同时删掉一条会在合法重构时误报的字面量断言。
+- `docs/guards.md` §1 增补五条守卫（OTLP enum + partialSuccess、CUMULATIVE 窗口起点、模板重建
+  清 dist、幂等键进程内认领、模板 ↔ 源码双向引用）；`docs/spec.md` §10 ⑤ 记逐条定性、
+  反向验证与「报告自称已证伪」的抽查范围。
+- `tests/docs/usage-guide.test.ts` 把 `OtlpExporterOptions` 登记进成员表校验 —— 新增选项自此
+  被文档守卫钉住（注入假成员验证过会红）。
+
+**迁移**：无（框架 API 无破坏性变更，既有代码不需要任何改动）。唯一需要动作的是 `maxRetries`：
+如果你此前给它传过 `NaN` / `±Infinity` / 负数 / 小数，升级后**构造期会抛 `TypeError`** ——
+这是有意的（它此前是静默失效），改成非负整数即可；传 `0` 或不传的代码不受影响。
+
+## [0.8.1] - 2026-09-21
+
+### 变更
+
+> 本版主题（窗口 `0.8.0 → 0.8.1`，含 #107–#110）：**出站链路传播** —— spec §9.2 那条
+> 「出站传播仍开放」的项收口。**无破坏性变更**：只新增一个公开函数；既有 API、trace 形状、
+> OTLP 导出值与 id 生成本身全部逐字不变（id 投影只是从 `integrations/otlp.ts` 的私有函数
+> **上移到** `core/trace.ts` 成为单一真源，取值一字未改）。
+
+### 新增
+
+- **`currentTraceparent(): string | undefined`**（出站链路传播）：给出**当前调用期** span 的
+  W3C `traceparent`（`00-<32位trace>-<16位span>-00`），自己带在出站请求上（`fetch` 头 / gRPC
+  metadata）。下游若也是 agentia（或任何认 `traceparent` 的服务），就能把「谁触发了这次调用」
+  关联到**具体 span**，而不是只到 run 粒度：
+
+  ```ts
+  import { currentTraceparent } from '@migor/agentia';
+
+  const tp = currentTraceparent();
+  await fetch(url, { headers: { ...(tp ? { traceparent: tp } : {}) } });
+  ```
+
+  粒度：普通工具与 `@Prompt` **不建 span**，取到的是发起它们的那次 `llm.turn`；`@Skill` /
+  `@SubAgent` 方法体内取到的是自己的 `capability` span（内层覆盖外层）。入站那一半
+  （`traceparent` 头 → run 根 `links`）已随 0.6.2 落地，本版把出站补上，跨服务关联从此双向。
+
+### 已知边界（同时写进 `usage-guide` §7）
+
+- **只给读取器，不替你做注入** —— 框架不创建出站请求，注入那一行是宿主的（与「webhook 用
+  sink + 你自己的 `fetch`」同一条既有决策）。
+- `run` 根 span 由 `runAgent` 打开 ⇒ 更早的 `contextInit` / 记忆水合取到 `undefined` —— 那时
+  确实还没有 span 可指，不编造。
+- flags 位恒 `00`：本框架不采样（每次 run 全量记账），不替下游声明「已采样」。
+- id 宽度：内部 id 是 UUID，出站与 OTLP 共用**同一份**投影（trace 去横线 32-hex、span 截
+  16-hex）⇒ 下游收到的 span id 与 collector 里那个**是同一个数**（各写一份会让同一次调用在
+  两个系统里出现两个 span id）。
+
+### 仓库自身（不面向使用者）
+
+- 第七 / 第八轮复审散件沉淀进 `docs/guards.md` 附录 B，并立「多 agent 同仓作业」三条纪律
+  （结论钉 commit / 门禁跑隔离导出树 / 不碰别人的未提交改动）。
+- 出处链更正：spec §10 的「132 条直接用例」→ **127**（逐文件计数，独立复核不可复现 132），
+  全仓口径改引「+140 条（`tests/` 增量）」；覆盖率棘轮分支 85→88 / 函数 92→95。
+- 新增两条守卫并入册：id 投影**单源**（OTLP 与出站必须同一个数）、出站**调用期作用域**
+  （并行不串 / 内层不外泄），两条都做过承重性反向验证。
+- 发布面清单的 lock 项改为**按包名锚定**：裸 `"version"` 计数会被**恰好同版本号的第三方
+  依赖**撞网（本次真发生：`@grpc/proto-loader` 恰好 @0.8.1 ⇒ 闸门报「4 处应为 0.8.1，实际
+  命中 5 处」，读起来像漏项）。夹具同步加了同版本诱饵，断言它既不被替换、也不进网。
+
+**迁移**：无。既有代码不需要任何改动；要开始用出站传播，就在出站请求上加一行 `traceparent`。
+
 ## [0.8.0] - 2026-09-21
 
 ### 变更
@@ -727,7 +864,9 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.8.2...HEAD
+[0.8.2]: https://github.com/retrychx/agentia/releases/tag/v0.8.2
+[0.8.1]: https://github.com/retrychx/agentia/releases/tag/v0.8.1
 [0.8.0]: https://github.com/retrychx/agentia/releases/tag/v0.8.0
 [0.7.2]: https://github.com/retrychx/agentia/releases/tag/v0.7.2
 [0.7.1]: https://github.com/retrychx/agentia/releases/tag/v0.7.1

package/README.md

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

package/dist/AGENTS.md

@@ -461,7 +461,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` 未失败则去重，直接返回既有记录 |
+| `POST /tasks` | `{ input, idempotencyKey?, options? }` —— `input` 同 `RunInput`；`options` 是 `RunInvocationOptions` | 202 `TaskRecord`（`status: 'queued'`）；同 `idempotencyKey` 未失败则去重、直接返回既有记录（**同步 store** 当场判定；**异步 store** 下只保证**同进程内并发提交**不重复执行，跨进程与终态后重提仍是 at-least-once —— 见 §7「同键去重的能力边界」） |
 | `GET /tasks/:id` | — | 200 `TaskRecord`；不存在 → 404。**停机中仍可轮询**（否则拿不到在飞任务的结果） |
 | `POST /tasks/:id/approve` | `{ decisions: { <tool_use_id>: { approved, reason? } }, decidedBy? }` | 200 `TaskRecord`（HITL 审批：批准/拒绝挂起任务，见 §6.6「人工审批」）；任务不存在 → 404；不在 `awaiting_approval` 状态 → 409；body 非法 → 400。**停机中仍可审批**（与 GET 轮询同理由） |
 | `GET /healthz` | — | 200 `HealthResponse`；**不鉴权**，停机中也回 200 |
@@ -538,7 +538,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 }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与底层 client 的**内置重试**叠加 —— **两条内置适配器口径一致**（`createAnthropicClient` / `createOpenAIClient` 都有 `maxRetries`，缺省 2，重试同一状态码集合 408/409/429/5xx）—— 建议二选一调（这里 `maxAttempts: 1`，或 `<适配器>({ maxRetries: 0 })`）。
+- **重试**：缺省自动重试可重试失败（429 / 5xx / 连接失败），指数退避 + 抖动。`retry: false` 关闭，或 `retry: { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与底层 client 的**内置重试**叠加 —— **两条内置适配器口径一致**（`createAnthropicClient` / `createOpenAIClient` 都有 `maxRetries`，缺省 2，重试同一状态码集合 408/409/429/5xx）—— 建议二选一调（这里 `maxAttempts: 1`，或 `<适配器>({ maxRetries: 0 })`）。`maxRetries` 在**构造期**校验：只收非负安全整数（`0` = 不重试），NaN / ±Infinity / 负数 / 小数一律抛 `TypeError` —— 判定是 `attempt >= maxRetries`，NaN 恒假、Infinity 永不达到，两者都等于**无限重试**（且静默）。
 - **流式**：`POST /run` 带 `Accept: text/event-stream` → SSE 逐帧下发（`text.delta` / `run.end` / `error`）；不带该头仍回一元 JSON。
 - **工具超时 / 并发闸门**：`toolTimeoutMs` 超时**不杀 run**（该条 tool_result 记 `is_error`，模型可换路）；`maxToolConcurrency` 给同回合的并行工具设上限（默认全并行）。⚠️ 超时 = **放弃等待**：`AgentTool.run` 没有 signal 参数，**副作用可能已发生**；但引擎放弃等待时会 abort `ToolRunContext.abandoned` —— 想真停的工具监听它自行收尾（框架自带的 @SubAgent / @Skill 已这么做：超时即中止子循环，capability span 以 error 收尾）。**超时判定只有一个裁判**：`toolTimeoutMs` 是唯一判据 —— 工具自带的超时（如 MCP 桥的 `timeoutMs`）在设了本项时**不参与**判定；反过来说，工具自判的超时（抛 `code='timeout'` 的错误）与引擎判的记**同一类账**（`errorKind='timeout'`），并同样回 `is_error`。
 
@@ -628,12 +628,34 @@ trace 出去之后能干什么：指标、调用树面板、调优报告、生
 | `registerDefaultTraceSink` | 注册全局默认 sink（构造期快照合并） |
 | `TraceRecorder` | 内存 recorder（一次 run 一个）；`addLink(spanId, { traceId, spanId? })` 记一条跨 trace 链路（见 §6「跨进程关联」） |
 | `parseTraceparent` | 解析 W3C `traceparent` 头 → `{ traceId, spanId? }`；**非法 / 缺头一律返回 `undefined`**（不抛、不打 400）—— 结果直接交给 `traceContext` 选项，见 §6「跨进程关联」 |
-| `createOtlpExporter` | OTLP/JSON 导出，零依赖；选项 `OtlpExporterOptions`：`endpoint` / `headers` / `serviceName` / `timeoutMs`（单次导出超时，缺省 10000，非正数 = 不限 —— 裸 fetch 无超时，collector 半开连接会让 run 收尾永久挂起；超时按导出失败处理，不击穿 run） |
+| `createOtlpExporter` | OTLP/JSON 导出，零依赖；选项见下面「`OtlpExporterOptions`」表 |
 | `metricsSink` | 指标累加器（Prometheus 文本 / OTLP metrics），满足 `TraceSink` 即接入 —— 见 §6「指标」 |
 | `buildRunReport` | 从一条 trace 生成**调优报告**（能力/模型的耗时、token、成本、错误率排行）—— 见 §6「调优报告」 |
 | `Score` | 质量评分：`{ name; value; source?; comment? }` —— LLM-judge / 人工标注 / eval 结论挂到 trace 上；约定 `value` 为 0–1（布尔结论用 0/1），`source` 记评分来源（eval 名 / `'human'` / judge 模型 id） |
 | `attachScore` | `attachScore(trace, score)`：把评分挂到 run 根 span（一条 `score` 事件，body 即 `Score`）。评分通常来自 run **之外**（跑完才评），所以走事件而非 span 字段；trace 找不到根 span 时静默忽略（观测不击穿业务） |
 
+#### `OtlpExporterOptions`（`createOtlpExporter` 的选项）
+
+| 字段 | 说明 |
+|---|---|
+| `endpoint` | collector 基地址（如 `http://localhost:4318`）；导出即 POST `${endpoint}/v1/traces` |
+| `headers` | 追加的请求头（鉴权 / 租户标） |
+| `serviceName` | OTLP resource 的 `service.name`，缺省 `agentia` |
+| `timeoutMs` | 单次导出请求超时（毫秒，缺省 10000，非正数 = 不限）——裸 `fetch` 没有超时，collector 半开连接会让 run 收尾**永久挂起**；超时按导出失败处理 |
+| `onExportError` | 导出失败回调：给了它，**所有**失败（非 2xx / 超时 / **HTTP 200 但 collector 报部分接收**）都交给它、不再向 `TraceSink` 调用方抛；不给则维持既有行为（抛出，由 `flushSinks` 吞掉 —— 观测失败不击穿业务）。存在理由：`TraceSink` 的失败缺省是**静默**的，「导出其实少了一半数据」这类消息得有人能收到 |
+
+导出器的两条线缆口径（都有守卫钉着，别按直觉改）：
+
+- **enum 一律整数编码**：`status.code` = `1`（ok）/ `2`（error）、`kind` = `1`（INTERNAL）。
+  OTLP 规范是**明文 MUST**，且专门区别于 protobuf 的通用 JSON 映射：*「Values of enum fields
+  MUST be encoded as integer values… only integer enum values are allowed in OTLP JSON Protobuf
+  Encoding; the enum name strings MUST NOT be used.」*（曾经发的是 `'STATUS_CODE_OK'` 这种字符串，
+  本地假 collector 只做 `JSON.parse`，所以一直没被发现）。**代价取决于 collector 的宽容度**：
+  照规范校验的会整批拒收（数据没落库、框架只见 HTTP 200），按通用 protobuf JSON 映射的能收下。
+- **HTTP 200 不等于全部接收**：collector 可以回 `200 + partialSuccess`（部分接收 / 拒收若干）。
+  导出器把「**真拒收**（键在场且值 > 0）**或**非空 `errorMessage`」判为失败；`{}` 与
+  `rejectedSpans: 0` 属于「全部接收」的另一种写法（有 collector 恒发），不算失败。
+
 **评分链路**：`attachScore` 写 run 根 `score` 事件 → OTLP 导出时译为 `gen_ai.evaluation.result`
 （`gen_ai.evaluation.name` / `.score.value`，`source` / `comment` 走自有 `agentia.score.*` 键）→
 `metricsSink` 聚合成 `agentia_score` 指标族（见 §6「指标」）。eval / 在线评估怎么用见 §6「evals」与「在线评估采样」。
@@ -678,8 +700,34 @@ runner.submit(msg.value, {
 换宿主这条缝不变：gRPC 宿主把 metadata 的 `traceparent` 翻进 `options.traceContext`，
 见 §6.2「gRPC 宿主」。
 
-> **只做入站**：框架**不生成**出站 `traceparent`（运行中没有「当前 span」这个概念，硬造一个会是假的
-> spanId，比不做更糟）。要从 run 往外传，用结果里的 `runId`（== `traceId`）拼你自己的头，见 §7 已知边界。
+**出站（反过来：你调别人）**：在 run 内用 `currentTraceparent()` 取当前 span 的 W3C 头，
+自己带在出站请求上 —— 下游若也是 agentia（或任何认 `traceparent` 的服务），接到的就是一条指向
+**具体 span**（回合 / 能力调用）的 link，而不是只到 run 粒度：
+
+```ts
+import { currentTraceparent } from '@migor/agentia';
+
+@Tool({ description: '把工单交给订单服务' })
+async placeOrder(input: { sku: string }) {
+  const tp = currentTraceparent();          // 不在 run 内 → undefined（那时不该编一个）
+  const res = await fetch(orderSvc, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...(tp ? { traceparent: tp } : {}) },
+    body: JSON.stringify(input),
+  });
+  return res.json();
+}
+```
+
+- **粒度**：普通工具与 `@Prompt` **不建 span**，它们的「当前 span」就是发起它们的那次 `llm.turn`；
+  `@Skill` / `@SubAgent` 的方法体内则是它自己的 `capability` span。内层覆盖外层。
+- **不自动注入**：框架不创建出站请求，注入那一行是你自己的（同上 `fetch`；gRPC 宿主塞进 metadata）。
+- 与入站同一个格式、同一份 id 投影：`currentTraceparent()` 的输出喂回 `parseTraceparent()` 逐字还原，
+  下游 OTLP 里看到的 span id 与本地 collector 里的是**同一个数**（见 §7 已知边界）。
+
+> **出站的边界（如实）**：`run` 根 span 由 `runAgent` 打开，所以比它更早的环节 ——
+> `contextInit`、记忆水合（`MemoryStore.load`）—— `currentTraceparent()` 返回 `undefined`：
+> 那时确实还没有 span 可指。flags 位恒 `00`（本框架**不采样**，不替下游声明「已采样」）。
 
 #### 指标（从 trace 派生）
 
@@ -1206,6 +1254,7 @@ const callable = {
 | `strict` 只是透传 | 框架**不校验** schema 的合规性（是否 `additionalProperties:false` 等） |
 | schema 校验是**子集** | 只覆盖 `type/properties/required/additionalProperties/enum/items`；`format`/`minimum`/`oneOf` 一律放行 |
 | 历史畸形就放弃裁剪 | `trimToolPairs` 遇到非严格交替历史会整体放弃（宁可少裁，也不切出孤立 tool_use 让请求 400） |
+| 同键去重的能力边界 | `idempotencyKey` 的去重分三档：**同步 store** 下 `submit` 当场返回既有记录；**异步 store**（Redis / SQLite 等）下 `submit` 是同步门面、无法 await，去重靠**进程内认领表**，只覆盖「**同进程内并发提交**」（2026-09-21 修复前这里会两次都执行）；**跨进程并发**与**终态之后重提同键**仍是 at-least-once —— store 的 idem 索引是 last-wins（重提即新任务，`redisStore` / `fsStore` / `sqliteStore` 头注释同口径）。要严格一次，请让副作用自身幂等（或在 store 层做唯一约束） |
 | 缺省内存 store 不淘汰 | 长跑宿主请设 `InMemoryTaskStore({ maxRecords })` 或换 `FileTaskStore` / `SqliteTaskStore` |
 | 能力引用两种粒度 | `tools` 写 **provider token** = 整片能力菜单；写 `'<token>/<能力名>'` = 只引单个能力（@Tool/@Skill/@SubAgent/@Prompt 都可点名，装配期校验，名字不存在即抛错并列出可用名单） |
 | 能力名有格式校验 | 装饰器能力名（`name` 或缺省的方法名）必须匹配 `^[A-Za-z0-9_-]{1,64}$`（与 MCP 桥同口径），非法名在 `createApp` **装配期即抛错** —— 含空格/点/中文的名字会让模型 API 400，宁可在启动期拦住 |
@@ -1233,6 +1282,7 @@ const callable = {
 | MCP 只做 tools | `sampling`（server 反向请求模型）/ `resources` / `prompts` 原语不做；出厂连接器同样只做 `tools/list` + `tools/call` |
 | MCP 的协议层错误框架看不见 | `isError: true` 只有连接器能看见 —— 它必须转成抛错，否则模型收到的是一条「成功」的结果（出厂连接器已代你处理） |
 | MCP 超时同样是「不等了」 | 桥的 `timeoutMs` 取消不了 server 侧执行（拿不到取消句柄）；它只是**兜底** —— 引擎设了 `toolTimeoutMs` 时**不参与**判定（一次调用只有一个裁判；**显式 `toolTimeoutMs: 0` 也算设了** —— 那是引擎表态「不限」，桥不会再自作主张判 60s），两条路径**同判定、同账**（`errorKind='timeout'`） |
+| 已中止的 MCP 调用**不发请求** | 信号在**发送前**就已中止 ⇒ 立刻以 `AbortError` 收场，请求不出门（2026-09-21 前是「照样 write、Promise 永不 settle」：副作用真送达、调用方永久挂起）。发送**之后**才中止的，请求已在路上、取消不了 —— 那是「不等了」，与 `toolTimeoutMs` 同口径 |
 | MCP 连接器的超时只管装配期 | 连接器自带的 `timeoutMs` 只作用于**握手 + `tools/list`**（那两步**没有任何别的裁判** —— server 卡住会让 `createApp` 永久挂起）；`callTool` 仍是引擎 / 桥那一个裁判 |
 | MCP 连接的 `close()` 保证子进程已终止 | stdio 先 `SIGTERM`、`MCP_CLOSE_GRACE_MS`（2000 ms）后 `SIGKILL`，然后**等真正的 `'exit'`** —— **返回即代表进程已被回收**（此前到点即返回，会留孤儿进程而调用方无从知晓）；HTTP 尽力 `DELETE` 会话（server 不认也无所谓） |
 | StreamableHTTP 会话过期**自愈** | 带会话 id 收到 `404` = 会话已终止、**该请求未被 server 执行** ⇒ 丢会话 → 重新握手 → 把**这一次**重试一次（**只一次**，不再循环）。自愈本身是静默的 ⇒ 用 `onSessionExpired` 去计数 / 告警，否则它和「静默失效」在监控上看不出区别。`404` **之外**的失败仍按 `classifyError` 分流抛出，不重试 |
@@ -1240,7 +1290,7 @@ const callable = {
 | MCP 工具不能进 DI 容器 | 它没有 provider token，也不能被别的能力的 `tools` 引用（两种引用粒度都要先有 token） |
 | 指标分位是窗口内精确值 | `*_last{quantile=...}` 只反映最近 `windowSize`（缺省 1024）条样本；要跨实例聚合请用直方图（`*_bucket` / `_sum` / `_count`，累积语义） |
 | 指标是**进程内**累加 | 不做分布式聚合与持久化：多实例各算各的（直方图可相加），重启即清零。要长期保留请把 `render()` 抓走或用 `export:'otlp'` 推给采集端 |
-| OTLP metrics 只推当前累计 | 按 `intervalMs` 周期导出**累积值**（CUMULATIVE），不做增量/背压；导出失败按 `onExportError` 处理（缺省吞掉，不重试、不阻塞 run） |
+| OTLP metrics 只推当前累计 | 按 `intervalMs` 周期导出**累积值**（CUMULATIVE），不做增量/背压；导出失败按 `onExportError` 处理（缺省吞掉，不重试、不阻塞 run）。`reset()` 语义是**开启新窗口**：计数清零**且**数据点起点前移（同一 `startTime` 下 counter 只能单调不减，只清零会让后端算出负增量或丢样本） |
 | `GET /metrics` 不鉴权 | 与 `/healthz` 同档（拉取端在集群内网）。要保护请放反代之后，或不传 `metrics` 选项自行在外层挂路由 |
 | 工具没有 token/成本指标 | 工具是**你的代码**、本身不消耗 token，所以只产出调用数/失败数/耗时；token 与成本只对 `skill`/`subagent`（有 `capability` span）与模型维度产出 |
 | `@Prompt` 没有能力指标 | 资产类能力不建 span、无独立耗时，故不出现在能力排行里（这是刻意的：硬凑一个假耗时会误导调优） |
@@ -1250,7 +1300,7 @@ const callable = {
 | `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 时静默忽略，多次调用即多条事件（不同维度各记各的） |
-| 链路关联只做**入站** | `traceContext` / `traceparent` 头只把**上游**接进来（run 根的 `links`）；框架**不生成**出站 `traceparent` —— 运行中没有「当前 span」可导出，硬造会给出假 spanId。要从 run 往外传，用 `result.trace.traceId`（== `runId`）自行拼头。另：link 只落在 run 根（子 span 不散），且**一进程内**不跨进程自动传播 —— 队列场景要自己把 `traceContext` 传下去（HTTP 头带走，或随 `TaskRecord.spec.options` 落库） |
+| 链路关联：入站自动、**出站只给读取器** | `traceContext` / `traceparent` 头把**上游**接进来（run 根的 `links`）；出站方向给 `currentTraceparent()`（当前 span 的 W3C 串，回合 / 能力调用粒度），但框架**不替你做注入** —— 它不创建出站请求，那一行由宿主的 `fetch` / metadata 自己写。两个边界：① `run` 根 span 由 `runAgent` 打开 ⇒ 更早的 `contextInit` / 记忆水合取到 `undefined`（那时确实没有 span）；② flags 恒 `00`（本框架不采样）。id 宽度经**同一份投影**压到 16 位（与 OTLP 导出共用，单一真源）—— 故下游收到的 span id 与 collector 里的是同一个数。另：link 只落在 run 根（子 span 不散），且**一进程内**不跨进程自动传播 —— 队列场景要自己把 `traceContext` 传下去（HTTP 头带走，或随 `TaskRecord.spec.options` 落库） |
 | 配额不是框架子系统 | 只给缝（middleware + TraceSink + BudgetGuard），计数放哪（内存 / Redis / DB）与超限怎么办都是你的策略 |
 | 人工审批两种形态 | 进程内闸门用 `middleware`（`await` 决策再放行）；跨进程耐久审批用 `@Tool({ approval: 'required' })` + `POST /tasks/:id/approve`（挂起/恢复，见 §6.6「人工审批」） |
 | 审批超时是**惰性**判定 | `approvalTimeoutMs` 不起定时器：`approve` / `poll` / `resumePending` 读到过期挂起任务时才自动全拒并重派 —— 没人读的任务不会自己超时（要定期扫就调 `resumePending()`） |

package/dist/core/timeout.d.ts

@@ -25,6 +25,15 @@ export declare class TimeoutError extends Error {
     readonly code: 'timeout';
     constructor(message: string);
 }
+/**
+ * 造一个「已取消」错误：`name === 'AbortError'`（**不是** `TimeoutError` —— 取消不是超时，
+ * `engine/errors.ts` 按 `name` 把它归进 aborted，loop 据此以 `aborted` 收尾）。
+ *
+ * 为什么要导出：这个形状此前**只**活在 `interruptibleSleep` 内部，于是别处需要「以取消收场」
+ * 时只能各写各的（写成 `TimeoutError` 或干脆不 settle）。MCP stdio 桥的「已中止就不该发请求」
+ * 正是这种场景（2026-09-21 外部复核），两处共用一份形状，免得口径漂开。
+ */
+export declare function abortError(message?: string): Error;
 /**
  * 是否超时错误。三条判据（任一条成立即算，**全部是鸭子类型** —— 使用者不必 import 本模块）：
  *

package/dist/core/timeout.js

@@ -28,6 +28,17 @@ export class TimeoutError extends Error {
         this.name = 'TimeoutError';
     }
 }
+/**
+ * 造一个「已取消」错误：`name === 'AbortError'`（**不是** `TimeoutError` —— 取消不是超时，
+ * `engine/errors.ts` 按 `name` 把它归进 aborted，loop 据此以 `aborted` 收尾）。
+ *
+ * 为什么要导出：这个形状此前**只**活在 `interruptibleSleep` 内部，于是别处需要「以取消收场」
+ * 时只能各写各的（写成 `TimeoutError` 或干脆不 settle）。MCP stdio 桥的「已中止就不该发请求」
+ * 正是这种场景（2026-09-21 外部复核），两处共用一份形状，免得口径漂开。
+ */
+export function abortError(message = '已被取消') {
+    return Object.assign(new Error(message), { name: 'AbortError' });
+}
 /**
  * 是否超时错误。三条判据（任一条成立即算，**全部是鸭子类型** —— 使用者不必 import 本模块）：
  *
@@ -150,15 +161,14 @@ export function interruptibleSleep(ms, signal, abortMessage = '已被取消') {
     if (ms <= 0)
         return Promise.resolve();
     return new Promise((resolve, reject) => {
-        const abortError = () => Object.assign(new Error(abortMessage), { name: 'AbortError' });
         // 已中止：立即 reject（此处 timer 尚未创建，绝不能去 clear）
         if (signal?.aborted) {
-            reject(abortError());
+            reject(abortError(abortMessage));
             return;
         }
         function onAbort() {
             clearTimeout(timer);
-            reject(abortError());
+            reject(abortError(abortMessage));
         }
         const timer = setTimeout(() => {
             signal?.removeEventListener('abort', onAbort);

package/dist/core/timeout.js.map

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

package/dist/core/trace.d.ts

@@ -70,6 +70,31 @@ export interface SpanLink {
  * 版本号非 `00` 时按 W3C「兼容未来」规则接受（只认前四段语义）。
  */
 export declare function parseTraceparent(value: string | null | undefined): TraceContext | undefined;
+/**
+ * 内部 id → **线缆形态**（W3C `traceparent` 与 OTLP 通用）。
+ *
+ * 内部 id 一律 UUID（去横线 32-hex），而线上两份契约都要求 trace 16 字节（32-hex）、
+ * span **8 字节（16-hex）** —— 宽度不同，不能共用。原样发出去会被判 `invalid span_id`
+ * （拒收）或按前 16 位截断。故 trace 侧去横线即可、span 侧必须截到 16 位。
+ *
+ * ⚠️ **单一真源**：OTLP 导出（`integrations/otlp.ts`）与出站 `formatTraceparent` 必须
+ * 走**同一份**投影。各写一份的后果不是「风格不统一」，而是**同一次调用在两个系统里
+ * 是两个 span id** —— 跨系统关联最不能出的错。要改这里，先看 `tests/integrations/otlp.test.ts`
+ * 的「导出与出站同数」用例。
+ *
+ * 幂等：已经是 32-hex（trace）/ 16-hex（span）的输入原样通过（上游 span id 被再次转发不变形）。
+ */
+export declare function wireTraceId(id: string): string;
+export declare function wireSpanId(id: string): string;
+/**
+ * 生成 W3C `traceparent`（`parseTraceparent` 的镜像：一个解析、一个生成）。
+ *
+ * flags 位恒为 `00`：本框架**不采样**（每次 run 全量记账），故没有「已采样」可声明 ——
+ * 编一个 `01` 是替下游做决定。入站侧 `parseTraceparent` 也从不读 flags。
+ *
+ * 调用方保证给的是内部 id 或线缆 id（本函数只做投影，不做合法性判定）。
+ */
+export declare function formatTraceparent(traceId: string, spanId: string): string;
 export interface Span {
     spanId: SpanId;
     traceId: TraceId;

package/dist/core/trace.js

@@ -26,6 +26,37 @@ export function parseTraceparent(value) {
         return undefined;
     return { traceId, spanId };
 }
+/**
+ * 内部 id → **线缆形态**（W3C `traceparent` 与 OTLP 通用）。
+ *
+ * 内部 id 一律 UUID（去横线 32-hex），而线上两份契约都要求 trace 16 字节（32-hex）、
+ * span **8 字节（16-hex）** —— 宽度不同，不能共用。原样发出去会被判 `invalid span_id`
+ * （拒收）或按前 16 位截断。故 trace 侧去横线即可、span 侧必须截到 16 位。
+ *
+ * ⚠️ **单一真源**：OTLP 导出（`integrations/otlp.ts`）与出站 `formatTraceparent` 必须
+ * 走**同一份**投影。各写一份的后果不是「风格不统一」，而是**同一次调用在两个系统里
+ * 是两个 span id** —— 跨系统关联最不能出的错。要改这里，先看 `tests/integrations/otlp.test.ts`
+ * 的「导出与出站同数」用例。
+ *
+ * 幂等：已经是 32-hex（trace）/ 16-hex（span）的输入原样通过（上游 span id 被再次转发不变形）。
+ */
+export function wireTraceId(id) {
+    return id.replaceAll('-', '');
+}
+export function wireSpanId(id) {
+    return id.replaceAll('-', '').slice(0, 16);
+}
+/**
+ * 生成 W3C `traceparent`（`parseTraceparent` 的镜像：一个解析、一个生成）。
+ *
+ * flags 位恒为 `00`：本框架**不采样**（每次 run 全量记账），故没有「已采样」可声明 ——
+ * 编一个 `01` 是替下游做决定。入站侧 `parseTraceparent` 也从不读 flags。
+ *
+ * 调用方保证给的是内部 id 或线缆 id（本函数只做投影，不做合法性判定）。
+ */
+export function formatTraceparent(traceId, spanId) {
+    return `00-${wireTraceId(traceId)}-${wireSpanId(spanId)}-00`;
+}
 /**
  * 把评分挂到 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":"AAAA;;;GAGG;AAqEH,sEAAsE;AACtE,MAAM,cAAc,GAAG,6DAA6D,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAqDD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,KAAY;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC;IACpE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC9D,OAAO,YAAY,CAAC;AACtB,CAAC"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqEH,sEAAsE;AACtE,MAAM,cAAc,GAAG,6DAA6D,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc;IAC/D,OAAO,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;AAC/D,CAAC;AAqDD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,KAAY;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC;IACpE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC9D,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/engine/loop.js

@@ -1,9 +1,11 @@
 import { createAnthropicClient } from '../integrations/anthropic.js';
+import { withCurrentSpan } from './span-scope.js';
 import { abortedResult, failedResult, finishedResult, suspendedResult } from './loop-result.js';
 import { tailToolUses, textOfParam } from './resume-input.js';
 import { DEFAULT_MAX_ITERATIONS, DEFAULT_MAX_TOKENS, resolveDefaultModel, runConfigSnapshot, } from './run-config.js';
 import { TraceRecorder } from './tracer.js';
-import { abortedError, budgetError, buildLoopContext, checkTurnEntry, executeTurnTools, recordTurnUsage, streamTurn, textOf, } from './turn.js';
+import { abortedError, budgetError, buildLoopContext, checkTurnEntry, executeTurnTools, recordTurnUsage, streamTurn, } from './turn.js';
+import { textOf } from './text.js';
 import { resolveStopReason } from './stop-reason.js';
 import { isSuccessStopReason } from './types.js';
 /**
@@ -194,7 +196,9 @@ export async function runAgent(options) {
     const progress = { iterations: 0 };
     let result;
     try {
-        result = await agentLoop({
+        // run 根作用域（spec §9.2 出站传播）：循环内任何地方（工具 / 子能力 / 中间件）都读得到
+        // 「我正处在哪个 span」—— 更内层的作用域由 turn / skill / subagent 逐层收窄。
+        result = await withCurrentSpan({ traceId: recorder.traceId, spanId: rootId }, () => agentLoop({
             client: options.client ?? createAnthropicClient(),
             model: resolveDefaultModel(options.model),
             maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
@@ -219,7 +223,7 @@ export async function runAgent(options) {
             priceOverrides: options.priceOverrides,
             onUnpricedModel: options.onUnpricedModel,
             approvals: options.approvals,
-        });
+        }));
     }
     catch (e) {
         // 硬写 0 会把「第 3 回合请求失败」报成「一次模型都没调」——按实际进度报

package/dist/engine/loop.js.map

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

package/dist/engine/span-scope.d.ts

@@ -0,0 +1,48 @@
+import { type SpanId } from '../core/trace.js';
+/**
+ * Agentia —— **调用期**「当前 span」作用域（spec §9.2 出站传播）。
+ *
+ * 为什么不是 run 级：run 级 ALS 只有一个值，并行工具调用会互相覆盖 ⇒ 父子关系错。
+ * spec §9.2 正是因此锁定「span 句柄**不放** `RunContext`」（那里只有 blackboard）。
+ * 这里**每次调用一份** —— `withCurrentSpan` 进入的是该次调用的 async 上下文，
+ * 并行调用天然互不干扰（`tests/engine/spanScope.test.ts` 钉着这条）。
+ *
+ * 写入点由粗到细三层，内层覆盖外层：
+ * - `run` 根 —— `engine/loop.ts` 包住整轮循环；
+ * - `llm.turn` —— `engine/turn.ts` 包住每次工具调用（普通工具与 `@Prompt` **刻意不建 span**，
+ *   它们的「当前 span」就是发起它的那个回合，与 `ToolRunContext.parentSpanId` 同一个值）；
+ * - `capability` —— `toolkit/skill.ts` / `toolkit/subagent.ts` 包住自己的方法体 / 子循环。
+ *
+ * 边界（如实）：`run` 根 span 由 `runAgent` 打开，故 `executeRun` 里更早的 `contextInit` /
+ * 记忆水合**没有**作用域 —— 那时确实还没有 span 可指，`currentTraceparent()` 返回 `undefined`。
+ */
+/** 作用域内容：一次调用同时知道自己是哪条 trace 的哪个 span（两件都要，才能编出合法头） */
+export interface SpanScope {
+    traceId: string;
+    spanId: SpanId;
+}
+/**
+ * 在指定 span 作用域内执行。返回类型随 fn 而定（async fn → Promise<T>，同步 fn → T）。
+ *
+ * 传的是**值**而不是「读 ctx」：写入者手上只有 recorder 与 span id，这里不去反向依赖
+ * runtime 的 `RunContext`（`engine` 不能引 `runtime`，分层单向）。
+ */
+export declare function withCurrentSpan<T>(scope: SpanScope, fn: () => Promise<T>): Promise<T>;
+export declare function withCurrentSpan<T>(scope: SpanScope, fn: () => T): T;
+/** 当前调用期的 span 作用域；不在任何 run / 调用内时 undefined。 */
+export declare function currentSpan(): SpanScope | undefined;
+/**
+ * 当前调用期的 W3C `traceparent`（**公共 API**，spec §9.2 出站传播）。
+ *
+ * 玩法：在自己发起的出站请求里带上它，下游就能把「谁触发了这次调用」记成一条指向
+ * **具体 span** 的 link（粒度到 turn / capability，不再是 run 级）。
+ *
+ * ```ts
+ * await fetch(url, { headers: { traceparent: currentTraceparent()! } });
+ * ```
+ *
+ * - 不在 run 内、或在 `run` 根 span 打开之前的环节（`contextInit` / 记忆水合）→ `undefined`；
+ * - flags 位恒 `00`：本框架不采样，不替下游声明「已采样」；
+ * - 框架**不替你做**出站注入（它不创建出站请求）—— 这一行是你自己的。
+ */
+export declare function currentTraceparent(): string | undefined;

package/dist/engine/span-scope.js

@@ -0,0 +1,31 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { formatTraceparent } from '../core/trace.js';
+const store = new AsyncLocalStorage();
+export function withCurrentSpan(scope, fn) {
+    return store.run(scope, fn);
+}
+/** 当前调用期的 span 作用域；不在任何 run / 调用内时 undefined。 */
+export function currentSpan() {
+    return store.getStore();
+}
+/**
+ * 当前调用期的 W3C `traceparent`（**公共 API**，spec §9.2 出站传播）。
+ *
+ * 玩法：在自己发起的出站请求里带上它，下游就能把「谁触发了这次调用」记成一条指向
+ * **具体 span** 的 link（粒度到 turn / capability，不再是 run 级）。
+ *
+ * ```ts
+ * await fetch(url, { headers: { traceparent: currentTraceparent()! } });
+ * ```
+ *
+ * - 不在 run 内、或在 `run` 根 span 打开之前的环节（`contextInit` / 记忆水合）→ `undefined`；
+ * - flags 位恒 `00`：本框架不采样，不替下游声明「已采样」；
+ * - 框架**不替你做**出站注入（它不创建出站请求）—— 这一行是你自己的。
+ */
+export function currentTraceparent() {
+    const scope = store.getStore();
+    if (!scope)
+        return undefined;
+    return formatTraceparent(scope.traceId, scope.spanId);
+}
+//# sourceMappingURL=span-scope.js.map