@armadra/agent 0.7.6 → 0.8.1

package/dist/cli/subcommands/stats.js

@@ -5,7 +5,7 @@
  * - 时间：`--since` / `--until` 接受 `7d`（含今天的最近 7 天）、`today`、`YYYY-MM-DD`（本地日期，含当天）。
  * - 分组：`--by day|week|month|provider|channel|model|project`。
  * - 缓存：`<数据目录>/stats-index.json`，按文件 mtime / size 失效；`--no-cache` 不读也不写。
- * - 口径见 session/stats-aggregate.ts 与 docs/sessions.md「统计」。
+ * - 口径见 session/stats-aggregate.ts 与 docs/guides/sessions.md「统计」。
  */
 import { join, resolve } from "node:path";
 import { expandHome, resolveDataDir } from "../../config/paths.js";

package/dist/codemode/capability.d.ts

@@ -1,5 +1,5 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/guides/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
  * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS

package/dist/codemode/capability.js

@@ -1,5 +1,5 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/guides/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
  * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS

package/dist/codemode/host-side.d.ts

@@ -3,7 +3,7 @@
  *
  * - 命令行：`<node> --max-old-space-size=<MB> --permission --allow-fs-read=<入口>
  *   --disallow-code-generation-from-strings <入口> --ama-codemode-sandbox`；堆上限取 `codemode.maxHeapMb`
- *   （缺省 256，0 不加），超出时子进程 OOM 退出，映射为脚本错误（docs/memory-plan.md D10）；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
+ *   （缺省 256，0 不加），超出时子进程 OOM 退出，映射为脚本错误（docs/history/memory-plan.md D10）；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
  *   子进程、worker、addon、inspector 权限；以空环境启动（拿不到密钥与会话路径）；嵌入 Electron
  *   时设 `ELECTRON_RUN_AS_NODE=1` 运行同一可执行文件。
  * - 入口：bundle 里是 ama.cjs 同目录的 `ama-sandbox.cjs`（构建脚本定义 `__AMA_SANDBOX_ENTRY__`）；
@@ -13,7 +13,7 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
- * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ * - OS 沙箱（docs/guides/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
  *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
  *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */

package/dist/codemode/host-side.js

@@ -3,7 +3,7 @@
  *
  * - 命令行：`<node> --max-old-space-size=<MB> --permission --allow-fs-read=<入口>
  *   --disallow-code-generation-from-strings <入口> --ama-codemode-sandbox`；堆上限取 `codemode.maxHeapMb`
- *   （缺省 256，0 不加），超出时子进程 OOM 退出，映射为脚本错误（docs/memory-plan.md D10）；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
+ *   （缺省 256，0 不加），超出时子进程 OOM 退出，映射为脚本错误（docs/history/memory-plan.md D10）；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
  *   子进程、worker、addon、inspector 权限；以空环境启动（拿不到密钥与会话路径）；嵌入 Electron
  *   时设 `ELECTRON_RUN_AS_NODE=1` 运行同一可执行文件。
  * - 入口：bundle 里是 ama.cjs 同目录的 `ama-sandbox.cjs`（构建脚本定义 `__AMA_SANDBOX_ENTRY__`）；
@@ -13,7 +13,7 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
- * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ * - OS 沙箱（docs/guides/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
  *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
  *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */

package/dist/compaction/image-budget.d.ts

