@armadra/agent 0.8.0 → 0.8.1

package/dist/permissions/pipeline.js

@@ -25,7 +25,7 @@
  * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
  * 记忆只作用于第 ③ 步模式产生的 ask（auto 里只作用于规则层之后）。
  *
- * [S2] bash 沙箱（docs/permissions.md「判定顺序」）：default / auto-edit 下，bash 调用若将在 OS 沙箱内
+ * [S2] bash 沙箱（docs/guides/permissions.md「判定顺序」）：default / auto-edit 下，bash 调用若将在 OS 沙箱内
  * 运行且沙箱拒绝网络、没请求 `sandbox: false`、命令文本不碰机密路径、嵌套不超深，第 ③ 步的 ask 变
  * allow（`sandboxed: true`）；①② 与 Hook ask 照旧优先。auto 下沙箱不直接放行，只作为分类器输入；
  * 请求 `sandbox: false` 越出沙箱时规则层询问（allow 规则 / Hook allow / 会话记忆仍可放行）。
@@ -72,7 +72,7 @@ export const PLAN_MODE_MESSAGE = "Plan mode is active: write/execute tools are d
 /** [W5-F] plan 下 `todo set / update` 的拒绝说明（计划与清单分开，避免跳过审批）。 */
 export const PLAN_TODO_MESSAGE = "Plan mode is active: the todo list is created from the approved plan. Write the steps in a <proposed_plan> block instead.";
 /**
- * [W5-F] plan 模式第 ③ 步（输入可见，docs/wave5-plan.md §6.2）：
+ * [W5-F] plan 模式第 ③ 步（输入可见，docs/history/wave5-plan.md §6.2）：
  * read 放行（`todo` 只放行 get）；bash 按 `plan.bash`（readonly：只读子集放行其余拒绝；ask：其余询问；
  * deny：全拒）；task 放行（子会话共用同一管线，同样处在 plan）；其余 write / execute 拒绝。
  * 返回 undefined = 交给通常的模式真值表。

package/dist/permissions/protected.d.ts

@@ -1,5 +1,5 @@
 /**
- * auto 模式规则层的受保护路径（§7.4，docs/permissions.md「规则层」）。
+ * auto 模式规则层的受保护路径（§7.4，docs/guides/permissions.md「规则层」）。
  *
  * - **机密路径**（读写都询问）：`.env` / `.env.*`（`.example` / `.sample` / `.template` / `.dist` 除外）、
  *   `*.env`、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.config/gcloud/`、

package/dist/permissions/protected.js

@@ -1,5 +1,5 @@
 /**
- * auto 模式规则层的受保护路径（§7.4，docs/permissions.md「规则层」）。
+ * auto 模式规则层的受保护路径（§7.4，docs/guides/permissions.md「规则层」）。
  *
  * - **机密路径**（读写都询问）：`.env` / `.env.*`（`.example` / `.sample` / `.template` / `.dist` 除外）、
  *   `*.env`、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.config/gcloud/`、

package/dist/permissions/readonly-bash.d.ts

@@ -1,5 +1,5 @@
 /**
- * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/wave5-plan.md §6.2、D21）。[W5-F]
+ * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/history/wave5-plan.md §6.2、D21）。[W5-F]
  *
  * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
  * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：

package/dist/permissions/readonly-bash.js

@@ -1,5 +1,5 @@
 /**
- * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/wave5-plan.md §6.2、D21）。[W5-F]
+ * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/history/wave5-plan.md §6.2、D21）。[W5-F]
  *
  * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
  * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：

package/dist/permissions/types.d.ts

@@ -75,7 +75,7 @@ export interface ApprovalRequestContext {
     /** [W5-C0] 子 Agent 任务 id（对话框标注 `[task:<agent>]`）。 */
     taskId?: string;
     /**
-     * [W5-C0] 来自外部 Agent 的权限请求（docs/wave5-plan.md §5.3）：只走 broker 链（宿主 → UI →
+     * [W5-C0] 来自外部 Agent 的权限请求（docs/history/wave5-plan.md §5.3）：只走 broker 链（宿主 → UI →
      * 无人值守拒绝），auto 分类器与模型都不参与；RPC `permission_request` 原样带出。
      */
     origin?: ExternalPermissionOrigin;
