@armadra/agent 0.3.0 → 0.5.0

package/dist/cli/args.js

@@ -2,15 +2,18 @@
  * 手写参数解析（设计 §11.1 第 2 步、§12.10、§13）。[B5]
  *
  * - 支持 `--opt value` 与 `--opt=value`；`--` 之后全部作为提示文本；可重复的参数累加。
+ * - 位置参数 `-`：`-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>`。
  * - `--provider` 不带 `--model` 不在这里报错，由 bootstrap 第 11 步报（退出码 2）。
  */
 import { AmaError } from "../errors.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { canonicalPreset } from "../config/types.js";
 import { CODEMODE_MODES } from "../config/types.js";
 export const SUBCOMMANDS = [
     "auth",
@@ -20,6 +23,7 @@ export const SUBCOMMANDS = [
     "doctor",
     "config",
     "init",
+    "stats",
 ];
 export class UsageError extends AmaError {
     constructor(message) {
@@ -27,7 +31,7 @@ export class UsageError extends AmaError {
         this.name = "UsageError";
     }
 }
-const PERMISSION_MODES = ["plan", "default", "auto-edit", "full-auto"];
+const PERMISSION_MODES = PERMISSION_MODES_STRICT_FIRST;
 const THINKING_LEVELS = [
     "off",
     "minimal",
@@ -38,82 +42,10 @@ const THINKING_LEVELS = [
 ];
 const OUTPUT_FORMATS = ["text", "json", "stream-json"];
 const QUIET_LEVELS = ["normal", "header", "silent"];
-/** 帮助与报错按常用顺序列出（校验集合同 TOOLS_PRESETS_STRICT_FIRST）。 */
-const PRESET_CHOICES = ["default", "minimal", "codemode", "coordinator"];
+/** 帮助与报错按常用顺序列出（校验集合同 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 管道）
-  --output-format <格式>       -p 的输出：text（缺省）| json | stream-json
-  --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）
-
-权限与信任
-  --permission-mode <模式>     plan | default | auto-edit | full-auto
-  --allow <规则>               追加允许规则，可重复（如 "bash(git status*)"）
-  --deny <规则>                追加拒绝规则，可重复（如 "write(**/.env*)"）
-  --trust / --no-trust         信任 / 不信任当前项目（项目级 Hook、Skill、提示模板）
-
-资源
-  --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 | coordinator
-  --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 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；已有的不覆盖
-
-其它
-  -h, --help                   输出本帮助
-  -v, --version                输出版本
-
-退出码：0 正常 · 1 运行期错误 · 2 用法错误 · 3 配置错误 · 4 无可用模型或 key ·
-        5 会话错误 · 6 宿主 / Hook 启动失败 · 78 宿主 API 版本不匹配 · 130 SIGINT · 143 SIGTERM
-`;
+export { HELP_TEXT } from "./help-text.js";
 const VALUE_OPTIONS = new Set([
     "profile",
     "host",
@@ -139,6 +71,12 @@ const VALUE_OPTIONS = new Set([
     "tools-preset",
     "codemode",
     "image",
+    "max-turns",
+    "max-cost",
+    "agent-dir",
+    "system-prompt",
+    "system-prompt-mode",
+    "from",
 ]);
 const FLAG_ALIASES = {
     "-h": "help",
@@ -171,6 +109,9 @@ export function emptyArgs() {
         resume: false,
         print: false,
         noTui: false,
+        noSession: false,
+        stdin: false,
+        noStdin: false,
         positionals: [],
     };
 }
@@ -227,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")
@@ -244,7 +185,7 @@ function applyValue(args, option, value) {
             args.excludeTools = [...(args.excludeTools ?? []), ...list(value)];
             break;
         case "tools-preset":
-            args.toolsPreset = choice(option, value, PRESET_CHOICES);
+            args.toolsPreset = canonicalPreset(choice(option, value, PRESET_CHOICES));
             break;
         case "codemode":
             args.codemode = choice(option, value, CODEMODE_MODES);
@@ -252,6 +193,32 @@ function applyValue(args, option, value) {
         case "image":
             args.images.push(value);
             break;
+        case "system-prompt":
+            args.systemPrompt = value;
+            break;
+        case "system-prompt-mode":
+            args.systemPromptMode = choice(option, value, ["append", "replace"]);
+            break;
+        case "max-turns": {
+            const turns = Number(value);
+            if (!Number.isInteger(turns) || turns < 1)
+                throw new UsageError(`--max-turns 应为正整数（收到 ${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;
     }
 }
 function applyFlag(args, name) {
@@ -271,6 +238,12 @@ function applyFlag(args, name) {
         case "no-tui":
             args.noTui = true;
             return true;
+        case "no-session":
+            args.noSession = true;
+            return true;
+        case "no-stdin":
+            args.noStdin = true;
+            return true;
         case "trust":
         case "no-trust": {
             const value = name === "trust";
@@ -285,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,
@@ -295,12 +268,28 @@ function validate(args) {
     ].filter((f) => f !== undefined);
     if (sessionFlags.length > 1)
         throw new UsageError(`${sessionFlags.join(" 与 ")} 不能同时使用`);
+    if (args.noSession && sessionFlags.length > 0) {
+        throw new UsageError(`--no-session 与 ${sessionFlags[0]} 不能同时使用`);
+    }
     if (args.apiKey !== undefined && args.model === undefined) {
         throw new UsageError("--api-key 需要同时给出 --model");
     }
     if (args.outputFormat !== undefined && !args.print) {
         throw new UsageError("--output-format 只用于 -p / --print");
     }
+    if (args.systemPromptMode !== undefined && args.systemPrompt === undefined) {
+        throw new UsageError("--system-prompt-mode 需要同时给出 --system-prompt");
+    }
+    if (args.maxTurns !== undefined && !args.print) {
+        throw new UsageError("--max-turns 只用于 -p / --print");
+    }
+    if (args.noStdin && !args.print)
+        throw new UsageError("--no-stdin 只用于 -p / --print");
+    if (args.noStdin && args.stdin)
+        throw new UsageError("--no-stdin 与位置参数 - 不能同时使用");
+    if (args.stdin && !args.print) {
+        throw new UsageError("位置参数 - （从 stdin 读提示）只用于 -p / --print");
+    }
     if (args.images.length > 0 && !args.print) {
         throw new UsageError("--image 只用于 -p / --print（交互界面里写 @图片路径）");
     }
@@ -318,7 +307,11 @@ export function parseArgs(argv) {
             args.positionals.push(...argv.slice(i + 1));
             break;
         }
-        if (!token.startsWith("-") || token === "-") {
+        if (token === "-") {
+            args.stdin = true;
+            continue;
+        }
+        if (!token.startsWith("-")) {
             args.positionals.push(token);
             continue;
         }

package/dist/cli/bootstrap.js

@@ -20,8 +20,10 @@ import { HookDispatcher } from "../hooks/dispatcher.js";
 import { AgentEventBus, createHostApi } from "../host/api-impl.js";
 import { activateHost, disposeHost } from "../host/loader.js";
 import { HELP_TEXT, parseArgs, UsageError } from "./args.js";
+import { applyFromOption } from "./from-prompt.js";
 import { ExitCode } from "./exit-codes.js";
 import { applyProfile, applyToolFilters, decideMode, defaultSendUser, instructionSources, resolveModel, sessionRequestOf, sourceOf, step, thinkingOf, toStartupError, } from "./startup-steps.js";
+import { resolveSystemPromptArg } from "./system-prompt-arg.js";
 /** §11.1 第 3–14 步。 */
 export async function bootstrap(argsIn, deps, io) {
     const warnings = [];
@@ -118,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({
@@ -154,10 +157,15 @@ export async function bootstrap(argsIn, deps, io) {
             }
             : {}),
     }));
-    const { model, provider } = await step(ExitCode.NoModel, "模型", () => resolveModel(args, providers, sessionManager, config.defaultModel, deps, interactive));
+    const { model, provider } = await step(ExitCode.NoModel, "模型", () => resolveModel(args, providers, sessionManager, config.defaultModel, deps, interactive, io.env));
     const thinkingLevel = thinkingOf(args, sessionManager, config.thinkingLevel);
     // 12. 工具注册表
-    const tools = await step(ExitCode.RuntimeError, "工具", () => deps.tools.create({ config, cwd: sessionCwd, mode }));
+    const tools = await step(ExitCode.RuntimeError, "工具", () => deps.tools.create({
+        config,
+        cwd: sessionCwd,
+        mode,
+        paths: { configDir: paths.configDir, dataDir: paths.dataDir },
+    }));
     for (const name of config.tools?.disabled ?? []) {
         if (tools.get(name) === undefined)
             warn(`config tools.disabled：未知工具 ${name}，已忽略`);
@@ -200,12 +208,14 @@ export async function bootstrap(argsIn, deps, io) {
         // 14. 组装 AgentSession、session_start、SessionStart Hook
         const unattended = mode === "print";
         const builtinDeny = config.permission?.builtinDeny;
+        const autoSafeCommands = config.permission?.autoSafeCommands;
         const permission = await step(ExitCode.Config, "权限", () => deps.permissions.create({
             mode: config.permission?.mode ?? "default",
             rules: merged.ruleSpecs,
             unattended,
             cwd: sessionCwd,
             ...(builtinDeny !== undefined ? { builtinDeny } : {}),
+            ...(autoSafeCommands !== undefined ? { autoSafeCommands } : {}),
         }));
         const hooks = new HookDispatcher({
             hooks: hookConfig.hooks,
@@ -260,6 +270,21 @@ export async function bootstrap(argsIn, deps, io) {
             unattended,
             warn,
         };
+        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));
+        if (systemPrompt !== undefined)
+            overrides.systemPrompt = systemPrompt;
+        if (Object.keys(overrides).length > 0)
+            assembly.overrides = overrides;
         session = await step(ExitCode.RuntimeError, "会话组装", () => deps.session.create(assembly));
         const active = session;
         let disposed;
@@ -347,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;
@@ -359,12 +388,18 @@ export async function runCli(argv, deps, io) {
         return reportError(error, io);
     }
     const restore = runtime.mode === "print" || runtime.mode === "rpc" ? takeOverStdout() : () => undefined;
+    let cleanupFrom = () => undefined;
     try {
         if (runtime.mode !== "interactive")
             for (const w of runtime.warnings)
                 io.stderr(`ama: 警告：${w}\n`);
-        const context = { args, prompt: args.prompt, io };
-        const runner = deps.modes[runtime.mode];
+        // [W4-D] --from：旧会话的一条用户消息作提示（-p 时连图片，临时文件在 finally 删除）。
+        const from = applyFromOption(args, runtime, io);
+        cleanupFrom = from.cleanup;
+        const context = from.context;
+        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 {
@@ -383,6 +418,7 @@ export async function runCli(argv, deps, io) {
     }
     finally {
         await runtime.dispose("exit").catch(() => undefined);
+        cleanupFrom();
         restore();
     }
 }

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

@@ -0,0 +1,21 @@
+/**
+ * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * 怎么显式开启。
+ *
+ * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）
+ *   不提示；
+ * - 每个配置目录只提示一次：已提示过的配置目录记在 `<数据目录>/notices.json`；读写失败不影响启动
+ *   （至多多提示一次）。
+ */
+import type { SandboxCapability } from "../codemode/capability.js";
+import type { AmaConfig } from "../config/types.js";
+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" | "sandbox">;
+    capability: Pick<SandboxCapability, "strict" | "nodeMajor">;
+    configDir: string;
+    dataDir: string;
+}): string | undefined;

package/dist/cli/codemode-notice.js

@@ -0,0 +1,56 @@
+/**
+ * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * 怎么显式开启。
+ *
+ * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）
+ *   不提示；
+ * - 每个配置目录只提示一次：已提示过的配置目录记在 `<数据目录>/notices.json`；读写失败不影响启动
+ *   （至多多提示一次）。
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCodemodeMode } from "../tools/presets.js";
+export const NOTICES_FILE = "notices.json";
+const KEY = "codemodeNonStrictDefault";
+function readNotices(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const shown = value[KEY];
+            return {
+                version: 1,
+                ...(Array.isArray(shown) ? { [KEY]: shown.filter((s) => typeof s === "string") } : {}),
+            };
+        }
+    }
+    catch {
+        // 不存在或损坏：按没提示过处理
+    }
+    return { version: 1 };
+}
+export function codemodeNoticeText(capability) {
+    return (`Node ${capability.nodeMajor} < 25 且没有可用的操作系统沙箱：codemode 沙箱的网络未隔离，codemode 缺省关闭；` +
+        "用 `--codemode on` 或 config 的 codemode.mode 开启（每个配置目录只提示一次）");
+}
+/** 需要提示时返回文案并记下（之后同一配置目录不再提示）；不需要时 undefined。 */
+export function takeCodemodeNotice(input) {
+    const resolved = resolveCodemodeMode(input.config, input.capability.strict);
+    if (resolved.source !== "preset" || resolved.preset !== "default" || input.capability.strict)
+        return undefined;
+    const path = join(input.dataDir, NOTICES_FILE);
+    const notices = readNotices(path);
+    const shown = notices[KEY] ?? [];
+    if (shown.includes(input.configDir))
+        return undefined;
+    try {
+        mkdirSync(input.dataDir, { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify({ ...notices, [KEY]: [...shown, input.configDir] })}\n`);
+        renameSync(tmp, path);
+    }
+    catch {
+        // 写不进去也照常提示
+    }
+    return codemodeNoticeText(input.capability);
+}

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 任务注册表
+    ];
+}