@@ -1,5 +1,5 @@
 /**
- * 单请求图片总量预算（docs/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
+ * 单请求图片总量预算（docs/history/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
  *
  * base64 图片在历史里每轮重发，几张截图就可能撞上 Anthropic 32 MB / Gemini 20 MB 的请求上限。
  * `planImageBudget` 给出要降级的消息：调用方把每条写成 `context_edit{reason:"image_budget"}`，

package/dist/compaction/image-budget.js

@@ -1,5 +1,5 @@
 /**
- * 单请求图片总量预算（docs/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
+ * 单请求图片总量预算（docs/history/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
  *
  * base64 图片在历史里每轮重发，几张截图就可能撞上 Anthropic 32 MB / Gemini 20 MB 的请求上限。
  * `planImageBudget` 给出要降级的消息：调用方把每条写成 `context_edit{reason:"image_budget"}`，

package/dist/config/edit.d.ts

@@ -1,5 +1,5 @@
 /**
- * Settings edit core (docs/wave6-plan.md §6.2, D24-D26). [W6-S]
+ * Settings edit core (docs/history/wave6-plan.md §6.2, D24-D26). [W6-S]
  *
  * Shared by the `/config` panel, `/config key=value` and `ama config get | set | unset | list`:
  * - `readSnapshot()` reads the user and project files fresh and merges them with the profile / command

package/dist/config/edit.js

@@ -1,5 +1,5 @@
 /**
- * Settings edit core (docs/wave6-plan.md §6.2, D24-D26). [W6-S]
+ * Settings edit core (docs/history/wave6-plan.md §6.2, D24-D26). [W6-S]
  *
  * Shared by the `/config` panel, `/config key=value` and `ama config get | set | unset | list`:
  * - `readSnapshot()` reads the user and project files fresh and merges them with the profile / command

package/dist/config/init.d.ts

@@ -1,5 +1,5 @@
 /**
- * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ * 配置目录初始化（docs/guides/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
  *
  * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）：只有 `$schema`、
  *   `version` 与空 `providers`，不写死任何缺省值——缺省值以后调整（例如 codemode 跟随预设）对老用户

package/dist/config/init.js

@@ -1,5 +1,5 @@
 /**
- * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ * 配置目录初始化（docs/guides/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
  *
  * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）：只有 `$schema`、
  *   `version` 与空 `providers`，不写死任何缺省值——缺省值以后调整（例如 codemode 跟随预设）对老用户

package/dist/config/json-schema.d.ts

@@ -1,6 +1,6 @@
 /**
  * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
- * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
+ * （docs/guides/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
  * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
  * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
  * 顶层与各段的键（供应商内部除外）的 description / default 来自 key-docs.ts（`annotate`）；说明跟随界面
@@ -8,7 +8,7 @@
  */
 type Schema = Record<string, unknown>;
 export declare const CONFIG_SCHEMA_FILE = "config.schema.json";
-export declare const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
+export declare const CONFIG_SCHEMA_ID = "https://github.com/AMA-Link/armadra-agent/config.schema.json";
 /** 生成 config.json 的 JSON Schema。 */
 export declare function buildConfigJsonSchema(): Schema;
 /** 写进文件的文本（2 空格缩进 + 换行结尾）。 */

package/dist/config/json-schema.js

@@ -1,6 +1,6 @@
 /**
  * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
- * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
+ * （docs/guides/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
  * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
  * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
  * 顶层与各段的键（供应商内部除外）的 description / default 来自 key-docs.ts（`annotate`）；说明跟随界面
@@ -15,7 +15,7 @@ import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CHECKPOINT_MODES, SANDBOX_ENABL
 import { AGENT_ID_PATTERN } from "./schema-w5.js";
 import { AGENTS_RESERVED_KEYS, SUBAGENT_BACKGROUND_MODES } from "./types-w5.js";
 export const CONFIG_SCHEMA_FILE = "config.schema.json";
-export const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
+export const CONFIG_SCHEMA_ID = "https://github.com/AMA-Link/armadra-agent/config.schema.json";
 const KNOWN_APIS = [
     "openai-completions",
     "openai-responses",

package/dist/config/schema-w5.d.ts

@@ -1,5 +1,5 @@
 /**
- * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ * 第五波配置键的校验（docs/history/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
  *
  * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
  * 未知字段是 warning。只校验形状；行为由各批次实现。

package/dist/config/schema-w5.js

@@ -1,5 +1,5 @@
 /**
- * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ * 第五波配置键的校验（docs/history/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
  *
  * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
  * 未知字段是 warning。只校验形状；行为由各批次实现。

package/dist/config/schema-w6.d.ts

@@ -1,5 +1,5 @@
 /**
- * 第六波配置键的校验（docs/wave6-plan.md §7；规则与 json-schema.ts 一一对应，json-schema.test.ts 守住）。[W6-C0]
+ * 第六波配置键的校验（docs/history/wave6-plan.md §7；规则与 json-schema.ts 一一对应，json-schema.test.ts 守住）。[W6-C0]
  *
  * 类型 / 取值错误是 error，未知字段是 warning。只校验形状；行为由各批次实现。
  */

package/dist/config/schema-w6.js