@@ -171,7 +171,7 @@ export interface PermissionVerdict {
      */
     classify?: boolean;
     /**
-     * [S2] 这次 bash 调用将经 OS 沙箱运行（docs/sandbox.md「第二阶段」）。default / auto-edit 下因此免审批时
+     * [S2] 这次 bash 调用将经 OS 沙箱运行（docs/guides/sandbox.md「第二阶段」）。default / auto-edit 下因此免审批时
      * 为真；auto 下随 `classify` 一起交给分类器作为输入。
      */
     sandboxed?: boolean;

package/dist/plan/done-markers.d.ts

@@ -1,5 +1,5 @@
 /**
- * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
+ * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/guides/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
  * 批准计划的交接消息请模型每完成一步在回复里单独一行写 `[DONE:S1]`；ama 在回合结束时读这些标记，
  * 把计划生成的待办（`planStep`）标为 done、下一个未完成项转 in_progress，照常落 `ama.todo` 与发
  * `todo_updated`，界面与 RPC 的进度显示不依赖 todo 工具。

package/dist/plan/done-markers.js

@@ -1,5 +1,5 @@
 /**
- * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
+ * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/guides/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
  * 批准计划的交接消息请模型每完成一步在回复里单独一行写 `[DONE:S1]`；ama 在回合结束时读这些标记，
  * 把计划生成的待办（`planStep`）标为 done、下一个未完成项转 in_progress，照常落 `ama.todo` 与发
  * `todo_updated`，界面与 RPC 的进度显示不依赖 todo 工具。

package/dist/plan/extract.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<proposed_plan>` 块的提取与步骤解析（docs/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
+ * `<proposed_plan>` 块的提取与步骤解析（docs/history/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
  *
  * - 只认开、闭标签**各占一行**（允许行首尾空白）、且不在代码围栏（``` / ~~~）内的块；
  *   不闭合的块忽略；多个完整块取最后一个。

package/dist/plan/extract.js

@@ -1,5 +1,5 @@
 /**
- * `<proposed_plan>` 块的提取与步骤解析（docs/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
+ * `<proposed_plan>` 块的提取与步骤解析（docs/history/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
  *
  * - 只认开、闭标签**各占一行**（允许行首尾空白）、且不在代码围栏（``` / ~~~）内的块；
  *   不闭合的块忽略；多个完整块取最后一个。

package/dist/plan/prompts.d.ts

@@ -1,5 +1,5 @@
 /**
- * plan 模式注入给模型的文本（docs/wave5-plan.md §6.2、D18）。[W5-F]
+ * plan 模式注入给模型的文本（docs/history/wave5-plan.md §6.2、D18）。[W5-F]
  *
  * 全部以 `custom_message`（`display:false`）追加在尾部，投影成 user 消息，不碰 system 节与工具表
  * （design §9.1）。文本是给模型看的，用英文；界面文案不在这里。

package/dist/plan/prompts.js

@@ -1,5 +1,5 @@
 /**
- * plan 模式注入给模型的文本（docs/wave5-plan.md §6.2、D18）。[W5-F]
+ * plan 模式注入给模型的文本（docs/history/wave5-plan.md §6.2、D18）。[W5-F]
  *
  * 全部以 `custom_message`（`display:false`）追加在尾部，投影成 user 消息，不碰 system 节与工具表
  * （design §9.1）。文本是给模型看的，用英文；界面文案不在这里。

package/dist/plan/store.d.ts

@@ -1,5 +1,5 @@
 /**
- * 计划的持久化：会话条目的读取与计划文件导出（docs/wave5-plan.md §6.3）。[W5-F]
+ * 计划的持久化：会话条目的读取与计划文件导出（docs/history/wave5-plan.md §6.3）。[W5-F]
  *
  * - 权威数据在会话 JSONL：`custom{ama.plan}`（只追加：状态变化再记一条，同 id 取分支上最后一条）、
  *   `custom{ama.plan_state}`（进入 / 退出 plan）。

package/dist/plan/store.js

@@ -1,5 +1,5 @@
 /**
- * 计划的持久化：会话条目的读取与计划文件导出（docs/wave5-plan.md §6.3）。[W5-F]
+ * 计划的持久化：会话条目的读取与计划文件导出（docs/history/wave5-plan.md §6.3）。[W5-F]
  *
  * - 权威数据在会话 JSONL：`custom{ama.plan}`（只追加：状态变化再记一条，同 id 取分支上最后一条）、
  *   `custom{ama.plan_state}`（进入 / 退出 plan）。

package/dist/rpc.d.ts

@@ -12,14 +12,14 @@
  * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
  *   附最新 usage）；stream-json 输出同一形状。
  * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
- * - [W5-C0] 第五波（docs/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
+ * - [W5-C0] 第五波（docs/history/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
  *   get_tasks / get_agents`（返回形状见 `RpcW5Results`），客户端能力 `plans`（声明后计划审批交客户端）；
  *   新事件由 `SessionEvent` 派生自动包含。命令实现归 W5-F（C0 时返回 `not_implemented`），
  *   `RPC_PROTOCOL_VERSION` 不变。
- * - [W6-C0] 第六波（docs/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
+ * - [W6-C0] 第六波（docs/history/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
  *   `RpcW6Results`，W6-T2 实现，之前回 `not_implemented`）；事件 `quota_update`；`permission_request.context`
  *   可带 `toolCallId`；`keySource` 可为 `oauth`。`RPC_PROTOCOL_VERSION` 不变。
- * - [W7-B2] 后台子 Agent（docs/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
+ * - [W7-B2] 后台子 Agent（docs/history/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
  *   `RpcW7Results`（无 taskId = 全部前台运行中任务；对已结束 / 已在后台的任务回空表）；事件
  *   `subagent_background` 由 `SessionEvent` 派生。`RPC_PROTOCOL_VERSION` 不变。
  */

package/dist/rpc.js

@@ -12,14 +12,14 @@
  * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
  *   附最新 usage）；stream-json 输出同一形状。
  * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
- * - [W5-C0] 第五波（docs/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
+ * - [W5-C0] 第五波（docs/history/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
  *   get_tasks / get_agents`（返回形状见 `RpcW5Results`），客户端能力 `plans`（声明后计划审批交客户端）；
  *   新事件由 `SessionEvent` 派生自动包含。命令实现归 W5-F（C0 时返回 `not_implemented`），
  *   `RPC_PROTOCOL_VERSION` 不变。
- * - [W6-C0] 第六波（docs/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
+ * - [W6-C0] 第六波（docs/history/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
  *   `RpcW6Results`，W6-T2 实现，之前回 `not_implemented`）；事件 `quota_update`；`permission_request.context`
  *   可带 `toolCallId`；`keySource` 可为 `oauth`。`RPC_PROTOCOL_VERSION` 不变。
- * - [W7-B2] 后台子 Agent（docs/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
+ * - [W7-B2] 后台子 Agent（docs/history/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
  *   `RpcW7Results`（无 taskId = 全部前台运行中任务；对已结束 / 已在后台的任务回空表）；事件
  *   `subagent_background` 由 `SessionEvent` 派生。`RPC_PROTOCOL_VERSION` 不变。
  */

package/dist/sandbox/bash.d.ts

@@ -1,5 +1,5 @@
 /**
- * bash 的 OS 沙箱（docs/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
+ * bash 的 OS 沙箱（docs/guides/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
  *
  * - 生效条件：`sandbox.bash: auto` 且探测到能限制写入的沙箱（sandbox-exec / bwrap；`unshare` 只隔离网络，
  *   不算）。不生效时 bash 原样运行、权限照旧；

package/dist/sandbox/bash.js

@@ -1,5 +1,5 @@
 /**
- * bash 的 OS 沙箱（docs/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
+ * bash 的 OS 沙箱（docs/guides/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
  *
  * - 生效条件：`sandbox.bash: auto` 且探测到能限制写入的沙箱（sandbox-exec / bwrap；`unshare` 只隔离网络，
  *   不算）。不生效时 bash 原样运行、权限照旧；

package/dist/sandbox/detect.d.ts

@@ -1,5 +1,5 @@
 /**
- * 操作系统沙箱能力探测（docs/sandbox.md「探测与降级」）。
+ * 操作系统沙箱能力探测（docs/guides/sandbox.md「探测与降级」）。
  *
  * - 「存在」不等于「可用」（嵌套在别的沙箱里、容器里没有用户命名空间）：用目标配置跑一次最小探针，退出码 0
  *   才算可用；

package/dist/sandbox/detect.js

@@ -1,5 +1,5 @@
 /**
- * 操作系统沙箱能力探测（docs/sandbox.md「探测与降级」）。
+ * 操作系统沙箱能力探测（docs/guides/sandbox.md「探测与降级」）。
  *
  * - 「存在」不等于「可用」（嵌套在别的沙箱里、容器里没有用户命名空间）：用目标配置跑一次最小探针，退出码 0
  *   才算可用；

package/dist/sandbox/index.d.ts

@@ -1,4 +1,4 @@
-/** 操作系统级沙箱（docs/sandbox.md）：探测、参数生成与命令包装。 */
+/** 操作系统级沙箱（docs/guides/sandbox.md）：探测、参数生成与命令包装。 */
 export { NO_OS_SANDBOX, configureOsSandbox, osSandboxStatus, probeOsSandbox, resetOsSandboxForTests, resolveSandboxEnabled, type OsSandboxStatus, type ProbeDeps, type SandboxEnabled, } from "./detect.js";
 export { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, type OsSandboxKind, type OsSandboxPolicy, } from "./profile.js";
 export { resolveExtras, resolveWritable, wrapCommand, type WrappedCommand } from "./wrap.js";

package/dist/sandbox/index.js

@@ -1,4 +1,4 @@
-/** 操作系统级沙箱（docs/sandbox.md）：探测、参数生成与命令包装。 */
+/** 操作系统级沙箱（docs/guides/sandbox.md）：探测、参数生成与命令包装。 */
 export { NO_OS_SANDBOX, configureOsSandbox, osSandboxStatus, probeOsSandbox, resetOsSandboxForTests, resolveSandboxEnabled, } from "./detect.js";
 export { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, } from "./profile.js";
 export { resolveExtras, resolveWritable, wrapCommand } from "./wrap.js";

package/dist/sandbox/profile.d.ts

@@ -1,5 +1,5 @@
 /**
- * 操作系统沙箱的参数生成（docs/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
+ * 操作系统沙箱的参数生成（docs/guides/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
  *
  * - `buildSbplProfile`：macOS `sandbox-exec -p` 的 SBPL 配置；
  * - `buildBwrapArgs`：Linux bubblewrap 的参数（到 `--` 为止）；

package/dist/sandbox/profile.js

@@ -1,5 +1,5 @@
 /**
- * 操作系统沙箱的参数生成（docs/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
+ * 操作系统沙箱的参数生成（docs/guides/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
  *
  * - `buildSbplProfile`：macOS `sandbox-exec -p` 的 SBPL 配置；
  * - `buildBwrapArgs`：Linux bubblewrap 的参数（到 `--` 为止）；

package/dist/sandbox/wrap.d.ts

@@ -1,5 +1,5 @@
 /**
- * 包装命令行（docs/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
+ * 包装命令行（docs/guides/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
  * spawn（进程组、stdio、环境都不变）。
  *
  * - 可写目录取 realpath（SBPL 按真实路径匹配，macOS 的 /tmp、/var 是符号链接；bwrap 绑定也要求存在），

package/dist/sandbox/wrap.js

@@ -1,5 +1,5 @@
 /**
- * 包装命令行（docs/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
+ * 包装命令行（docs/guides/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
  * spawn（进程组、stdio、环境都不变）。
  *
  * - 可写目录取 realpath（SBPL 按真实路径匹配，macOS 的 /tmp、/var 是符号链接；bwrap 绑定也要求存在），

package/dist/sdk.d.ts

@@ -10,10 +10,10 @@
  *   summarizeFrom / summarizeUpTo / undoAbortedTurn`，内存会话只能仅对话）。
  *
  * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
- * - [W5-F] 计划（docs/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
+ * - [W5-F] 计划（docs/guides/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
  *   返回的会话带 `plan.current() / respond() / todos()`。没有 `onProposed` 时按 `plan.unattended`
  *   （缺省 stop：计划落盘后停下，不替人批准）。
- * - [W6-C0] `language`（两个入口都有）：界面语言，跟随宿主界面（docs/i18n.md）；进程级，`AMA_LANG` 仍优先。
+ * - [W6-C0] `language`（两个入口都有）：界面语言，跟随宿主界面（docs/guides/i18n.md）；进程级，`AMA_LANG` 仍优先。
  */
 import type { ApiRegistry } from "./ai/apis/api.js";
 import type { ModelThinkingLevel, ProviderData } from "./ai/types.js";
@@ -135,7 +135,7 @@ export interface CreateSessionOptions {
     /** 命令式 Hook（缺省不加载文件系统里的 hooks.json）。 */
     hooks?: HookConfig | false;
     config?: Partial<AmaConfig>;
-    /** [W5-F] 计划（plan.* 配置与审批回调），见 docs/plan.md。 */
+    /** [W5-F] 计划（plan.* 配置与审批回调），见 docs/guides/plan.md。 */
     plan?: SessionPlanOptions;
     unattended?: boolean;
     onWarning?: (message: string) => void;

package/dist/sdk.js

@@ -10,10 +10,10 @@
  *   summarizeFrom / summarizeUpTo / undoAbortedTurn`，内存会话只能仅对话）。
  *
  * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
- * - [W5-F] 计划（docs/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
+ * - [W5-F] 计划（docs/guides/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
  *   返回的会话带 `plan.current() / respond() / todos()`。没有 `onProposed` 时按 `plan.unattended`
  *   （缺省 stop：计划落盘后停下，不替人批准）。
- * - [W6-C0] `language`（两个入口都有）：界面语言，跟随宿主界面（docs/i18n.md）；进程级，`AMA_LANG` 仍优先。
+ * - [W6-C0] `language`（两个入口都有）：界面语言，跟随宿主界面（docs/guides/i18n.md）；进程级，`AMA_LANG` 仍优先。
  */
 import { resolve } from "node:path";
 import { ProviderRegistry } from "./ai/providers/registry.js";

package/dist/session/line-reader.d.ts

@@ -1,5 +1,5 @@
 /**
- * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * 会话文件的字节级按行读取（docs/history/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
  * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
  *
  * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲

package/dist/session/line-reader.js

@@ -1,5 +1,5 @@
 /**
- * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * 会话文件的字节级按行读取（docs/history/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
  * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
  *
  * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲

package/dist/session/list.d.ts

@@ -1,5 +1,5 @@
 /**
- * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/history/memory-plan.md D6、§2.4）：
  * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
  * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
  *

package/dist/session/list.js

@@ -1,5 +1,5 @@
 /**
- * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/history/memory-plan.md D6、§2.4）：
  * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
  * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
  *

package/dist/session/migrate.d.ts

@@ -8,7 +8,7 @@
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
  * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
- * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/history/memory-plan.md R6）。
  */
 import type { SessionEntry, SessionHeader, SessionLine } from "./types.js";
 export interface MigratedSession {

package/dist/session/migrate.js

@@ -8,7 +8,7 @@
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
  * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
- * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/history/memory-plan.md R6）。
  */
 import { AmaError } from "../errors.js";
 import { SESSION_FORMAT_VERSION } from "./types.js";

package/dist/session/store.d.ts

@@ -30,7 +30,7 @@ export interface ReadResult {
 export declare function isBlankLine(line: Buffer): boolean;
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
- * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
+ * 按块逐行读（line-reader.ts，docs/history/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 export declare function readSessionLines(file: string, options?: {
     repair?: boolean;

package/dist/session/store.js

@@ -45,7 +45,7 @@ export function isBlankLine(line) {
 }
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
- * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
+ * 按块逐行读（line-reader.ts，docs/history/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 export function readSessionLines(file, options = {}) {
     const lines = [];

package/dist/skills/builtin.js

@@ -14,7 +14,7 @@ import { dirname, join } from "node:path";
 export const BUILTIN_SKILLS_DIR = "builtin";
 const AMA_DOCS_BODY = `# ama quick reference
 
-ama is the coding agent running this session. Docs: https://github.com/Owlbay/armadra-agent (README.md, docs/).
+ama is the coding agent running this session. Docs: https://github.com/AMA-Link/armadra-agent (README.md, docs/).
 
 ## Files
 - User config dir \`~/.config/ama/\` (\`AMA_CONFIG_DIR\`; Windows \`%APPDATA%\\ama\`): \`config.json\`, \`auth.json\` (keys, 0600), \`hooks.json\`, \`keybindings.json\`, \`trust.json\`, \`AGENTS.md\`, \`skills/\`, \`prompts/\`.
@@ -93,7 +93,7 @@ export async function withBuiltinSkills(skills, dataDir, builtins = BUILTIN_SKIL
             await ensureFile(location, builtinSkillText(builtin));
         }
         catch (error) {
-            // 与 skills/ 其它加载告警一样固定英文（模型侧模块不 import i18n，见 docs/i18n.md）
+            // 与 skills/ 其它加载告警一样固定英文（模型侧模块不 import i18n，见 docs/guides/i18n.md）
             warnings.push(`built-in skill ${builtin.name} could not be written: ${error.message}`);
             continue;
         }

package/dist/tools/background-jobs.d.ts

@@ -1,5 +1,5 @@
 /**
- * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ * 后台命令（docs/history/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
  *
  * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不

package/dist/tools/background-jobs.js

@@ -1,5 +1,5 @@
 /**
- * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ * 后台命令（docs/history/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
  *
  * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不

package/dist/tools/clipboard-image.d.ts

@@ -1,5 +1,5 @@
 /**
- * 剪贴板图片（docs/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
+ * 剪贴板图片（docs/history/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
  *
  * 零依赖读不了剪贴板位图，按平台依次调系统命令，成功写 `<dataDir>/clipboard/<时间戳>.png` 并返回
  * 路径（编辑器插入 `@<路径>`，之后走 loadImageFile）；没有工具或剪贴板里没有图返回 undefined：

package/dist/tools/clipboard-image.js

@@ -1,5 +1,5 @@
 /**
- * 剪贴板图片（docs/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
+ * 剪贴板图片（docs/history/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
  *
  * 零依赖读不了剪贴板位图，按平台依次调系统命令，成功写 `<dataDir>/clipboard/<时间戳>.png` 并返回
  * 路径（编辑器插入 `@<路径>`，之后走 loadImageFile）；没有工具或剪贴板里没有图返回 undefined：

package/dist/tools/edit.d.ts

@@ -38,7 +38,7 @@ export declare function planEdits(content: string, edits: readonly EditOp[], rep
 export declare function unifiedDiff(oldText: string, newText: string, path: string, context?: number): string;
 /** 改前 / 改后全文（[ACP-C] D6）：任一侧超过 {@link FILE_CHANGE_TEXT_LIMIT} 返回 undefined。 */
 export declare function fileChangeOf(path: string, oldText: string | null, newText: string, firstChangedLine?: number): FileChange | undefined;
-/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+/** 检查点：写前备份（docs/history/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
 export declare function beforeWrite(ctx: ToolContext, abs: string): Promise<void>;
 export declare function executeEdit(input: EditInput, ctx: ToolContext): Promise<ToolResult>;
 export declare function createEditTool(): ToolDefinition<EditInput>;

package/dist/tools/edit.js

@@ -177,7 +177,7 @@ export function fileChangeOf(path, oldText, newText, firstChangedLine) {
 // ---------------------------------------------------------------------------
 // 工具
 // ---------------------------------------------------------------------------
-/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+/** 检查点：写前备份（docs/history/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
 export async function beforeWrite(ctx, abs) {
     if (ctx.checkpoint === undefined)
         return;

package/dist/tools/grep.d.ts

@@ -6,7 +6,7 @@
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
  * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
- *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
+ *   给模型在大仓库里先缩范围（docs/design/search-plan.md §4.2）。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 export interface GrepInput {

package/dist/tools/grep.js

@@ -6,7 +6,7 @@
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
  * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
- *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
+ *   给模型在大仓库里先缩范围（docs/design/search-plan.md §4.2）。
  */
 import { readFile, stat } from "node:fs/promises";
 import { displayPath, resolvePath } from "./paths.js";

package/dist/tools/image-resize.d.ts

@@ -1,5 +1,5 @@
 /**
- * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ * 可选的图片缩放（docs/history/wave5-plan.md §4、D12）。[W5-I]
  *
  * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
  * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回

package/dist/tools/image-resize.js

@@ -1,5 +1,5 @@
 /**
- * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ * 可选的图片缩放（docs/history/wave5-plan.md §4、D12）。[W5-I]
  *
  * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
  * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回

package/dist/tools/read-lines.d.ts

@@ -1,5 +1,5 @@
 /**
- * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ * `read` 大文件的字节窗口读取（docs/history/memory-plan.md D1、§2.1）。[M-E]
  *
  * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
  * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）

package/dist/tools/read-lines.js

@@ -1,5 +1,5 @@
 /**
- * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ * `read` 大文件的字节窗口读取（docs/history/memory-plan.md D1、§2.1）。[M-E]
  *
  * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
  * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）

package/dist/tools/read.d.ts

@@ -26,7 +26,7 @@ export interface ReadToolOptions {
 }
 export declare function isBinary(buf: Buffer): boolean;
 /**
- * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/design/search-plan.md §4.2）。
  * 活动集未知（宿主自建上下文）时沿用旧文案。
  */
 export declare function directoryHint(shown: string, ctx: Pick<ToolContext, "activeTools">): string;

package/dist/tools/read.js

@@ -29,7 +29,7 @@ function error(message) {
     return { content: message, isError: true };
 }
 /**
- * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/design/search-plan.md §4.2）。
  * 活动集未知（宿主自建上下文）时沿用旧文案。
  */
 export function directoryHint(shown, ctx) {

package/dist/tools/task-ctl.d.ts

@@ -1,6 +1,6 @@
 /**
  * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
- * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ * （docs/history/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
  *
  * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
  * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表

package/dist/tools/task-ctl.js

@@ -1,6 +1,6 @@
 /**
  * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
- * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ * （docs/history/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
  *
  * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
  * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表

package/dist/tools/task.d.ts

@@ -1,5 +1,5 @@
 /**
- * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/wave5-plan.md §7.3，D13、D23）。
+ * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/history/wave5-plan.md §7.3，D13、D23）。
  * [B3 → W5-G]
  *
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
@@ -55,7 +55,7 @@ export interface TaskToolOptions {
 export declare const TASK_CONTEXT_LEAD: string;
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
 export declare const FOREGROUND_DESCRIPTION: string;
-/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/history/agents-concurrency-plan.md §2.6）时的描述。 */
 export declare const BACKGROUND_DESCRIPTION: string;
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export declare const TASK_AGENTS_HEADING = "\nAgents:\n";

package/dist/tools/task.js

@@ -1,5 +1,5 @@
 /**
- * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/wave5-plan.md §7.3，D13、D23）。
+ * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/history/wave5-plan.md §7.3，D13、D23）。
  * [B3 → W5-G]
  *
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
@@ -64,7 +64,7 @@ export const TASK_CONTEXT_LEAD = "Delegate to a sub-agent (fresh context: give f
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
 export const FOREGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Returns its final report. Parallel in one reply; writers use isolation ` +
     "worktree. background: returns a taskId (see task_ctl); taskId: continue it.";
-/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/history/agents-concurrency-plan.md §2.6）时的描述。 */
 export const BACKGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Runs in the background by default: returns a taskId; a ` +
     "<task-notification> follows; keep working. background:false waits for the result. " +
     "taskId: continue it. Parallel in one reply; writers use isolation worktree.";