@armadra/agent 0.8.0 → 0.9.0

package/dist/ai/providers/models-dev-snapshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * 入库的 models.dev 快照（docs/wave5-plan.md §2.1、docs/providers.md「模型元数据」）。
+ * 入库的 models.dev 快照（docs/history/wave5-plan.md §2.1、docs/guides/providers.md「模型元数据」）。
  *
  * `models-dev/*.json` 由 `scripts/update-models-dev.mjs` 生成并内联进 `models-dev-data.ts`（单 bundle，
  * 运行时不读 JSON 文件、不联网）。本模块解析内联数据，并提供与脚本同一口径的 `buildSnapshot()`

package/dist/ai/providers/models-dev-snapshot.js

@@ -1,5 +1,5 @@
 /**
- * 入库的 models.dev 快照（docs/wave5-plan.md §2.1、docs/providers.md「模型元数据」）。
+ * 入库的 models.dev 快照（docs/history/wave5-plan.md §2.1、docs/guides/providers.md「模型元数据」）。
  *
  * `models-dev/*.json` 由 `scripts/update-models-dev.mjs` 生成并内联进 `models-dev-data.ts`（单 bundle，
  * 运行时不读 JSON 文件、不联网）。本模块解析内联数据，并提供与脚本同一口径的 `buildSnapshot()`

package/dist/ai/providers/models-dev.d.ts

@@ -1,5 +1,5 @@
 /**
- * models.dev 模型元数据（docs/providers.md「模型元数据：models.dev」）：裁剪、索引、匹配、映射。
+ * models.dev 模型元数据（docs/guides/providers.md「模型元数据：models.dev」）：裁剪、索引、匹配、映射。
  *
  * 数据源 `https://models.dev/api.json` 是「供应商 → 模型」两层表，同一个模型 id 会在几十家转售商下
  * 重复出现且取值不一。`ModelsDevIndex.match()` 按文档里的顺序挑一条：显式 `provider/model` →
@@ -18,7 +18,7 @@ export interface ModelsDevPrices {
 }
 /**
  * 用到的模型字段（models.dev 原名）；其余裁剪时丢掉。快照只多存 family / knowledge /
- * release_date / limit.input / 价格档位 / interleaved / status（docs/wave5-plan.md §2.1）。
+ * release_date / limit.input / 价格档位 / interleaved / status（docs/history/wave5-plan.md §2.1）。
  */
 export interface ModelsDevModel {
     id: string;
@@ -104,7 +104,7 @@ export interface ModelsDevFields {
  * 缺的缓存价记 0（与目录一贯写法一致：没有单独计价）。
  */
 export type ModelsDevMapping = "custom" | "catalog";
-/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/wave5-plan.md §2.1）。 */
+/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/history/wave5-plan.md §2.1）。 */
 export declare function keepForSnapshot(raw: unknown): boolean;
 /** 裁剪一家供应商；`keep` 给出时只留它放行的模型（模型 id 按字典序）。 */
 export declare function trimProvider(providerId: string, provider: Record<string, unknown>, keep?: (modelId: string, raw: unknown) => boolean): ModelsDevProvider;
@@ -131,7 +131,7 @@ export declare class ModelsDevIndex {
     match(id: string, explicit?: string): ModelsDevMatch | undefined;
     private choose;
 }
-/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md「模型元数据」）。 */
+/** models.dev 条目 → ama Model 字段（规则见 docs/guides/providers.md「模型元数据」）。 */
 export declare function modelsDevFields(model: ModelsDevModel, mapping?: ModelsDevMapping): ModelsDevFields;
 /** 可由 models.dev 补的 Model 字段（展示来源用）。 */
 export declare const ENRICHABLE_FIELDS: readonly ["contextWindow", "maxTokens", "input", "reasoning", "cost"];

package/dist/ai/providers/models-dev.js

@@ -1,5 +1,5 @@
 /**
- * models.dev 模型元数据（docs/providers.md「模型元数据：models.dev」）：裁剪、索引、匹配、映射。
+ * models.dev 模型元数据（docs/guides/providers.md「模型元数据：models.dev」）：裁剪、索引、匹配、映射。
  *
  * 数据源 `https://models.dev/api.json` 是「供应商 → 模型」两层表，同一个模型 id 会在几十家转售商下
  * 重复出现且取值不一。`ModelsDevIndex.match()` 按文档里的顺序挑一条：显式 `provider/model` →
@@ -136,7 +136,7 @@ function trimModel(id, raw) {
         out.interleaved = { field: interleaved["field"] };
     return out;
 }
-/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/wave5-plan.md §2.1）。 */
+/** 快照过滤：丢 deprecated、输出不含文本、上下文为 0 / 缺失、tool_call:false（docs/history/wave5-plan.md §2.1）。 */
 export function keepForSnapshot(raw) {
     if (!isRecord(raw))
         return false;
@@ -337,7 +337,7 @@ function toCost(p, mapping) {
         cacheWrite: p.cache_write ?? missing,
     };
 }
-/** models.dev 条目 → ama Model 字段（规则见 docs/providers.md「模型元数据」）。 */
+/** models.dev 条目 → ama Model 字段（规则见 docs/guides/providers.md「模型元数据」）。 */
 export function modelsDevFields(model, mapping = "custom") {
     const out = {};
     if (model.name !== undefined)

package/dist/ai/types.d.ts

@@ -15,7 +15,7 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
- * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ * - [W5-C0] 第五波（docs/history/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
  *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
  *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
  *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /
@@ -345,7 +345,7 @@ export interface Model {
     /** 发布状态；正式版不填（deprecated 的模型在快照里已过滤）。 */
     status?: "beta";
 }
-/** 物化后的渠道（docs/providers.md「渠道」）；key 不在这里，经 `resolveApiKey(provider, channel)` 取。 */
+/** 物化后的渠道（docs/guides/providers.md「渠道」）；key 不在这里，经 `resolveApiKey(provider, channel)` 取。 */
 export interface ProviderChannel {
     name: string;
     api: Api;

package/dist/ai/types.js

@@ -15,7 +15,7 @@
  * - [W3-C0] 第三波 §1.3 的五个缓存兼容开关单列为 `PromptCacheCompat`（各协议共用），只并入
  *   `ProviderCompat`（全部可选），不改各协议 compat 接口——`detectCompat` 的返回形状不变，
  *   缺省值由 C1a 在协议层按端点推断。
- * - [W5-C0] 第五波（docs/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
+ * - [W5-C0] 第五波（docs/history/wave5-plan.md §2.1、§3.1）：`Model` 加 models.dev 元数据字段
  *   （`family / knowledge / releaseDate / inputLimit / status`）；`AnthropicMessagesCompat` 加
  *   `sendInterleavedThinkingBeta / sendCacheControl`、`OpenAIResponsesCompat` 加
  *   `explicitCacheField`，全部可选（缺省由 W5-M2 的主机推断表给出）；`ProviderData.channels /

package/dist/auth/chatgpt/cli.d.ts

@@ -1,5 +1,5 @@
 /**
- * `ama auth login | logout | status chatgpt`（docs/wave6-plan.md §4.2、D16）。[W6-O]
+ * `ama auth login | logout | status chatgpt`（docs/history/wave6-plan.md §4.2、D16）。[W6-O]
  *
  * - login：flavor 取 `--flavor` > 用户级 `auth.chatgpt.flavor` > siwc；`--paste` / `--device`（只 codex）/ 缺省
  *   浏览器；codex 首次在 TTY 下一次性确认「非官方、仅个人使用」（非 TTY 需 `--yes`），`acknowledgedAt` 入条目；

package/dist/auth/chatgpt/cli.js

@@ -1,5 +1,5 @@
 /**
- * `ama auth login | logout | status chatgpt`（docs/wave6-plan.md §4.2、D16）。[W6-O]
+ * `ama auth login | logout | status chatgpt`（docs/history/wave6-plan.md §4.2、D16）。[W6-O]
  *
  * - login：flavor 取 `--flavor` > 用户级 `auth.chatgpt.flavor` > siwc；`--paste` / `--device`（只 codex）/ 缺省
  *   浏览器；codex 首次在 TTY 下一次性确认「非官方、仅个人使用」（非 TTY 需 `--yes`），`acknowledgedAt` 入条目；

package/dist/auth/chatgpt/host-id.d.ts

@@ -1,5 +1,5 @@
 /**
- * SIWC 的 `ext_agent_host_id`（docs/wave6-plan.md D16）：每个安装稳定不变，存
+ * SIWC 的 `ext_agent_host_id`（docs/history/wave6-plan.md D16）：每个安装稳定不变，存
  * `<dataDir>/chatgpt-host.json`（0600，按安装、不随 dotfiles 同步），形如 `urn:uuid:…`。[W6-O]
  */
 export declare const HOST_ID_FILE = "chatgpt-host.json";

package/dist/auth/chatgpt/host-id.js

@@ -1,5 +1,5 @@
 /**
- * SIWC 的 `ext_agent_host_id`（docs/wave6-plan.md D16）：每个安装稳定不变，存
+ * SIWC 的 `ext_agent_host_id`（docs/history/wave6-plan.md D16）：每个安装稳定不变，存
  * `<dataDir>/chatgpt-host.json`（0600，按安装、不随 dotfiles 同步），形如 `urn:uuid:…`。[W6-O]
  */
 import { randomUUID } from "node:crypto";

package/dist/auth/chatgpt/login.d.ts

@@ -1,5 +1,5 @@
 /**
- * ChatGPT 登录 / 登出编排（docs/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
+ * ChatGPT 登录 / 登出编排（docs/history/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
  *
  * 登录：预设 → 授权码（browser / paste / device）→ 换 token（表单编码；SIWC 带 `resource`，client id 用
  * 回调带回的签发 id）→ 校验（SIWC：JWKS 验签 iss / aud / nonce / exp + 授予 scope 含

package/dist/auth/chatgpt/login.js

@@ -1,5 +1,5 @@
 /**
- * ChatGPT 登录 / 登出编排（docs/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
+ * ChatGPT 登录 / 登出编排（docs/history/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
  *
  * 登录：预设 → 授权码（browser / paste / device）→ 换 token（表单编码；SIWC 带 `resource`，client id 用
  * 回调带回的签发 id）→ 校验（SIWC：JWKS 验签 iss / aud / nonce / exp + 授予 scope 含

package/dist/auth/chatgpt/presets.d.ts

@@ -1,5 +1,5 @@
 /**
- * ChatGPT 登录预设表（docs/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
+ * ChatGPT 登录预设表（docs/history/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
  *
  * 两条路径共用 PKCE / 回调 / 存储 / 锁 / 配额框架，差异全部在这张表里：
  * - `siwc`（缺省，官方动态注册）：`/api/accounts/*`，首次 `client_id=dynamic_agent_client`，回调带回签发的

package/dist/auth/chatgpt/presets.js

@@ -1,5 +1,5 @@
 /**
- * ChatGPT 登录预设表（docs/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
+ * ChatGPT 登录预设表（docs/history/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
  *
  * 两条路径共用 PKCE / 回调 / 存储 / 锁 / 配额框架，差异全部在这张表里：
  * - `siwc`（缺省，官方动态注册）：`/api/accounts/*`，首次 `client_id=dynamic_agent_client`，回调带回签发的

package/dist/auth/oauth/callback-server.d.ts

@@ -1,5 +1,5 @@
 /**
- * 本地 OAuth 回调服务（docs/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
+ * 本地 OAuth 回调服务（docs/history/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
  *
  * - 只监听 `127.0.0.1`；端口按 `ports` 依次尝试（0 = 任意空闲端口），被占用就试下一个；全被占用报
  *   `oauth_ports_busy`（**不**像别的客户端那样发 `/cancel` 抢占他人的监听）；

package/dist/auth/oauth/callback-server.js

@@ -1,5 +1,5 @@
 /**
- * 本地 OAuth 回调服务（docs/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
+ * 本地 OAuth 回调服务（docs/history/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
  *
  * - 只监听 `127.0.0.1`；端口按 `ports` 依次尝试（0 = 任意空闲端口），被占用就试下一个；全被占用报
  *   `oauth_ports_busy`（**不**像别的客户端那样发 `/cancel` 抢占他人的监听）；

package/dist/auth/oauth/flows.d.ts

@@ -1,5 +1,5 @@
 /**
- * 授权流程（docs/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
+ * 授权流程（docs/history/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
  *
  * 三种拿授权码的方式，产出同一个 `AuthorizationResult`，由各预设的登录模块去换 token：
  * - `browser`：本地回调服务 + 打开浏览器（打不开就只给 URL）；

package/dist/auth/oauth/flows.js

@@ -1,5 +1,5 @@
 /**
- * 授权流程（docs/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
+ * 授权流程（docs/history/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
  *
  * 三种拿授权码的方式，产出同一个 `AuthorizationResult`，由各预设的登录模块去换 token：
  * - `browser`：本地回调服务 + 打开浏览器（打不开就只给 URL）；

package/dist/auth/oauth/oidc.d.ts

@@ -1,5 +1,5 @@
 /**
- * OIDC discovery、JWKS 与 id_token 校验（docs/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
+ * OIDC discovery、JWKS 与 id_token 校验（docs/history/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
  *
  * SIWC 必须：JWKS 验签 + `iss` = issuer、`aud` 含签发的 client id、`nonce` = 本次登录的、`exp` 未过
  * （允许 60 s 时钟偏差）。discovery 与 JWKS 每进程按 issuer 缓存一次。

package/dist/auth/oauth/oidc.js

@@ -1,5 +1,5 @@
 /**
- * OIDC discovery、JWKS 与 id_token 校验（docs/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
+ * OIDC discovery、JWKS 与 id_token 校验（docs/history/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
  *
  * SIWC 必须：JWKS 验签 + `iss` = issuer、`aud` 含签发的 client id、`nonce` = 本次登录的、`exp` 未过
  * （允许 60 s 时钟偏差）。discovery 与 JWKS 每进程按 issuer 缓存一次。

package/dist/auth/oauth/pkce.d.ts

@@ -1,5 +1,5 @@
 /**
- * PKCE（RFC 7636，S256）与随机串（docs/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
+ * PKCE（RFC 7636，S256）与随机串（docs/history/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
  *
  * verifier 32 字节随机数的 base64url（43 字符），challenge = base64url(SHA-256(verifier)) 无填充；
  * `state` / `nonce` 同样 32 字节随机。只用 `node:crypto`。

package/dist/auth/oauth/pkce.js

@@ -1,5 +1,5 @@
 /**
- * PKCE（RFC 7636，S256）与随机串（docs/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
+ * PKCE（RFC 7636，S256）与随机串（docs/history/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
  *
  * verifier 32 字节随机数的 base64url（43 字符），challenge = base64url(SHA-256(verifier)) 无填充；
  * `state` / `nonce` 同样 32 字节随机。只用 `node:crypto`。

package/dist/auth/oauth/refresh.d.ts

@@ -1,5 +1,5 @@
 /**
- * OAuth access token 的取用与刷新（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ * OAuth access token 的取用与刷新（docs/history/wave6-plan.md §4.3、D15）。[W6-O]
  *
  * - 触发：`expiresAt − now < 5 min`，或协议层 401 后 `force`；
  * - 进程内：同一 (auth.json, 供应商) 共用一个刷新 Promise；

package/dist/auth/oauth/refresh.js

@@ -1,5 +1,5 @@
 /**
- * OAuth access token 的取用与刷新（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ * OAuth access token 的取用与刷新（docs/history/wave6-plan.md §4.3、D15）。[W6-O]
  *
  * - 触发：`expiresAt − now < 5 min`，或协议层 401 后 `force`；
  * - 进程内：同一 (auth.json, 供应商) 共用一个刷新 Promise；

package/dist/auth/oauth/token-client.d.ts

@@ -1,7 +1,7 @@
 /**
  * OAuth 端点的 HTTP 调用（token 交换 / 刷新 / 撤销 / discovery）。[W6-O]
  *
- * 日志红线（docs/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
+ * 日志红线（docs/history/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
  * 原文、请求参数、code 或任何 token。
  */
 import { AmaError } from "../../errors.js";

package/dist/auth/oauth/token-client.js

@@ -1,7 +1,7 @@
 /**
  * OAuth 端点的 HTTP 调用（token 交换 / 刷新 / 撤销 / discovery）。[W6-O]
  *
- * 日志红线（docs/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
+ * 日志红线（docs/history/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
  * 原文、请求参数、code 或任何 token。
  */
 import { AmaError } from "../../errors.js";

package/dist/auth/oauth/token-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * OAuth 条目的存取与跨进程刷新锁（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ * OAuth 条目的存取与跨进程刷新锁（docs/history/wave6-plan.md §4.3、D15）。[W6-O]
  *
  * - 读：每次都从磁盘读（绕过 `ApiKeyResolver.fileCache`，长会话才能看到别的进程刷新后的 token）；文件不存在 /
  *   坏掉 / 不是 oauth 条目 → undefined；

package/dist/auth/oauth/token-store.js

@@ -1,5 +1,5 @@
 /**
- * OAuth 条目的存取与跨进程刷新锁（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ * OAuth 条目的存取与跨进程刷新锁（docs/history/wave6-plan.md §4.3、D15）。[W6-O]
  *
  * - 读：每次都从磁盘读（绕过 `ApiKeyResolver.fileCache`，长会话才能看到别的进程刷新后的 token）；文件不存在 /
  *   坏掉 / 不是 oauth 条目 → undefined；

package/dist/auth/testing/fake-oauth.d.ts

@@ -1,5 +1,5 @@
 /**
- * 测试用 fake OAuth / ChatGPT 后端（docs/wave6-plan.md §4.6）。`node:http` 随机端口；不进 bundle。
+ * 测试用 fake OAuth / ChatGPT 后端（docs/history/wave6-plan.md §4.6）。`node:http` 随机端口；不进 bundle。
  *
  * OAuth：authorize（记参数、302 回 redirect_uri；SIWC 注册时带签发的 client_id 与 scope）、token（校验 PKCE；
  * 授权码 / 刷新；刷新轮换，旧 refresh token 再用 → `refresh_token_reused`）、deviceauth、discovery + JWKS

package/dist/auth/testing/fake-oauth.js

@@ -1,5 +1,5 @@
 /**
- * 测试用 fake OAuth / ChatGPT 后端（docs/wave6-plan.md §4.6）。`node:http` 随机端口；不进 bundle。
+ * 测试用 fake OAuth / ChatGPT 后端（docs/history/wave6-plan.md §4.6）。`node:http` 随机端口；不进 bundle。
  *
  * OAuth：authorize（记参数、302 回 redirect_uri；SIWC 注册时带签发的 client_id 与 scope）、token（校验 PKCE；
  * 授权码 / 刷新；刷新轮换，旧 refresh token 再用 → `refresh_token_reused`）、deviceauth、discovery + JWKS