@@ -1,5 +1,5 @@
 /**
- * 第六波配置键的校验（docs/wave6-plan.md §7；规则与 json-schema.ts 一一对应，json-schema.test.ts 守住）。[W6-C0]
+ * 第六波配置键的校验（docs/history/wave6-plan.md §7；规则与 json-schema.ts 一一对应，json-schema.test.ts 守住）。[W6-C0]
  *
  * 类型 / 取值错误是 error，未知字段是 warning。只校验形状；行为由各批次实现。
  */

package/dist/config/settings-registry.d.ts

@@ -1,5 +1,5 @@
 /**
- * Settings registry (docs/wave6-plan.md §6.1, D24-D26). [W6-S]
+ * Settings registry (docs/history/wave6-plan.md §6.1, D24-D26). [W6-S]
  *
  * One row per key that the `/config` panel and `ama config set` treat as a scalar setting: group, apply
  * tier (now / next session / restart), whether it changes the cache prefix, project-level writability

package/dist/config/settings-registry.js

@@ -1,5 +1,5 @@
 /**
- * Settings registry (docs/wave6-plan.md §6.1, D24-D26). [W6-S]
+ * Settings registry (docs/history/wave6-plan.md §6.1, D24-D26). [W6-S]
  *
  * One row per key that the `/config` panel and `ama config set` treat as a scalar setting: group, apply
  * tier (now / next session / restart), whether it changes the cache prefix, project-level writability

package/dist/config/types-w5.d.ts

@@ -1,5 +1,5 @@
 /**
- * 第五波配置键的形状（docs/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
+ * 第五波配置键的形状（docs/history/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
  * 说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
  *
  * 层级：项目级只接受 `plan.bash`（只能更严）、`reminders`、`ui.statusLine`（随 `ui` 段）；其余只认
@@ -59,7 +59,7 @@ export interface AgentsConfig {
 }
 /** 取 `agents.<id>`（保留键返回 undefined）。 */
 export declare function agentEntry(agents: AgentsConfig | undefined, agentId: string): AgentEntryConfig | undefined;
-/** [W7-B2] 子 Agent 缺省前台还是后台（docs/agents-concurrency-plan.md §2.6）。 */
+/** [W7-B2] 子 Agent 缺省前台还是后台（docs/history/agents-concurrency-plan.md §2.6）。 */
 export declare const SUBAGENT_BACKGROUND_MODES: readonly ["auto", "always", "never"];
 export type SubagentBackgroundMode = (typeof SUBAGENT_BACKGROUND_MODES)[number];
 /** [W5-G] ama 自己的子会话。 */

package/dist/config/types-w5.js

@@ -1,5 +1,5 @@
 /**
- * 第五波配置键的形状（docs/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
+ * 第五波配置键的形状（docs/history/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
  * 说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
  *
  * 层级：项目级只接受 `plan.bash`（只能更严）、`reminders`、`ui.statusLine`（随 `ui` 段）；其余只认
@@ -18,7 +18,7 @@ export function agentEntry(agents, agentId) {
     const entry = agents[agentId];
     return typeof entry === "object" && !Array.isArray(entry) ? entry : undefined;
 }
-/** [W7-B2] 子 Agent 缺省前台还是后台（docs/agents-concurrency-plan.md §2.6）。 */
+/** [W7-B2] 子 Agent 缺省前台还是后台（docs/history/agents-concurrency-plan.md §2.6）。 */
 export const SUBAGENT_BACKGROUND_MODES = ["auto", "always", "never"];
 /** `models.enabled` 的一项：`provider/model[@channel]` 或 `provider/*`。 */
 export const MODELS_ENABLED_REF = /^[^/\s]+\/\S+$/;

package/dist/config/types-w6.d.ts

@@ -1,11 +1,11 @@
 /**
- * 第六波配置键的形状（docs/wave6-plan.md §7、§1.3、§3.1、§4.3、§4.4、§5.2）。[W6-C0] 契约文件：C0 只定形状、
+ * 第六波配置键的形状（docs/history/wave6-plan.md §7、§1.3、§3.1、§4.3、§4.4、§5.2）。[W6-C0] 契约文件：C0 只定形状、
  * 校验（schema-w6.ts）、说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
  *
  * 层级（merge.ts）：项目级可设 `ui.language`、`ui.agentBar`，`memory` 只接受 `enabled: false`；`ui.replyLanguage`、
  * `memory` 其余键、`auth` 只认用户级 / profile（项目级忽略并 warning）。
  */
