@migor/agentia 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,109 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [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
+
+### 变更
+
+> 本版主题（窗口 `0.7.2 → 0.8.0`，含 #83–#105）：**CLI 机器可读面 + 脚手架生产路径修复**。
+> 框架运行时 API 零变化；窗口内 23 个提交里 13 个是纯结构拆分（AsyncRunner / turn / loop /
+> http 外移判定面，零行为变化），其余大多是仓库自身的门禁与测试加固。
+> **一条必须看的修复**：用 ≤0.7.2 的 `agentia create` 生成过工程的，
+> `npm run build && npm start` 一跑就崩（discover 目录是 cwd 相对写法，生产形态下会去加载
+> `src/` 的 `.ts` 源码）。缺陷在**生成出来的工程里**，升级 CLI 不会自动修好已有工程 ——
+> 迁移办法见下方「迁移」。
+
+### 新增（CLI）
+
+- **`agentia --version` / `-v`**：打印 CLI 版本（读包自身 `package.json`）。
+- **`report` / `diff` / `doctor` 支持 `--json`**：stdout 只输出一个 JSON 文档，可直接进
+  管道与 CI；出错仍走 stderr + 退出码 1，且 stdout 保持空。`harvest` 刻意不加
+  （它的 stdout 本身就是产物）；`dev` 额外参数原样透传给用户脚本。
+- **脚手架把 `@migor/cli` 写进生成工程的 devDependencies**（与框架同 `^` 版本），`dev`
+  script 改为 `agentia dev`：`npx agentia …` 走本地 bin —— 离线可用，且版本被 pin 住与
+  框架同批（不 pin 的话老工程会被 npx 拉到最新 CLI）。
+
+### 修复
+
+- **脚手架生成工程的 discover 目录按本文件位置解析，不再是 cwd 相对字符串**（本版最高
+  优先级）：旧模板生成的工程 `npm run build && npm start` 必崩
+  "Invalid or unexpected token"（生产形态下去加载 `src/` 的 `.ts` 源码，而装饰器不是
+  可擦除语法），换个 cwd 启动连目录都找不到。**0.7.2 及之前所有版本生成的工程都带此
+  缺陷。** 新写法按 `import.meta.url` 相对本文件解析（开发态 `src/`、构建后 `dist/` 都
+  成立），并过滤不存在的分类目录（空分类 tsc 不产出 `dist/<分类>/`，「这类暂时没有能力」
+  不该让启动失败）。
+
+### 迁移
+
+- **用 ≤0.7.2 的 `agentia create` 生成过工程的**：把工程 `src/main.ts` 的 discover 段
+  换成新模板的写法（重新 `agentia create` 一个同名工程对照抄过来即可 —— 核心是目录按
+  `new URL(d + '/', import.meta.url)` 解析 + `existsSync` 过滤这两处）。
+  框架 API 本身无破坏性变更，`@migor/agentia` 与 `@migor/cli` 升到 `^0.8.0` 即可。
+
+### 内部（不影响使用者）
+
+- 纯结构拆分 13 件：AsyncRunner 五步（SlotPool / approval-policy / DrainGate /
+  resume-policy / TaskWaiters）、`turn.ts` 四步、`loop.ts` 三步、`http.ts` 两步 ——
+  判定面有名字、编排留在原处，零行为变化（#85–#100）。
+- Biome 零告警闸门：93 warnings + 12 infos → 0，verify-all 第 1 步与 CI lint job 翻
+  `--error-on-warnings`（#84）。
+- 计时断言不再卡预算边界、改用单调时钟量（#102 / #103）。
+- 覆盖率棘轮门禁（c8：行 95 / 分支 85 / 函数 92）+ e2e-cli 折入「npm pack → 离线安装 →
+  装出来的包真跑最小 run」（#104）。
+- CLI 模板从字符串升级为真文件（`packages/cli/templates/`，生成产物逐字节不变）（#105）。
+
 ## [0.7.2] - 2026-09-20
 
 ### 变更
@@ -676,7 +779,9 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.7.2...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.8.1...HEAD
+[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
 [0.7.0]: https://github.com/retrychx/agentia/releases/tag/v0.7.0

package/README.md

@@ -19,18 +19,22 @@
 ## 安装与配置
 
 ```bash
-npm i @migor/agentia                 # 框架（项目依赖）
-npm i -g @migor/cli                  # 命令行工具（脚手架 / 生成 / 调试）
-
-agentia create my-app                # 脚手架（含 .env / .env.example）
-$EDITOR my-app/.env                  # 填 ANTHROPIC_API_KEY（也可直接 export，真实环境变量优先）
+npx @migor/cli create my-app         # 脚手架（含 .env / .env.example）
+cd my-app && npm install             # 框架与 CLI 都装进工程
+$EDITOR .env                         # 填 ANTHROPIC_API_KEY（也可直接 export，真实环境变量优先）
+npm run dev                          # = agentia dev：tsx watch + 本地 inspector 面板
 # 可选：ANTHROPIC_BASE_URL（兼容端点）、AGENTIA_MODEL（缺省 claude-opus-5）
+
+# 工程内直接用：npx agentia g tool fetch-weather / npx agentia doctor / npx agentia --version
+#   （脚手架把 @migor/cli 装进 devDependencies ⇒ 走本地 bin，离线可用、版本与工程一同 pin）
+# 首次创建必须带 scope —— npm 上另有一个别人的 `agentia` 包，短名会装错东西。
+# 想全局装（到处都能敲 agentia）：npm i -g @migor/cli
 ```
 
 > 框架**不自动**读 `.env`：脚手架 `src/main.ts` 首行的 `loadEnvFile()` 负责把它读进 `process.env`。
 > 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。
 
-> **版本**：`0.7.2`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> **版本**：`0.8.1`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
 > `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
 > [`examples/README.md`](examples/README.md) 的「依赖说明」。
 

package/dist/AGENTS.md

@@ -80,16 +80,28 @@ console.log(result.finalText, result.stopReason, result.trace.totalUsage);
 ## 2. 项目结构（CLI 约定）
 
 ```bash
-npx @migor/cli create my-app     # 脚手架（含 .env / .env.example）
-cd my-app && npm install
+npx @migor/cli create my-app     # 首次创建：必须带 scope（短名 agentia 在 npm 上是别人的包）
+cd my-app && npm install         # 框架与 CLI 都装进工程
 $EDITOR .env                     # 填 ANTHROPIC_API_KEY（脚手架已生成，且已被 .gitignore 挡住）
-npx @migor/cli dev               # tsx watch + 本地 inspector 面板
-npx @migor/cli g tool fetch-weather   # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
-npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复）
+npm run dev                      # = agentia dev：tsx watch + 本地 inspector 面板
+npx agentia g tool fetch-weather   # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
+npx agentia doctor               # 静态体检（未登记/悬空/命名/重复）
+npx agentia --version            # CLI 版本（= -v）
 ```
 
+> **命令从哪来**：脚手架把 `@migor/cli` 装进工程的 `devDependencies`，所以**工程内**用短名
+> `npx agentia …` 即可（走本地 bin：离线可用、版本与工程一同 pin）。**首次创建**必须用带 scope 的
+> `npx @migor/cli create` —— npm 上另有一个别人的 `agentia` 包，短名会装错东西。
+> 想全局装上（到处都能敲 `agentia`）：`npm i -g @migor/cli`。
+
 四分类目录，一能力一文件夹：`src/tools/` · `src/skills/` · `src/prompts/` · `src/subagents/` —— **目录名就是类型**，不用记别名。每个文件夹的 `index.ts` 是入口，`default export` 支持三种形态：**类**（token = 文件夹名）、**Provider 对象**、**Provider 数组**。显式注册表在 `src/registry.ts`（`agentia g` 自动维护，也可手改）。
 
+> **脚手架 `src/main.ts` 怎么找这些目录**：按**本文件位置**解析（`fileURLToPath(new URL('tools/', import.meta.url))`），
+> 所以 dev 解析到 `src/`、`npm run build` 之后解析到 `dist/` —— 从任何目录启动都成立，也不受 cwd 影响。
+> 别改成 cwd 相对写法（形如 `src/tools` 的字符串）：那样 `node dist/main.js` 会去加载 `src/` 下的 `.ts`
+> 源码，而装饰器不是可擦除的类型语法，Node 直接跑不了。空分类目录（还没有该类型的能力 ⇒ 构建后没有
+> 对应 `dist/<分类>/`）要过滤掉，否则 `discover` 会因「显式给出的路径不存在」而报错。
+
 > **陷阱**：装饰器注册表是模块级 `WeakMap`。框架必须是**单一模块实例** —— 混用 `src` 与 `dist`、或在一个仓库里装两份 agentia，会让能力收集为空。让 CLI 生成的 `package.json` 里只依赖一份框架即可。
 
 ---
@@ -666,8 +678,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 派生）
 
@@ -772,6 +810,9 @@ console.log(renderRunReport(report));
 
 CLI 侧有薄壳：`agentia report <trace.jsonl>` —— 每行一个 JSON（裸 Trace，或含 `result.trace` /
 `trace` 的 TaskRecord，如 `FileTaskStore` 的导出），跨行按能力合并后打印排行。
+加 `--json` 得到机器可读输出：stdout 只有一个 JSON 文档（`{ file, runs, failed, skippedLines,
+failures, capabilities, totals }`）、没有人类装饰，适合脚本与 CI 断言；出错仍走 stderr
+（`错误：…`）并把退出码置 1、stdout 保持为空 —— 脚本据此区分「有结果」与「没跑成」。
 
 > ⚠️ **单条 run 内样本常 < 5，分位没有意义** —— 所以报告以 `total` / `max` 为主；
 > 要看分位请用 `mergeRunReports` 汇总多条，或用 `metricsSink` 的直方图。
@@ -976,7 +1017,12 @@ const c = await app.run(messages); // 起一条新 run，沿着分叉点前的
 
 不落代码也可以直比两份 trace 导出：`agentia diff a.jsonl b.jsonl`（输入形态同 `agentia report`），
 打印 run 级 summary + 逐 span 差异，**有差异时退出码 1**（diff(1) 语义）——可直接进 CI 挡
-「换 prompt / 模型后轨迹漂移」。
+「换 prompt / 模型后轨迹漂移」。`--json` 给出结构化差异（`{ a, b, equal, summary, spans }`，
+每个 span 带 `path` / `missing` / `fields`），**退出码语义不变**（有差异仍为 1）—— 门禁照旧可用，
+只是「差在哪」也能被读。`agentia doctor --json` 同理（体检结果结构化，有错误仍退出 1）。
+
+> `report` / `diff` / `doctor` 支持 `--json`；`harvest` **没有**：它的 stdout 本身就是产物
+> （生成的 eval 文件源码），加 `--json` 会自相矛盾。
 
 - **配对语义**（结构性配对，字段差异不影响配对）：llm.turn 按回合序配对、**忽略 span name** ——
   name 是模型 id，而「换模型重跑」正是 A/B 主用例，按 name 配对会把两侧所有 turn 报成缺失；
@@ -1230,7 +1276,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/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-result.d.ts

@@ -0,0 +1,72 @@
+import type { MessageParam } from '../core/message.js';
+import type { SpanError } from '../core/trace.js';
+import type { AgentStopReason } from './types.js';
+/**
+ * Agentia —— 循环出口的**结果形状单源**（engine/loop.ts 的拆分第二步）。
+ *
+ * `AgentLoopResult` 属「结果/状态记录」型（`docs/guards.md` 的类型角色表）：7 个字段
+ * **必须全在场**，值可以为 undefined —— 消费方按 `result.suspendedMessages === undefined`
+ * 判「没挂起」，而「字段缺席」与「字段为 undefined」在 JSON / OTLP 上是两回事。
+ *
+ * 此前这 7 个字段由 loop.ts 的五处对象字面量各写一遍（= 35 次「记得写」）：加一个字段
+ * 要改五处，漏一处就是无声的形状漂移。现在出口只剩四个具名构造器，各自的语义写在名字上：
+ *
+ *   suspendedResult  挂起（等人审批）—— 不是失败；交出的历史是**拷贝**
+ *   abortedResult    已取消 —— 带结构化 error（取消不是失败，但原因要可查）
+ *   failedResult     抛出被兜住 —— 由 `classifyError` 翻成结构化 error
+ *   finishedResult   循环这次**结束**了 —— 成败由 stopReason 表达，error 由调用方给
+ *
+ * 文件分工：本文件只管「出口长什么样」；什么时候走哪个出口由 engine/loop.ts 决定。
+ */
+export interface AgentLoopResult<T = unknown> {
+    stopReason: AgentStopReason;
+    finalText: string;
+    /** 非正常收尾时的结构化原因；正常收尾为 undefined（**字段在场**，见 core/run.ts 的说明） */
+    error: SpanError | undefined;
+    /** 本轮循环自己发起的模型往返次数 */
+    iterations: number;
+    /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
+    typed: T | undefined;
+    /**
+     * HITL 挂起（stopReason === 'awaiting_approval'）时的完整消息历史
+     * （末尾是含未决 tool_use 的 assistant 消息）；未挂起为 undefined（字段在场）。
+     */
+    suspendedMessages: MessageParam[] | undefined;
+    /** HITL 挂起时待决的 tool_use_id 列表；未挂起为 undefined（字段在场） */
+    pendingApprovals: string[] | undefined;
+}
+/** 挂起收尾（两处出口共用：循环中途挂起 / 恢复模式进来发现决定仍不齐） */
+export declare function suspendedResult<T>(ctx: {
+    messages: MessageParam[];
+    progress: {
+        iterations: number;
+    };
+    typed: T | undefined;
+}, pending: string[], 
+/** 挂起前那一回合的文本（循环中途挂起时给；恢复模式再次挂起时没有新回合，留空） */
+finalText?: string): AgentLoopResult<T>;
+/**
+ * 已取消收尾。取消**不是失败**，但必须带结构化 error —— 否则 trace 上只看到「停了」，
+ * 看不出是「人取消的」还是「上游出错的」。
+ *
+ * `iterations` 由调用方给实际进度：取消可能发生在第 N 回合之后，硬写 0 会谎报成「一次模型都没调」。
+ */
+export declare function abortedResult<T = never>(iterations?: number): AgentLoopResult<T>;
+/**
+ * 抛出被兜住的收尾：`cause` 是**任何**抛出来的东西（SDK 异常、类型错误、abort 信号……），
+ * 出口处一律经 `classifyError` 翻成结构化 SpanError —— 「非正常收尾必带结构化 error」
+ * 这条不变量落在这一处，而不是散在各 catch 里。
+ */
+export declare function failedResult<T = never>(cause: unknown, iterations: number): AgentLoopResult<T>;
+/**
+ * 循环这次结束了。名字刻意不含成败：`stopReason` 才是成败的表达
+ * （`end_turn` / `stop_sequence` 成功，`budget_exceeded` / `max_iterations` / `refusal` 一类
+ * 非正常收尾则由调用方把结构化 `error` 一并给出）。
+ */
+export declare function finishedResult<T>(f: {
+    stopReason: AgentStopReason;
+    finalText: string;
+    iterations: number;
+    typed: T | undefined;
+    error?: SpanError | undefined;
+}): AgentLoopResult<T>;

package/dist/engine/loop-result.js

@@ -0,0 +1,80 @@
+import { classifyError } from './errors.js';
+import { abortedError } from './turn.js';
+/**
+ * 出口的公共底座：把五个「每次都得给」的字段写全，并把两个「只有挂起才非空」的字段
+ * 显式写成**在场**。唯一不经过它的是 `suspendedResult` —— 那正是它要覆盖这两个字段的原因。
+ */
+function loopResult(f) {
+    return {
+        stopReason: f.stopReason,
+        finalText: f.finalText,
+        error: f.error,
+        iterations: f.iterations,
+        typed: f.typed,
+        suspendedMessages: undefined,
+        pendingApprovals: undefined,
+    };
+}
+/** 挂起收尾（两处出口共用：循环中途挂起 / 恢复模式进来发现决定仍不齐） */
+export function suspendedResult(ctx, pending, 
+/** 挂起前那一回合的文本（循环中途挂起时给；恢复模式再次挂起时没有新回合，留空） */
+finalText = '') {
+    return {
+        ...loopResult({
+            stopReason: 'awaiting_approval',
+            finalText,
+            // 挂起不是失败：等人不该被看板算成失败（区分由 stopReason 承担）
+            error: undefined,
+            iterations: ctx.progress.iterations,
+            typed: ctx.typed,
+        }),
+        // 历史是**拷贝**：宿主落库后仍可能继续用同一条数组，挂起段的消息不能再被改
+        suspendedMessages: [...ctx.messages],
+        // 待决 id 列表原样交出（同一引用）—— 调用方此后不再改动它，保留原行为，不顺手加拷贝
+        pendingApprovals: pending,
+    };
+}
+/**
+ * 已取消收尾。取消**不是失败**，但必须带结构化 error —— 否则 trace 上只看到「停了」，
+ * 看不出是「人取消的」还是「上游出错的」。
+ *
+ * `iterations` 由调用方给实际进度：取消可能发生在第 N 回合之后，硬写 0 会谎报成「一次模型都没调」。
+ */
+export function abortedResult(iterations = 0) {
+    return loopResult({
+        stopReason: 'aborted',
+        finalText: '',
+        error: abortedError(),
+        iterations,
+        typed: undefined,
+    });
+}
+/**
+ * 抛出被兜住的收尾：`cause` 是**任何**抛出来的东西（SDK 异常、类型错误、abort 信号……），
+ * 出口处一律经 `classifyError` 翻成结构化 SpanError —— 「非正常收尾必带结构化 error」
+ * 这条不变量落在这一处，而不是散在各 catch 里。
+ */
+export function failedResult(cause, iterations) {
+    return loopResult({
+        stopReason: 'error',
+        finalText: '',
+        error: classifyError(cause),
+        iterations,
+        typed: undefined,
+    });
+}
+/**
+ * 循环这次结束了。名字刻意不含成败：`stopReason` 才是成败的表达
+ * （`end_turn` / `stop_sequence` 成功，`budget_exceeded` / `max_iterations` / `refusal` 一类
+ * 非正常收尾则由调用方把结构化 `error` 一并给出）。
+ */
+export function finishedResult(f) {
+    return loopResult({
+        stopReason: f.stopReason,
+        finalText: f.finalText,
+        error: f.error,
+        iterations: f.iterations,
+        typed: f.typed,
+    });
+}
+//# sourceMappingURL=loop-result.js.map

package/dist/engine/loop-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-result.js","sourceRoot":"","sources":["../../src/engine/loop-result.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuCzC;;;GAGG;AACH,SAAS,UAAU,CAAI,CAMtB;IACC,OAAO;QACL,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,iBAAiB,EAAE,SAAS;QAC5B,gBAAgB,EAAE,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,eAAe,CAC7B,GAAyF,EACzF,OAAiB;AACjB,6CAA6C;AAC7C,SAAS,GAAG,EAAE;IAEd,OAAO;QACL,GAAG,UAAU,CAAI;YACf,UAAU,EAAE,mBAAmB;YAC/B,SAAS;YACT,wCAAwC;YACxC,KAAK,EAAE,SAAS;YAChB,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU;YACnC,KAAK,EAAE,GAAG,CAAC,KAAK;SACjB,CAAC;QACF,yCAAyC;QACzC,iBAAiB,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;QACpC,+CAA+C;QAC/C,gBAAgB,EAAE,OAAO;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAY,UAAU,GAAG,CAAC;IACrD,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,YAAY,EAAE;QACrB,UAAU;QACV,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAY,KAAc,EAAE,UAAkB;IACxE,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,OAAO;QACnB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC;QAC3B,UAAU;QACV,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,CAMjC;IACC,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/loop.d.ts

@@ -1,46 +1,9 @@
 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 { SpanId } from '../core/trace.js';
+import type { AgentLoopResult } from './loop-result.js';
 import type { RetryOptions } from './retry.js';
-import type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, SystemParam } from './types.js';
-/**
- * 缺省模型解析：显式传入 > AGENTIA_MODEL env > 'claude-opus-5'。
- * 不把端点私有模型写死在代码里 —— 走 Anthropic 兼容网关（如 DeepSeek 端点）时
- * 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;
-    /** 非正常收尾时的结构化原因；正常收尾为 undefined（**字段在场**，见 core/run.ts 的说明） */
-    error: SpanError | undefined;
-    /** 本轮循环自己发起的模型往返次数 */
-    iterations: number;
-    /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
-    typed: T | undefined;
-    /**
-     * HITL 挂起（stopReason === 'awaiting_approval'）时的完整消息历史
-     * （末尾是含未决 tool_use 的 assistant 消息）；未挂起为 undefined（字段在场）。
-     */
-    suspendedMessages: MessageParam[] | undefined;
-    /** HITL 挂起时待决的 tool_use_id 列表；未挂起为 undefined（字段在场） */
-    pendingApprovals: string[] | undefined;
-}
+import type { AgentRunResult, ContextPolicy, RunAgentOptions, SystemParam } from './types.js';
 /** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
 export declare function runAgent<S extends JsonSchema = JsonSchema>(options: RunAgentOptions<S>): Promise<AgentRunResult<SchemaType<S>>>;
 /**