@armadra/agent 0.4.0 → 0.5.1

package/dist/cli/args.js

@@ -5,7 +5,7 @@
  * - 位置参数 `-`：`-p` 一直等 stdin 到 EOF（有提示参数时也不设首字节超时）。
  * - 子命令只在第一个参数是 `auth / sessions / models / providers / doctor / config / init` 时识别，
  *   其余参数原样交给子命令。
- * - 互斥：`-p` 与 `--mode rpc`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
+ * - 互斥：`-p` 与 `--mode rpc / acp`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
  *   `--trust` 与 `--no-trust`；`--api-key` 需要 `--model`；`--output-format` 需要 `-p`。
  * - `--resume [id]`：下一个参数形如会话 id（无空白、不以 `-` 开头）才被当作 id；
  *   否则仍作为提示文本。显式写法 `--resume=<id>`。
@@ -45,99 +45,7 @@ const QUIET_LEVELS = ["normal", "header", "silent"];
 /** 帮助与报错按常用顺序列出（校验集合同 TOOLS_PRESET_INPUTS；`codemode` 是 `codemode-only` 的别名）。 */
 const PRESET_CHOICES = ["default", "minimal", "codemode-only", "coordinator", "codemode"];
 const SESSION_ID_LIKE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
-export const HELP_TEXT = `用法：ama [选项] [提示]
-      ama <子命令> …
-
-模式
-  （缺省）                     终端界面；stdin / stdout 非 TTY 或 TERM=dumb 时自动降级为行式
-  --no-tui                     行式界面（readline + 括号粘贴）
-  -p, --print                  非交互：执行提示后退出。提示 = 参数 + stdin 管道内容；有提示参数时
-                               只等管道首字节 2 s（AMA_STDIN_WAIT_MS），没收到就忽略并提示；
-                               末尾加 - 则一直等到 EOF（如 npm test | ama -p 找原因 -）
-  --no-stdin                   -p 不读 stdin（父进程留着管道、又不想等 2 s 时）
-  --output-format <格式>       -p 的输出：text（缺省）| json | stream-json
-  --max-turns <N>              -p 最多跑 N 轮（一次模型请求加其工具执行算一轮）；到达上限仍有
-                               未完成的工具调用时提前结束，退出码 1
-  --image <文件>               -p 随提示发送图片（可重复；png / jpg / gif / webp，单张 ≤ 5 MB）；
-                               交互界面里写 @图片路径 或粘贴图片路径
-  --mode rpc                   stdio JSONL 协议（供嵌入）
-  --tui-mode <模式>            显示模式，第一期只有 regular（主屏）
-  --quiet-startup <档>         启动画面：normal | header | silent
-
-模型
-  --model <provider/id>        模型（可配合 --provider 只写 id；@渠道 指定渠道，如 packy/kimi-k2.5@messages）
-  --provider <id>              供应商（必须同时给 --model）
-  --api-key <key>              只用于本次启动的 key（需要 --model；优先用 ama auth set）
-  --thinking <级别>            off | minimal | low | medium | high | xhigh
-
-会话
-  -c, --continue               继续本目录最近的会话
-  -r, --resume [id]            恢复会话（交互模式无 id 时弹选择器）
-  --session-id <id>            使用指定 id 的会话（不存在则新建）
-  --fork <id>                  从指定会话分叉出新会话
-  --session-dir <目录>         会话目录（缺省 ~/.local/share/ama/sessions）
-  --no-session                 会话只在内存里，不写会话文件（之后无法 --resume）
-  --from <id>[#编号]           用旧会话的一条用户消息作提示（缺省最后一条；-p 时连图片一起；
-                               编号见 ama sessions show）
-
-权限与信任
-  --permission-mode <模式>     default | auto-edit | plan | auto | full-auto | allowlist
-                               （auto 由 ama 判断每一步；allowlist 只放行 allow 规则命中的，适合 CI）
-  --allow <规则>               追加允许规则，可重复（如 "bash(git status*)"）
-  --deny <规则>                追加拒绝规则，可重复（如 "write(**/.env*)"）
-  --trust / --no-trust         信任 / 不信任当前项目（项目级 Hook、Skill、提示模板）
-
-资源
-  --system-prompt <文本|@文件> 追加系统提示：缺省作为最后一条规则追加（工具表等前缀不变，利于缓存）
-  --system-prompt-mode <方式>  append（缺省）| replace（替换开头的角色说明，工具与项目上下文保留）
-  --profile <文件>             宿主 profile.json（字段等价于对应参数，命令行优先）
-  --host <模块>                宿主适配器模块（CJS / ESM）
-  --instructions <文件>        追加指令文件，可重复
-  --skill-dir <目录>           追加 Skill 目录，可重复
-  --auth-file <文件>           auth.json 位置（缺省 ~/.config/ama/auth.json）
-  --tools <a,b,…>              只启用这些工具
-  --exclude-tools <a,b,…>      禁用这些工具
-  --tools-preset <名>          工具预设：default（缺省）| minimal | codemode-only | coordinator
-                               （codemode 是 codemode-only 的旧名，仍可用）
-  --codemode <模式>            codemode 调用方式：off | on | only（缺省随预设）
-
-子命令
-  ama auth set <provider>      从 stdin 读取 key 写入 auth.json（0600）
-  ama auth list                列出已保存 key 的供应商（不显示 key）
-  ama auth remove <provider>   删除已保存的 key
-  ama sessions list|show|prune 会话管理
-  ama sessions search <关键词|/正则/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]
-                               跨会话全文检索
-  ama sessions export <id> [--format md|json|jsonl] [--output <文件>] [--branch leaf|all]
-                               导出会话（已脱敏）
-  ama models list [--provider <id>]  列出模型（含来源与 key 状态）
-  ama models check <provider/id>     发一次最小请求检查可用性
-  ama models discover <provider> [--probe] [--write] [--limit N]
-                               从中转 /v1/models 列出模型，探测协议并写入配置
-  ama models refresh-catalog   强制刷新 models.dev 模型元数据缓存
-  ama providers add <id> --base-url <url> [--key-env VAR] [--probe] [--channel n=api@url] [--yes]
-                               一键接入：列模型、补 models.dev 元数据、探测渠道、写入配置
-  ama providers list|channels <id>|remove <id>|refresh <id>
-                               供应商 → 渠道 → 模型；删除；重拉模型列表
-  ama models cache-probe <provider/id> [--tokens N] [--gap-ms MS] [--yes] [--json]
-                               判断端点是否报告缓存命中
-  ama doctor                   配置层级、信任、key 来源、Hook、终端能力
-  ama config show [--json]     生效配置与每项来源、将使用的模型
-  ama config path              配置目录、数据目录与各文件路径
-  ama config edit              用 $VISUAL / $EDITOR 打开 config.json
-  ama init [--force]           建配置目录（0700）与 config.json、config.schema.json；已有的不覆盖
-  ama stats [--since 7d] [--by day|week|month|provider|channel|model|project] [--all] [--json]
-                               跨会话统计：请求、token、缓存命中率、费用、工具调用
-
-其它
-  -h, --help                   输出本帮助
-  -v, --version                输出版本
-
-退出码：0 正常 · 1 运行期错误 · 2 用法错误 · 3 配置错误 · 4 无可用模型或 key ·
-        5 会话错误 · 6 宿主 / Hook 启动失败 · 7 -p 有工具调用被拒（无人审批；用
-        --permission-mode auto-edit|auto 或 --allow 放行）· 78 宿主 API 版本不匹配 ·
-        130 SIGINT · 143 SIGTERM
-`;
+export { HELP_TEXT } from "./help-text.js";
 const VALUE_OPTIONS = new Set([
     "profile",
     "host",
@@ -164,6 +72,8 @@ const VALUE_OPTIONS = new Set([
     "codemode",
     "image",
     "max-turns",
+    "max-cost",
+    "agent-dir",
     "system-prompt",
     "system-prompt-mode",
     "from",
@@ -258,7 +168,7 @@ function applyValue(args, option, value) {
             args.outputFormat = choice(option, value, OUTPUT_FORMATS);
             break;
         case "mode":
-            args.mode = choice(option, value, ["rpc"]);
+            args.mode = choice(option, value, ["rpc", "acp"]);
             break;
         case "tui-mode":
             if (value === "fullscreen")
@@ -296,6 +206,16 @@ function applyValue(args, option, value) {
             args.maxTurns = turns;
             break;
         }
+        case "max-cost": {
+            const usd = Number(value);
+            if (!Number.isFinite(usd) || usd <= 0)
+                throw new UsageError(`--max-cost 应为正数（美元，收到 ${value}）`);
+            args.maxCostUsd = usd;
+            break;
+        }
+        case "agent-dir":
+            (args.agentDirs ??= []).push(value);
+            break;
         case "from":
             args.from = value;
             break;
@@ -338,8 +258,8 @@ function applyFlag(args, name) {
     }
 }
 function validate(args) {
-    if (args.print && args.mode === "rpc")
-        throw new UsageError("-p 与 --mode rpc 不能同时使用");
+    if (args.print && args.mode !== undefined)
+        throw new UsageError(`-p 与 --mode ${args.mode} 不能同时使用`);
     const sessionFlags = [
         args.continue ? "--continue" : undefined,
         args.resume ? "--resume" : undefined,

package/dist/cli/bootstrap.js

@@ -120,6 +120,7 @@ export async function bootstrap(argsIn, deps, io) {
             trusted: trust.trusted,
             extraSkillDirs: [...args.skillDirs, ...(config.skills?.dirs ?? [])],
             promptDirs: profile?.promptDirs ?? [],
+            dataDir: paths.dataDir,
         }) ?? { skills: [], prompts: [], warnings: [] });
     warnings.push(...discovered.warnings);
     const hookConfig = await step(ExitCode.Config, "hooks.json", () => loadHookConfigs({
@@ -272,6 +273,11 @@ export async function bootstrap(argsIn, deps, io) {
         const overrides = {};
         if (args.maxTurns !== undefined)
             overrides.maxTurns = args.maxTurns;
+        // [W5-H2] --max-cost 由 limits 扩展执行（agent/limits.ts）
+        if (args.maxCostUsd !== undefined)
+            overrides.maxCostUsd = args.maxCostUsd;
+        if (args.agentDirs !== undefined)
+            overrides.agentDirs = [...args.agentDirs];
         if (args.noSession)
             overrides.noSession = true;
         const systemPrompt = await step(ExitCode.Config, "--system-prompt", () => resolveSystemPromptArg(args.systemPrompt, args.systemPromptMode, io.cwd));
@@ -366,6 +372,10 @@ export async function runCli(argv, deps, io) {
         io.stdout(HELP_TEXT);
         return ExitCode.Ok;
     }
+    // [W5-E] --mode acp：装配同 rpc（宿主看到的 mode 也是 rpc），分派到 ACP 服务端
+    const acp = args.mode === "acp";
+    if (acp)
+        args = { ...args, mode: "rpc" };
     if (deps === undefined) {
         io.stderr("ama: 运行时尚未装配（集成批次通过 registerRuntimeDeps 注入实现）\n");
         return ExitCode.RuntimeError;
@@ -387,7 +397,9 @@ export async function runCli(argv, deps, io) {
         const from = applyFromOption(args, runtime, io);
         cleanupFrom = from.cleanup;
         const context = from.context;
-        const runner = deps.modes[runtime.mode];
+        const runner = acp
+            ? (await import("../modes/acp/acp-mode.js")).runAcpMode
+            : deps.modes[runtime.mode];
         if (runner === undefined)
             throw new AmaError("not_implemented", `模式 ${runtime.mode} 尚未装配`, { exitCode: 1 });
         try {

package/dist/cli/choice-prompt.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI 子命令的方向键选择（零依赖）：TTY 下 raw mode 画一个编号选项列表，原地重画。
+ *
+ * - 按键：↑↓（与 Ctrl+P / Ctrl+N）移动、Enter 确认、数字直选、选项按键提示里的单个字母直选（`y` / `n`），
+ *   Esc / Ctrl+C / stdin 结束 = 取消；
+ * - 结束后把列表收成一行「? 问题 答案」，恢复 raw 状态与光标，暂停 stdin；进程意外退出时也恢复；
+ * - 颜色与字形按环境：`NO_COLOR` / 非 TTY 输出无色，`AMA_ASCII` / 区域设置决定 ASCII 字形（字形表见
+ *   docs/tui-design.md §2.2）；
+ * - 输入不是可开 raw 的 TTY（管道、CI）时 {@link confirmContinue} 回落为原来的文本 `[y/N]` 问答。
+ */
+export interface ChoiceInput {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?(raw: boolean): unknown;
+    on(event: "data" | "end", listener: (chunk?: Buffer | string) => void): unknown;
+    off(event: "data" | "end", listener: (chunk?: Buffer | string) => void): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+}
+export interface ChoiceOption {
+    label: string;
+    /** 右侧按键提示（空格分隔）；其中的单个字母同时是直选键。 */
+    keys?: string;
+}
+export interface PromptChoiceOptions {
+    question: string;
+    options: readonly ChoiceOption[];
+    /** 缺省选中的下标。 */
+    selected?: number;
+    /** 缺省 `process.stdin`。 */
+    input?: ChoiceInput;
+    /** 缺省写 stderr。 */
+    write?(text: string): void;
+    env?: NodeJS.ProcessEnv;
+    /** 输出是否 TTY（决定颜色）；缺省看 stderr。 */
+    outputIsTTY?: boolean;
+}
+/** 能否用方向键选择：输入是 TTY 且能开 raw。 */
+export declare function canPromptChoice(input?: ChoiceInput): boolean;
+/** 一块输入切成单个按键（转义序列整体、其余逐字符）。 */
+export declare function splitKeys(data: string): string[];
+/** 方向键选择：返回选中的下标，取消返回 undefined。调用方先用 {@link canPromptChoice} 判断。 */
+export declare function promptChoice(options: PromptChoiceOptions): Promise<number | undefined>;
+export interface ConfirmOptions {
+    /** 缺省「继续？」。 */
+    question?: string;
+    input?: ChoiceInput & NodeJS.ReadableStream;
+    write?(text: string): void;
+    /** 文本回落时问句写到哪里，缺省 stderr。 */
+    output?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    outputIsTTY?: boolean;
+}
+/**
+ * 计费 / 写入前的确认：TTY 下方向键选择「继续 / 取消」（缺省取消，`y` / `n` 直选）；
+ * 否则回落为文本 `继续？[y/N]`（只有 y / yes 算同意）。
+ */
+export declare function confirmContinue(options?: ConfirmOptions): Promise<boolean>;

package/dist/cli/choice-prompt.js

@@ -0,0 +1,140 @@
+/**
+ * CLI 子命令的方向键选择（零依赖）：TTY 下 raw mode 画一个编号选项列表，原地重画。
+ *
+ * - 按键：↑↓（与 Ctrl+P / Ctrl+N）移动、Enter 确认、数字直选、选项按键提示里的单个字母直选（`y` / `n`），
+ *   Esc / Ctrl+C / stdin 结束 = 取消；
+ * - 结束后把列表收成一行「? 问题 答案」，恢复 raw 状态与光标，暂停 stdin；进程意外退出时也恢复；
+ * - 颜色与字形按环境：`NO_COLOR` / 非 TTY 输出无色，`AMA_ASCII` / 区域设置决定 ASCII 字形（字形表见
+ *   docs/tui-design.md §2.2）；
+ * - 输入不是可开 raw 的 TTY（管道、CI）时 {@link confirmContinue} 回落为原来的文本 `[y/N]` 问答。
+ */
+import { createInterface } from "node:readline/promises";
+import { createTheme, defaultKeybindings, detectCapabilities, padToWidth, resolveAscii, visibleWidth, } from "../tui.js";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+/** 能否用方向键选择：输入是 TTY 且能开 raw。 */
+export function canPromptChoice(input = process.stdin) {
+    return input.isTTY === true && typeof input.setRawMode === "function";
+}
+/** 一块输入切成单个按键（转义序列整体、其余逐字符）。 */
+export function splitKeys(data) {
+    return data.match(/\x1b\[[0-9;?]*[ -/]*[@-~]|\x1bO[A-Za-z]|\x1b(?![[O])|[\s\S]/gu) ?? [];
+}
+/** 方向键选择：返回选中的下标，取消返回 undefined。调用方先用 {@link canPromptChoice} 判断。 */
+export function promptChoice(options) {
+    const input = options.input ?? process.stdin;
+    const write = options.write ?? ((text) => void process.stderr.write(text));
+    const env = options.env ?? process.env;
+    const theme = createTheme("dark", {
+        caps: detectCapabilities(env, options.outputIsTTY ?? process.stderr.isTTY === true),
+        ascii: resolveAscii(undefined, env),
+    });
+    const g = theme.glyphs;
+    const items = options.options;
+    const n = items.length;
+    let selected = Math.max(0, Math.min(n - 1, options.selected ?? 0));
+    let drawn = 0;
+    const keyWidth = Math.max(0, ...items.map((o) => (o.keys ?? "").length));
+    const labelWidth = Math.max(...items.map((o) => visibleWidth(o.label)));
+    const question = `${theme.fg("accent", "?")} ${theme.bold(options.question)}`;
+    const frame = () => [
+        question,
+        ...items.map((item, i) => {
+            const on = i === selected;
+            const left = `${on ? g.prompt : " "} ${i + 1}. ${padToWidth(item.label, labelWidth)}`;
+            const keys = item.keys === undefined ? "" : `  ${theme.fg("dim", item.keys.padEnd(keyWidth))}`;
+            return (on ? theme.fg("accent", theme.bold(left)) : left) + keys;
+        }),
+        theme.fg("dim", `${g.arrowUp}${g.arrowDown} 选择 · Enter 确认 · 1-${n} 直接选 · Esc 取消`),
+    ];
+    const draw = (lines) => {
+        const up = drawn > 0 ? `\x1b[${drawn}A` : "";
+        write(`${up}\r\x1b[J${lines.join("\n")}\n`);
+        drawn = lines.length;
+    };
+    return new Promise((resolve) => {
+        const wasRaw = input.isRaw === true;
+        let done = false;
+        const restore = () => {
+            input.setRawMode?.(wasRaw);
+            write(SHOW_CURSOR);
+        };
+        const finish = (index) => {
+            if (done)
+                return;
+            done = true;
+            input.off("data", onData);
+            input.off("end", onEnd);
+            process.off("exit", restore);
+            const answer = index === undefined ? "（已取消）" : items[index].label;
+            draw([`${question} ${theme.fg("dim", answer)}`]);
+            restore();
+            input.pause?.();
+            resolve(index);
+        };
+        const onKey = (key) => {
+            const letter = /^[a-z]$/i.test(key) ? key.toLowerCase() : "";
+            const byLetter = letter === "" ? -1 : items.findIndex((o) => (o.keys ?? "").split(/\s+/).includes(letter));
+            if (byLetter !== -1)
+                return finish(byLetter);
+            if (defaultKeybindings.matches(key, "tui.select.cancel"))
+                return finish(undefined);
+            if (/^[1-9]$/.test(key) && Number(key) <= n)
+                return finish(Number(key) - 1);
+            if (key === "\r" || key === "\n")
+                return finish(selected);
+            if (defaultKeybindings.matches(key, "tui.select.up"))
+                selected = (selected + n - 1) % n;
+            else if (defaultKeybindings.matches(key, "tui.select.down"))
+                selected = (selected + 1) % n;
+            else
+                return;
+            draw(frame());
+        };
+        const onData = (chunk) => {
+            for (const key of splitKeys(String(chunk ?? ""))) {
+                if (done)
+                    return;
+                onKey(key);
+            }
+        };
+        const onEnd = () => finish(undefined);
+        process.once("exit", restore);
+        input.setRawMode?.(true);
+        write(HIDE_CURSOR);
+        draw(frame());
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.resume?.();
+    });
+}
+/**
+ * 计费 / 写入前的确认：TTY 下方向键选择「继续 / 取消」（缺省取消，`y` / `n` 直选）；
+ * 否则回落为文本 `继续？[y/N]`（只有 y / yes 算同意）。
+ */
+export async function confirmContinue(options = {}) {
+    const question = options.question ?? "继续？";
+    const input = options.input ?? process.stdin;
+    if (canPromptChoice(input)) {
+        const index = await promptChoice({
+            question,
+            options: [
+                { label: "继续", keys: "y" },
+                { label: "取消", keys: "n Esc" },
+            ],
+            selected: 1,
+            input,
+            ...(options.write !== undefined ? { write: options.write } : {}),
+            ...(options.env !== undefined ? { env: options.env } : {}),
+            ...(options.outputIsTTY !== undefined ? { outputIsTTY: options.outputIsTTY } : {}),
+        });
+        return index === 0;
+    }
+    const rl = createInterface({ input, output: options.output ?? process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question(`${question}[y/N] `)).trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/cli/codemode-notice.d.ts

@@ -1,6 +1,7 @@
 /**
  * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
- * （Node ≥ 25）开 codemode；Node 22 / 24 下缺省关闭，启动时提示一次怎么显式开启。
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * 怎么显式开启。
  *
  * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）
  *   不提示；
@@ -13,7 +14,7 @@ export declare const NOTICES_FILE = "notices.json";
 export declare function codemodeNoticeText(capability: Pick<SandboxCapability, "nodeMajor">): string;
 /** 需要提示时返回文案并记下（之后同一配置目录不再提示）；不需要时 undefined。 */
 export declare function takeCodemodeNotice(input: {
-    config: Pick<AmaConfig, "tools" | "codemode">;
+    config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">;
     capability: Pick<SandboxCapability, "strict" | "nodeMajor">;
     configDir: string;
     dataDir: string;

package/dist/cli/codemode-notice.js

@@ -1,6 +1,7 @@
 /**
  * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
- * （Node ≥ 25）开 codemode；Node 22 / 24 下缺省关闭，启动时提示一次怎么显式开启。
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * 怎么显式开启。
  *
  * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）
  *   不提示；
@@ -29,7 +30,7 @@ function readNotices(path) {
     return { version: 1 };
 }
 export function codemodeNoticeText(capability) {
-    return (`Node ${capability.nodeMajor} < 25：codemode 沙箱的网络未隔离，codemode 缺省关闭；` +
+    return (`Node ${capability.nodeMajor} < 25 且没有可用的操作系统沙箱：codemode 沙箱的网络未隔离，codemode 缺省关闭；` +
         "用 `--codemode on` 或 config 的 codemode.mode 开启（每个配置目录只提示一次）");
 }
 /** 需要提示时返回文案并记下（之后同一配置目录不再提示）；不需要时 undefined。 */

package/dist/cli/compose-agents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 子 Agent 的组装（docs/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
+ *
+ * 由 compose-extensions.ts 的一行接入：每次装配会话时发现定义文件（`--agent-dir` / profile
+ * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具
+ * （描述里的类型清单）；工厂给每个根会话装一个扩展：建任务注册表（subagent-registry.ts，并发 /
+ * 排队上限与模型别名取自 config），`getStats().tasks` 汇总，会话 dispose 时停止后台任务。
+ * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。
+ *
+ * [W5-EG] 外部 runner（claude / codex / acp:* / 宿主注入）经 agents/external.ts 接入 `runners`：每个主
+ * 会话一个 ExternalAgents（审批接 requestApproval，只交给人）；PATH 上的 claude / codex 登记进类型
+ * 目录；嵌入宿主（有宿主适配器）时 ama 不自己 spawn 外部 Agent、也不登记（D17），只认
+ * `HostApi.runners.provide` 注入的。`/agents` / RPC `get_agents` 的外部探测在会话建立时异步缓存。
+ */
+import { type SubagentEnvironment } from "../agent/subagent-registry.js";
+import type { SessionCore } from "../agent/session-core.js";
+import type { SessionExtension, SessionExtensionFactory } from "../agent/session-extensions.js";
+import { AgentCatalog } from "../agents/catalog.js";
+import { type ExternalWiring } from "../agents/external.js";
+import type { ComposeExtensionDeps } from "./compose-extensions.js";
+export declare function loadAgentCatalog(deps: ComposeExtensionDeps): AgentCatalog;
+export declare function subagentEnvironment(deps: ComposeExtensionDeps, catalog: AgentCatalog): SubagentEnvironment;
+/** 外部 Agent 的装配材料（宿主、信任、探测开关取自装配材料与环境）。 */
+export declare function externalWiring(deps: ComposeExtensionDeps): ExternalWiring;
+/** 根会话的子 Agent 扩展：注册表、任务统计、dispose 时停止后台任务。 */
+export declare function createSubagentExtension(core: SessionCore, env: SubagentEnvironment, wiring?: ExternalWiring): SessionExtension;
+export declare function createSubagentsFactory(deps: ComposeExtensionDeps): SessionExtensionFactory;

package/dist/cli/compose-agents.js

@@ -0,0 +1,111 @@
+/**
+ * 子 Agent 的组装（docs/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
+ *
+ * 由 compose-extensions.ts 的一行接入：每次装配会话时发现定义文件（`--agent-dir` / profile
+ * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具
+ * （描述里的类型清单）；工厂给每个根会话装一个扩展：建任务注册表（subagent-registry.ts，并发 /
+ * 排队上限与模型别名取自 config），`getStats().tasks` 汇总，会话 dispose 时停止后台任务。
+ * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。
+ *
+ * [W5-EG] 外部 runner（claude / codex / acp:* / 宿主注入）经 agents/external.ts 接入 `runners`：每个主
+ * 会话一个 ExternalAgents（审批接 requestApproval，只交给人）；PATH 上的 claude / codex 登记进类型
+ * 目录；嵌入宿主（有宿主适配器）时 ama 不自己 spawn 外部 Agent、也不登记（D17），只认
+ * `HostApi.runners.provide` 注入的。`/agents` / RPC `get_agents` 的外部探测在会话建立时异步缓存。
+ */
+import { subagentRegistryFor } from "../agent/subagent-registry.js";
+import { AgentCatalog } from "../agents/catalog.js";
+import { agentSources, discoverAgents } from "../agents/discover.js";
+import { NO_AGENT_PROBE_ENV, SessionExternalAgents, registerExternalAgents, } from "../agents/external.js";
+import { hostRunnersOf } from "../host/api-impl.js";
+import { bindTaskAgents } from "../tools/task.js";
+/** 同一装配材料只提示一次（`/new` 等会重新装配会话）。 */
+const warned = new WeakSet();
+export function loadAgentCatalog(deps) {
+    const { assembly } = deps;
+    const found = discoverAgents(agentSources({
+        cwd: assembly.paths.cwd,
+        configDir: assembly.paths.configDir,
+        cliDirs: assembly.overrides?.agentDirs ?? [],
+        configDirs: assembly.config.agents?.dirs ?? [],
+    }), { trusted: assembly.trust.trusted });
+    if (!warned.has(assembly)) {
+        warned.add(assembly);
+        for (const warning of found.warnings)
+            assembly.warn(warning);
+        for (const dir of found.skippedUntrusted)
+            assembly.warn(`项目未信任，跳过子 Agent 定义目录 ${dir}（--trust 后生效）`);
+    }
+    return new AgentCatalog(found.agents);
+}
+export function subagentEnvironment(deps, catalog) {
+    const config = deps.assembly.config;
+    const env = {
+        catalog,
+        modelConfig: {
+            ...(config.agents === undefined ? {} : { agents: config.agents }),
+            ...(config.subagents === undefined ? {} : { subagents: config.subagents }),
+            ...(config.models === undefined ? {} : { models: config.models }),
+        },
+    };
+    const max = config.subagents?.maxConcurrent;
+    if (max !== undefined)
+        env.maxConcurrent = max;
+    const pending = config.subagents?.maxPending;
+    if (pending !== undefined)
+        env.maxPending = pending;
+    return env;
+}
+/** 外部 Agent 的装配材料（宿主、信任、探测开关取自装配材料与环境）。 */
+export function externalWiring(deps) {
+    const { assembly } = deps;
+    const api = assembly.host.handle?.api;
+    const hostRunners = api === undefined ? undefined : hostRunnersOf(api);
+    const config = assembly.config;
+    const wiring = {
+        env: deps.env,
+        hosted: assembly.host.handle !== undefined,
+        dataDir: assembly.paths.dataDir,
+        trusted: assembly.trust.trusted,
+        probe: deps.env[NO_AGENT_PROBE_ENV] !== "1",
+    };
+    if (hostRunners !== undefined)
+        wiring.hostRunners = hostRunners;
+    if (config.agents !== undefined)
+        wiring.config = config.agents;
+    const defaultModel = config.subagents?.defaultModel;
+    if (defaultModel !== undefined)
+        wiring.defaultModel = defaultModel;
+    return wiring;
+}
+/** 根会话的子 Agent 扩展：注册表、任务统计、dispose 时停止后台任务。 */
+export function createSubagentExtension(core, env, wiring) {
+    const external = wiring === undefined ? undefined : new SessionExternalAgents(core, wiring, env.catalog);
+    const registry = subagentRegistryFor(core, external === undefined ? env : { ...env, runners: (agent) => external.runner(agent) });
+    // RPC get_agents / `/agents` 的外部探测（异步，结果缓存）；-p 不需要
+    if (external !== undefined && core.options.unattended !== true)
+        void external.refreshInfos();
+    return {
+        id: "ama.subagents",
+        contributeStats(stats) {
+            const tasks = registry.stats();
+            if (tasks !== undefined)
+                stats.tasks = tasks;
+        },
+        dispose() {
+            registry.dispose();
+            external?.dispose();
+        },
+    };
+}
+export function createSubagentsFactory(deps) {
+    // 组装表的单元测试给的是不完整的装配材料
+    const task = deps.assembly.tools?.get?.("task");
+    if (task === undefined)
+        return () => undefined;
+    const catalog = loadAgentCatalog(deps);
+    const wiring = externalWiring(deps);
+    registerExternalAgents(catalog, wiring);
+    bindTaskAgents(task, catalog);
+    const env = subagentEnvironment(deps, catalog);
+    return ({ core }) => (core.depth > 0 ? undefined : createSubagentExtension(core, env, wiring));
+}

package/dist/cli/compose-extensions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 会话扩展的组装表（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ *
+ * 唯一允许多个批次各加一行的文件：每个批次在 `composeExtensions` 的数组里追加**一行**自己的工厂，
+ * 实现放在各自文件（`src/agent/session-<名>.ts` 等）。表顺序即调用顺序：
+ * - `beforePrompts`：靠前的先追加（plan 模式说明排在提醒之前）；
+ * - `wrapStream`：靠前的离协议层近，缓存控制器始终在最外层；
+ * - 其余钩子按表顺序。
+ *
+ * 写法（工厂每个会话实例各调一次；不想装进 task 子会话就按 depth 返回 undefined）：
+ *
+ * ```ts
+ * // src/agent/session-telemetry.ts [W5-A]
+ * export function createTelemetryExtension(deps: { now?(): number }): SessionExtension { … }
+ * // 本文件，数组里加一行：
+ * ({ core }) => (core.depth > 0 ? undefined : createTelemetryExtension({})),
+ * ```
+ *
+ * 配置从 `deps.assembly.config` 读（键与校验已在 config/schema-w5.ts，C0 统一加好）。
+ */
+import type { SessionExtensionFactory } from "../agent/session-extensions.js";
+import type { SessionAssembly } from "./deps.js";
+export interface ComposeExtensionDeps {
+    /** 第 14 步的装配材料：config、paths、mode、unattended、host、overrides 等。 */
+    readonly assembly: SessionAssembly;
+    readonly env: NodeJS.ProcessEnv;
+    log(level: "debug" | "info" | "warn" | "error", message: string): void;
+}
+export declare function composeExtensions(deps: ComposeExtensionDeps): SessionExtensionFactory[];

package/dist/cli/compose-extensions.js

@@ -0,0 +1,44 @@
+/**
+ * 会话扩展的组装表（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ *
+ * 唯一允许多个批次各加一行的文件：每个批次在 `composeExtensions` 的数组里追加**一行**自己的工厂，
+ * 实现放在各自文件（`src/agent/session-<名>.ts` 等）。表顺序即调用顺序：
+ * - `beforePrompts`：靠前的先追加（plan 模式说明排在提醒之前）；
+ * - `wrapStream`：靠前的离协议层近，缓存控制器始终在最外层；
+ * - 其余钩子按表顺序。
+ *
+ * 写法（工厂每个会话实例各调一次；不想装进 task 子会话就按 depth 返回 undefined）：
+ *
+ * ```ts
+ * // src/agent/session-telemetry.ts [W5-A]
+ * export function createTelemetryExtension(deps: { now?(): number }): SessionExtension { … }
+ * // 本文件，数组里加一行：
+ * ({ core }) => (core.depth > 0 ? undefined : createTelemetryExtension({})),
+ * ```
+ *
+ * 配置从 `deps.assembly.config` 读（键与校验已在 config/schema-w5.ts，C0 统一加好）。
+ */
+import { telemetryFactory } from "../agent/session-telemetry.js";
+import { createImageBudgetExtension } from "../agent/session-images.js";
+import { createLimitsExtension } from "../agent/limits.js";
+import { createRemindersExtension, remindersSettings } from "../agent/reminders.js";
+import { planExtensionFor } from "../plan/compose.js";
+import { createSubagentsFactory } from "./compose-agents.js";
+import { createExternalStatsExtension } from "../drivers/store.js";
+export function composeExtensions(deps) {
+    return [
+        // 各批次在下面约定的位置各加一行（顺序有意义，见文件头）：
+        // [W5-F]  createPlanExtension(...)
+        planExtensionFor(deps),
+        // [W5-H2] createRemindersExtension(...), createLimitsExtension(...)
+        ({ core }) => (core.depth > 0 ? undefined : createLimitsExtension(core, core.options.limits)),
+        ({ core }) => createRemindersExtension(core, remindersSettings(deps.assembly.config)),
+        // [W5-I]  createImageBudgetExtension(...)
+        ({ core }) => createImageBudgetExtension(core),
+        // [W5-A]  createTelemetryExtension(...)
+        telemetryFactory(deps.assembly.config.ui),
+        // [W5-E] 外部 Agent 记账 → SessionStats.external（只主会话）
+        ({ core }) => core.depth > 0 ? undefined : createExternalStatsExtension(() => core.manager.branch()),
+        createSubagentsFactory(deps), // [W5-G] 子 Agent 任务注册表
+    ];
+}