-/** `ui.language`：auto 按 `LC_ALL` / `LC_MESSAGES` / `LANG` 判断，判断不出用 en（docs/i18n.md）。 */
+/** `ui.language`：auto 按 `LC_ALL` / `LC_MESSAGES` / `LANG` 判断，判断不出用 en（docs/guides/i18n.md）。 */
 export type LanguageSetting = "auto" | "zh" | "en";
 export declare const LANGUAGE_SETTINGS: readonly LanguageSetting[];
 /** [W6-A] Agent 栏：auto 有任务时显示；off 不显示（嵌入宿主缺省 off）。 */
@@ -27,7 +27,7 @@ export interface UiConfigW6 {
 export type MemoryScopeName = "user" | "project";
 export declare const MEMORY_SCOPES: readonly MemoryScopeName[];
 export declare const MEMORY_SUBAGENT_MODES: readonly ["off", "read"];
-/** [W6-M] `memory` 段（docs/wave6-plan.md §3.1）。缺省关闭；关闭时系统提示、工具表、请求体逐字节不变。 */
+/** [W6-M] `memory` 段（docs/history/wave6-plan.md §3.1）。缺省关闭；关闭时系统提示、工具表、请求体逐字节不变。 */
 export interface MemoryConfig {
     /** 总开关，缺省 false；项目级只能设为 false；`--memory` / `--no-memory`、`AMA_MEMORY=0|1` 覆盖。 */
     enabled?: boolean;
@@ -42,7 +42,7 @@ export interface MemoryConfig {
     /** 子会话：read（缺省，写命令执行层拒绝）/ off（view 也拒绝）。 */
     subagents?: (typeof MEMORY_SUBAGENT_MODES)[number];
 }
-/** [W6-O] ChatGPT 登录的两条路径（docs/wave6-plan.md §4.1、D13）。 */
+/** [W6-O] ChatGPT 登录的两条路径（docs/history/wave6-plan.md §4.1、D13）。 */
 export type ChatGptFlavor = "siwc" | "codex";
 export declare const CHATGPT_FLAVORS: readonly ChatGptFlavor[];
 /** [W6-O] `auth.chatgpt`：不含密钥；只认用户级 / profile。 */
@@ -85,7 +85,7 @@ export interface ApiKeyAuthEntry {
     baseUrl?: string;
 }
 /**
- * [W6-O] auth.json 里的 OAuth 条目（docs/wave6-plan.md §4.3、D15）。token 与 id_token 原文绝不进日志、错误、
+ * [W6-O] auth.json 里的 OAuth 条目（docs/history/wave6-plan.md §4.3、D15）。token 与 id_token 原文绝不进日志、错误、
  * 事件、会话；`describeAuthFile` 只给 `{ kind: "oauth", flavor, plan, expiresIn, needsLogin }`。
  */
 export interface OAuthAuthEntry {

package/dist/config/types-w6.js

@@ -1,5 +1,5 @@
 /**
- * 第六波配置键的形状（docs/wave6-plan.md §7、§1.3、§3.1、§4.3、§4.4、§5.2）。[W6-C0] 契约文件：C0 只定形状、
+ * 第六波配置键的形状（docs/history/wave6-plan.md §7、§1.3、§3.1、§4.3、§4.4、§5.2）。[W6-C0] 契约文件：C0 只定形状、
  * 校验（schema-w6.ts）、说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
  *
  * 层级（merge.ts）：项目级可设 `ui.language`、`ui.agentBar`，`memory` 只接受 `enabled: false`；`ui.replyLanguage`、

package/dist/config/types.d.ts

@@ -7,7 +7,7 @@
  * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
  * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
- * （W5-C0）第五波配置键（docs/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
+ * （W5-C0）第五波配置键（docs/history/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
  * `AmaConfig`），已有段加 `ui.statusLine`、`compaction.prune / pruneExclude`、profile `agentDirs`。
  */
 import type { WarmingMode } from "../ai/cache/types.js";
@@ -27,13 +27,13 @@ export declare const CONFIG_FILE_VERSION: 1;
  */
 export type ModelConfig = Partial<Omit<Model, "id" | "provider" | "channel" | "channels">> & {
     id: string;
-    /** 挂载的渠道名，第一个是首选；缺省 `defaultChannel`（docs/providers.md「渠道」）。 */
+    /** 挂载的渠道名，第一个是首选；缺省 `defaultChannel`（docs/guides/providers.md「渠道」）。 */
     channels?: string[];
     /** models.dev 条目 `provider/model`（显式匹配）；false 关闭 models.dev 补全。 */
     modelsDev?: string | false;
     /**
      * [ME-C0] 从内置目录继承模型固有属性：缺省按 id 别名自动匹配；`"provider/id"` 显式指定；false 关闭
-     * （docs/model-efficiency-plan.md D10，实现归 ME-D）。
+     * （docs/history/model-efficiency-plan.md D10，实现归 ME-D）。
      */
     catalog?: string | false;
 };
@@ -63,7 +63,7 @@ export interface ProviderConfig {
     headers?: Record<string, string>;
     compat?: ProviderCompat;
     requiresApiKey?: boolean;
-    /** 多渠道（docs/providers.md「渠道」）；不写时 `api` + `baseUrl` 是隐式的 `default` 渠道。 */
+    /** 多渠道（docs/guides/providers.md「渠道」）；不写时 `api` + `baseUrl` 是隐式的 `default` 渠道。 */
     channels?: Record<string, ChannelConfig>;
     /** 缺省 `channels` 的第一个键。 */
     defaultChannel?: string;
@@ -206,7 +206,7 @@ export declare const MIN_CONTEXT_BUDGET = 32768;
 export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 180000;
 export declare const CHECKPOINT_MODES: readonly CheckpointMode[];
 /**
- * 检查点（docs/rewind-plan.md §5）。环境变量 `AMA_CHECKPOINTS` 覆盖 `mode`；项目级只接受
+ * 检查点（docs/history/rewind-plan.md §5）。环境变量 `AMA_CHECKPOINTS` 覆盖 `mode`；项目级只接受
  * `mode: "off"` 与调小 `maxFileBytes`（只能收紧）。
  */
 export interface CheckpointsConfig {
@@ -222,7 +222,7 @@ export declare const SANDBOX_ENABLED_MODES: readonly ("auto" | "off")[];
 /** [S2] `sandbox.network` 的取值。 */
 export declare const SANDBOX_NETWORK_MODES: readonly ("deny" | "allow")[];
 /**
- * 操作系统级沙箱（docs/sandbox.md）。只认用户级 / profile；项目级只接受收紧的 `network: "deny"`，其余忽略
+ * 操作系统级沙箱（docs/guides/sandbox.md）。只认用户级 / profile；项目级只接受收紧的 `network: "deny"`，其余忽略
  * 并 warning。环境变量 `AMA_SANDBOX=off` 覆盖 `enabled`。
  */
 export interface SandboxConfig {

package/dist/config/types.js

@@ -7,7 +7,7 @@
  * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
  * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
- * （W5-C0）第五波配置键（docs/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
+ * （W5-C0）第五波配置键（docs/history/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
  * `AmaConfig`），已有段加 `ui.statusLine`、`compaction.prune / pruneExclude`、profile `agentDirs`。
  */
 export { AGENT_BAR_MODES, CHATGPT_FLAVORS, LANGUAGE_SETTINGS, MEMORY_SCOPES, MEMORY_SUBAGENT_MODES, apiKeyEntry, isOAuthEntry, } from "./types-w6.js";

package/dist/drivers/acp/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * ACP 客户端（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ * ACP 客户端（docs/history/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
  *

package/dist/drivers/acp/client.js

@@ -1,5 +1,5 @@
 /**
- * ACP 客户端（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ * ACP 客户端（docs/history/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
  *

package/dist/drivers/acp/driver.d.ts

@@ -1,5 +1,5 @@
 /**
- * AcpDriver：经 ACP 驱动外部 Agent（docs/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
+ * AcpDriver：经 ACP 驱动外部 Agent（docs/history/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
  *
  * open：起进程 → `initialize` → 续聊优先 `session/resume`（不回放），其次 `session/load`
  * （回放的历史通知在 open 期间丢弃），都不支持则新开并发 notice「已新开」→ 按 ama 模式
@@ -19,16 +19,36 @@ import { type DriverDeps } from "../base.js";
 import type { CatalogCandidate } from "../catalog.js";
 import { TurnCollector } from "../turn.js";
 import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
-import { type AcpAuthMethod, type AcpContentBlock, type AcpSessionConfigOption, type AcpSessionModeState, type AcpSessionUpdate } from "./types.js";
+import { type AcpAuthMethod, type AcpContentBlock, type AcpPromptUsage, type AcpSessionConfigOption, type AcpSessionModeState, type AcpSessionUpdate } from "./types.js";
 export declare function toAcpContent(blocks: readonly ContentBlock[], images: boolean): AcpContentBlock[];
 /** session/update → DriverEvent（用户消息回放、命令表等忽略）。 */
 export declare function pushAcpUpdate(update: AcpSessionUpdate, turn: TurnCollector): void;
+type TurnUsage = {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+};
+/**
+ * `session/prompt` 答复的 usage → 本回合用量（ama 口径：input 不含缓存命中）。
+ * - `previous`：Agent 报的是会话累计（如 Copilot）时，上一回合的原始累计值，相减得本回合；
+ * - 有 `totalTokens` 且它等于 input + output 时，input 含缓存命中部分，减去 cachedRead。
+ */
+export declare function acpTurnUsage(usage: AcpPromptUsage, previous?: AcpPromptUsage): TurnUsage;
 /** ama 模式 → 该 Agent 的模式 id（显式映射 > 同名）。 */
 export declare function pickModeId(mode: PermissionMode, candidate: CatalogCandidate, state: AcpSessionModeState | null | undefined): string | undefined;
 /** `configOptions` 里 category `mode` 的选择项（没有 `modes` 的 Agent 用它表达模式）。 */
 export declare function modeConfigOption(options: readonly AcpSessionConfigOption[] | null | undefined): AcpSessionConfigOption | undefined;
 /** 与 {@link pickModeId} 同一映射，在 mode 类配置项的可选值里找（分组的展开）。 */
 export declare function pickConfigModeValue(mode: PermissionMode, candidate: CatalogCandidate, option: AcpSessionConfigOption | undefined): string | undefined;
+/**
+ * `agents.<id>.model` / task 的 `model` → configOptions 里 category `model` 的可选值：先精确匹配值，
+ * 再不分大小写匹配值或名称，最后匹配 `provider/model` 的模型部分。没有就返回 undefined（用 Agent 的缺省）。
+ */
+export declare function pickModelValue(model: string, options: readonly AcpSessionConfigOption[] | null | undefined): {
+    configId: string;
+    value: string;
+    current: boolean;
+} | undefined;
 /** 开会话回 -32000 → `agent_auth_required`，列出 `initialize` 给的认证方法。 */
 export declare function authRequiredError(agentId: string, methods: readonly AcpAuthMethod[], command: readonly string[], cause: unknown): AmaError;
 export declare class AcpDriver implements AgentDriver {
@@ -40,3 +60,4 @@ export declare class AcpDriver implements AgentDriver {
     probe(): Promise<DriverProbe>;
     open(options: DriverOpenOptions): Promise<DriverSession>;
 }
+export {};

package/dist/drivers/acp/driver.js

@@ -1,5 +1,5 @@
 /**
- * AcpDriver：经 ACP 驱动外部 Agent（docs/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
+ * AcpDriver：经 ACP 驱动外部 Agent（docs/history/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
  *
  * open：起进程 → `initialize` → 续聊优先 `session/resume`（不回放），其次 `session/load`
  * （回放的历史通知在 open 期间丢弃），都不支持则新开并发 notice「已新开」→ 按 ama 模式
@@ -90,6 +90,34 @@ export function pushAcpUpdate(update, turn) {
             return;
     }
 }
+/**
+ * `session/prompt` 答复的 usage → 本回合用量（ama 口径：input 不含缓存命中）。
+ * - `previous`：Agent 报的是会话累计（如 Copilot）时，上一回合的原始累计值，相减得本回合；
+ * - 有 `totalTokens` 且它等于 input + output 时，input 含缓存命中部分，减去 cachedRead。
+ */
+export function acpTurnUsage(usage, previous) {
+    const diff = (key) => {
+        const now = usage[key];
+        if (now === undefined)
+            return undefined;
+        return previous === undefined ? now : Math.max(0, now - (previous[key] ?? 0));
+    };
+    const input = diff("inputTokens");
+    const output = diff("outputTokens");
+    const cacheRead = diff("cachedReadTokens");
+    const { totalTokens: total, inputTokens: rawIn = 0, outputTokens: rawOut = 0 } = usage;
+    const cached = usage.cachedReadTokens ?? 0;
+    const includesCache = total !== undefined &&
+        cached > 0 &&
+        Math.abs(total - (rawIn + rawOut)) < Math.abs(total - (rawIn + rawOut + cached));
+    return {
+        ...(input !== undefined
+            ? { input: includesCache ? Math.max(0, input - (cacheRead ?? 0)) : input }
+            : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(cacheRead !== undefined ? { cacheRead } : {}),
+    };
+}
 /** ama 模式在 Agent 那边想要的模式 id，按优先级（显式映射 > 同名）。 */
 function wantedModeIds(mode, candidate) {
     const wanted = [candidate.modes?.[mode] ?? mode];
@@ -113,6 +141,23 @@ export function pickConfigModeValue(mode, candidate, option) {
     const values = option.options.flatMap((o) => "options" in o ? o.options.map((x) => x.value) : [o.value]);
     return wantedModeIds(mode, candidate).find((id) => values.includes(id));
 }
+/**
+ * `agents.<id>.model` / task 的 `model` → configOptions 里 category `model` 的可选值：先精确匹配值，
+ * 再不分大小写匹配值或名称，最后匹配 `provider/model` 的模型部分。没有就返回 undefined（用 Agent 的缺省）。
+ */
+export function pickModelValue(model, options) {
+    const option = options?.find((o) => o.category === "model" && o.type === "select");
+    if (option === undefined)
+        return undefined;
+    const values = option.options.flatMap((o) => ("options" in o ? o.options : [o]));
+    const lower = model.toLowerCase();
+    const hit = values.find((v) => v.value === model) ??
+        values.find((v) => v.value.toLowerCase() === lower || v.name.toLowerCase() === lower) ??
+        values.find((v) => v.value.toLowerCase().split("/").at(-1) === lower);
+    return hit === undefined
+        ? undefined
+        : { configId: option.id, value: hit.value, current: option.currentValue === hit.value };
+}
 /** 一条认证方法给人看的样子：terminal 型附上要在终端里跑的命令。 */
 function authMethodText(method, command) {
     if (method.type !== "terminal")
@@ -181,6 +226,9 @@ class AcpDriverSession {
     notices = [];
     /** 本回合已发过 cancel。 */
     cancelling = false;
+    /** Agent 的 usage 是会话累计时，上一回合的原始值（{@link acpTurnUsage}）。 */
+    usageTotals;
+    cumulativeUsage = false;
     constructor(agentId, transport, deps) {
         this.agentId = agentId;
         this.transport = transport;
@@ -200,6 +248,7 @@ class AcpDriverSession {
             onProtocolError: (_line, reason) => this.deps.log?.("debug", `${this.agentId}: ${reason}`),
         });
         const signal = options.signal;
+        this.cumulativeUsage = candidate.acpUsage === "session";
         await this.client.initialize(signal);
         let opened;
         try {
@@ -228,6 +277,13 @@ class AcpDriverSession {
         else if (modes != null || modeOption !== undefined) {
             this.notices.push(msg().drivers.agent.noMatchingMode(this.agentId, options.mode));
         }
+        if (options.model !== undefined) {
+            const model = pickModelValue(options.model, opened.configOptions);
+            if (model === undefined)
+                this.notices.push(msg().drivers.agent.noMatchingModel(this.agentId, options.model));
+            else if (!model.current)
+                await this.client.setConfigOption(this.id, model.configId, model.value);
+        }
     }
     /** 续聊优先 resume（不回放），其次 load（回放丢弃），都不行就新开；设好 `this.id`。 */
     async openSession(options) {
@@ -291,11 +347,9 @@ class AcpDriverSession {
             });
             const usage = result.usage;
             if (usage != null) {
-                turn.mergeUsage({
-                    ...(usage.inputTokens !== undefined ? { input: usage.inputTokens } : {}),
-                    ...(usage.outputTokens !== undefined ? { output: usage.outputTokens } : {}),
-                    ...(usage.cachedReadTokens !== undefined ? { cacheRead: usage.cachedReadTokens } : {}),
-                });
+                turn.mergeUsage(acpTurnUsage(usage, this.cumulativeUsage ? (this.usageTotals ?? {}) : undefined));
+                if (this.cumulativeUsage)
+                    this.usageTotals = usage;
             }
             return turn.result(result.stopReason);
         }

package/dist/drivers/acp/testing/fake-agent.d.ts

@@ -1,5 +1,5 @@
 /**
- * 黄金记录用的假 ACP Agent（docs/wave5-plan.md §5.1、§5.7）。[W5-E]
+ * 黄金记录用的假 ACP Agent（docs/history/wave5-plan.md §5.1、§5.7）。[W5-E]
  *
  * 零依赖、不联网、不碰文件系统；行为由提示文本里的标记决定，供 ama 自己的测试与 Armadra 复用
  * （`@armadra/agent/acp` 导出 {@link runFakeAcpAgent} 与可执行入口路径）：

package/dist/drivers/acp/testing/fake-agent.js

@@ -1,5 +1,5 @@
 /**
- * 黄金记录用的假 ACP Agent（docs/wave5-plan.md §5.1、§5.7）。[W5-E]
+ * 黄金记录用的假 ACP Agent（docs/history/wave5-plan.md §5.1、§5.7）。[W5-E]
  *
  * 零依赖、不联网、不碰文件系统；行为由提示文本里的标记决定，供 ama 自己的测试与 Armadra 复用
  * （`@armadra/agent/acp` 导出 {@link runFakeAcpAgent} 与可执行入口路径）：

package/dist/drivers/acp/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ * ACP（Agent Client Protocol）v1 的子集类型（docs/history/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
  * `initialize`、`authenticate`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、

package/dist/drivers/acp/types.js

@@ -1,5 +1,5 @@
 /**
- * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ * ACP（Agent Client Protocol）v1 的子集类型（docs/history/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
  * `initialize`、`authenticate`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、

package/dist/drivers/agents.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的入口（W5-G 的 `task(agent=…)` 经它拿 runner，docs/wave5-plan.md §5.5、§7.6、D13、D17）。[W5-E]
+ * 外部 Agent 的入口（W5-G 的 `task(agent=…)` 经它拿 runner，docs/history/wave5-plan.md §5.5、§7.6、D13、D17）。[W5-E]
  *
  * - `resolve("claude" | "codex" | "acp:<program>" | 表里的 id)` → {@link ProcessRunner}（按驱动表候选链，
  *   每次 `start` 时按模式与安装情况选驱动）；同一 spec 复用同一个 runner。

package/dist/drivers/agents.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的入口（W5-G 的 `task(agent=…)` 经它拿 runner，docs/wave5-plan.md §5.5、§7.6、D13、D17）。[W5-E]
+ * 外部 Agent 的入口（W5-G 的 `task(agent=…)` 经它拿 runner，docs/history/wave5-plan.md §5.5、§7.6、D13、D17）。[W5-E]
  *
  * - `resolve("claude" | "codex" | "acp:<program>" | 表里的 id)` → {@link ProcessRunner}（按驱动表候选链，
  *   每次 `start` 时按模式与安装情况选驱动）；同一 spec 复用同一个 runner。
@@ -17,6 +17,7 @@ import { HostRunnerRegistry } from "./host-runners.js";
 import { ClaudeStreamDriver } from "./native/claude-stream.js";
 import { CodexAppServerDriver } from "./native/codex-app-server.js";
 import { OneshotDriver } from "./native/oneshot.js";
+import { PiRpcDriver } from "./native/pi-rpc.js";
 import { PidRegistry, pidsFile } from "./pids.js";
 import { poolFromConfig } from "./pool.js";
 import { ProgramProbe } from "./probe.js";
@@ -33,6 +34,8 @@ export function createDriver(agentId, candidate, deps) {
             return new ClaudeStreamDriver(agentId, candidate, deps);
         case "codex-app-server":
             return new CodexAppServerDriver(agentId, candidate, deps);
+        case "pi-rpc":
+            return new PiRpcDriver(agentId, candidate, deps);
         case "oneshot":
             return new OneshotDriver(agentId, candidate, deps);
     }

package/dist/drivers/base.d.ts

@@ -1,5 +1,5 @@
 /**
- * 各驱动共用的依赖与看门狗（docs/wave5-plan.md §5.4）。[W5-E]
+ * 各驱动共用的依赖与看门狗（docs/history/wave5-plan.md §5.4）。[W5-E]
  */
 import type { PermissionMode } from "../permissions/types.js";
 import type { CatalogCandidate } from "./catalog.js";

package/dist/drivers/base.js

@@ -1,5 +1,5 @@
 /**
- * 各驱动共用的依赖与看门狗（docs/wave5-plan.md §5.4）。[W5-E]
+ * 各驱动共用的依赖与看门狗（docs/history/wave5-plan.md §5.4）。[W5-E]
  */
 import { candidateCapabilities } from "./catalog.js";
 import { versionSatisfies } from "./probe.js";