@migor/agentia 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,118 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [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
+
+### 变更
+
+> 本版主题（窗口 `0.7.1 → 0.7.2`，含 #77–#81）：**第九轮评审收口** —— 一条高优先级的
+> **HITL × `sessionStore` 组合破口**（挂起任务恢复后历史翻倍、成功后又把坏会话写回去），
+> 外加六条中/低优先级的静默失效修复；其余是纯结构重构、回归测试补课与依赖升级。
+> **无破坏性变更，不需要改代码**：所有修复都是「旧行为本来就不该那样」。
+> **两处错误归类收紧（记账口径，不是行为变更）**：Anthropic 流内 4xx 不再落成可重试的
+> `server`，异步宿主的 `runTimeoutMs` 超时不再落 `unknown`。宿主若按 `error.type` /
+> `errorKind` / `retryable` 分支（重试、告警、看板），取值会更准 —— 见下方两条。
+> 本条目的多数内容**是在本次发版时回填的**：窗口内 5 个 PR 都没写 CHANGELOG，
+> 条目按各提交正文重建。
+
+### 修复（第九轮评审收口）
+
+- **HITL × `sessionStore`：挂起任务恢复后会话历史翻倍 + 成功后毒化会话**（本版最高优先级）：
+  恢复段曾把 session 再注入 `app.run`，而挂起段落库的 `suspendedMessages` 已含完整历史 ⇒
+  run 层 `loadSession` 又 prepend 一遍（历史翻倍、token 复利）；且成功后 `appendSession`
+  会把含未决 `tool_use` 的整段扩展历史写回会话 —— 该会话**下一轮直接撞 API 400**
+  （孤立 `tool_use` + 连续 assistant）。现在恢复段不再注入 session，会话回写改由
+  `AsyncRunner` 按「本轮用户输入 + 最终回复」补，口径与 `run.ts` 的三条不变量一致。
+- **惰性审批超时 `#expireAndResume` 补重入闸 + 进闸后重读 store**：异步 store 下两个并发
+  `poll` 各拿到一份 `awaiting` 副本 ⇒ 双双填超时拒绝、**双双派发**（同一任务跑两遍）。
+  现在与 `approve` 共用同一把 per-taskId 在飞闸。
+- **MCP StreamableHTTP 连接器不再丢弃 `abandoned`**：`tools/call` 把引擎的「放弃等待」
+  信号透传到在飞 `fetch`（含会话 404 自愈那次重试）—— 裁判放弃后真能掐掉请求，
+  而不是继续在后台烧。stdio 侧 #75 的 `pending` 出簿修复这次补上了回归用例。
+- **Anthropic 流内 `error` 事件的 status 反推补 4xx 档**：`invalid_request_error` /
+  `authentication_error` / `permission_error` / `not_found_error` → 400（归 `api`、
+  **不可重试**），与 `openai.ts` 同口径。此前这些确定性病因落 500 + `retryable:true`，
+  引擎会白重试 3 次（3 次网络请求 + 3 倍等待）。
+- **异步宿主 `runTimeoutMs` 的超时错误不再落 `unknown`**：改用 `core/timeout.ts` 的
+  `TimeoutError`（`code='timeout'`），与引擎工具超时 / MCP 桥兜底同口径。归类由
+  `unknown`（`retryable:false`）变为 `timeout`（`retryable:true`）—— 这只是**记账口径**：
+  超时按定义属可重试故障，框架**不会**因此自动重跑整个 run，要不要重试仍由宿主决定。
+- **`FileTaskStore.save` 改为先落盘、成功后再更新内存**：落盘失败时内存不再推进，
+  避免内存与磁盘两本账、重启后静默回退（`get` / `byIdempotency` 查不到未落盘的记录）。
+- **Anthropic SSE 组装拦畸形 `content_block_start.index`**：超大 index（如 `1e9`）会造出
+  稀疏数组、后续 `for...of` / `reduce` 按 `length` 空转；现在畸形 index（负数 / 非整数 /
+  超上限）响亮抛 `AnthropicApiError(500)`。
+
+### 重构（纯结构，零行为变化）
+
+- `integrations/metrics.ts`（1050 行）→ `metrics-state.ts` / `metrics-render.ts` /
+  `metrics-otlp.ts` / `metrics.ts`（只留选项校验、定时器与组装）；
+  `integrations/mcp.ts`（897 行）→ `mcp-stdio.ts` / `mcp-http.ts` / `mcp.ts`
+  （桥 + 共享 helper + re-export 两个连接器工厂）。**公共面与运行时行为不变**。
+
+### 测试
+
+- 补上 #75 遗留的回归用例：stdio MCP 连接器「裁判放弃等待 ⇒ `pending` 记账出簿」的防泄漏
+  修复此前**没有任何用例守着**（夹具新增 `silentcall` 模式：握手 / `tools/list` 正常、
+  `tools/call` 永不回包）。
+
+### 依赖
+
+- 开发依赖：`@anthropic-ai/sdk` → 0.126.0、`@biomejs/biome` → 2.5.14、
+  `@types/node` → 26.6.1、`zod` → 4.6.5（均不影响运行时面）。
+- 官网（不随包发布）：`astro` → 7.3.3。
+
 ## [0.7.1] - 2026-09-19
 
 ### 变更
@@ -615,7 +727,9 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.8.0...HEAD
+[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
 [0.6.3]: https://github.com/retrychx/agentia/releases/tag/v0.6.3

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.1`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> **版本**：`0.8.0`（`@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` 里只依赖一份框架即可。
 
 ---
@@ -772,6 +784,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 +991,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 报成缺失；
@@ -1237,6 +1257,7 @@ const callable = {
 | 挂起段与恢复段是两棵 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（要审批的能力请放主菜单） |
 | 同步 `/run` 撞上审批没人可批 | 同步 RPC 会带着 `stopReason: 'awaiting_approval'` 收尾返回 —— 但响应体（`toHttpBody`）**不含** `suspendedMessages`，也没有任务记录可审批（待决清单只能去 trace 的 `approval.requested` 事件里看）。**要审批请走 `POST /tasks` 异步宿主** |
 | Scheduler 调度表不落库 | `every` / `at` 的调度本身只在内存：已 submit 的任务记录能经 `resumePending` 续跑，但「未来某刻再触发」的调度在重启后不存在（远期单发由宿主自己的 cron 驱动）。另：`drain()` 不停 Scheduler —— 停机窗口内到点的 tick 会打一条触发失败日志（无害但吵），介意就 `scheduler.stop()` 先行 |

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>>>;
 /**