@armadra/agent 0.4.0 → 0.5.0

package/dist/agents/catalog.js

@@ -0,0 +1,82 @@
+/**
+ * 子 Agent 类型目录：内置 ⊕ 发现的定义 ⊕ 外部 runner（docs/wave5-plan.md §7.1–§7.3、§7.6）。[W5-G]
+ *
+ * - 发现的同名定义覆盖内置类型（不 warning）；外部 runner（W5-E 的 ProcessRunner、宿主 runner）以
+ *   `add()` 登记，名字已存在时保留先登记者。
+ * - `describe()`：task 工具描述里的类型清单，总预算约 400 token（1 600 字符），超出只列名字。
+ * - `resolveModel()`：调用参数 `model` > 定义 `model`（非 inherit）> config `agents.<name>.model` >
+ *   `subagents.defaultModel` > 父当前模型（返回 undefined）；`fast` / `strong` 经 `models.aliases`。
+ */
+import { agentEntry } from "../config/types-w5.js";
+import { BUILTIN_AGENTS } from "./builtin.js";
+export const AGENT_LIST_BUDGET_CHARS = 1600;
+export class AgentCatalog {
+    byName = new Map();
+    resolver;
+    constructor(discovered = []) {
+        for (const agent of BUILTIN_AGENTS)
+            this.byName.set(agent.name, agent);
+        for (const agent of discovered)
+            this.byName.set(agent.name, agent);
+    }
+    /**
+     * 目录里没有的名字按需解析（`acp:<program>`、未在启动时登记的外部 / 宿主 runner，见
+     * agents/external.ts）。解析出的类型不进 {@link describe}：task 工具描述在会话内保持字节不变。
+     */
+    setResolver(resolver) {
+        this.resolver = resolver;
+    }
+    get(name) {
+        return this.byName.get(name) ?? this.resolver?.(name);
+    }
+    /** 外部 / 宿主类型；同名已存在返回 false。 */
+    add(agent) {
+        if (this.byName.has(agent.name))
+            return false;
+        this.byName.set(agent.name, agent);
+        return true;
+    }
+    list() {
+        return [...this.byName.values()];
+    }
+    names() {
+        return [...this.byName.keys()];
+    }
+    infos() {
+        return this.list().map((agent) => {
+            const info = {
+                name: agent.name,
+                description: agent.description,
+                runner: agent.runner,
+                source: agent.source,
+            };
+            if (agent.filePath !== undefined)
+                info.filePath = agent.filePath;
+            return info;
+        });
+    }
+    /** task 工具描述里的类型清单（`- name: description`；超预算只列名字）。 */
+    describe(budget = AGENT_LIST_BUDGET_CHARS) {
+        const lines = this.list().map((agent) => `- ${agent.name}: ${agent.description}`);
+        const full = lines.join("\n");
+        if (full.length <= budget)
+            return full;
+        return this.names().join(", ");
+    }
+}
+export function resolveAgentModel(agent, requested, config) {
+    const own = agent.model === "inherit" ? undefined : agent.model;
+    const picked = requested ??
+        own ??
+        agentEntry(config.agents, agent.name)?.model ??
+        config.subagents?.defaultModel;
+    if (picked === undefined || picked === "inherit")
+        return {};
+    if (picked === "fast" || picked === "strong") {
+        const alias = config.models?.aliases?.[picked];
+        if (alias === undefined)
+            return { warning: `models.aliases.${picked} is not set; using the parent model` };
+        return { ref: alias };
+    }
+    return { ref: picked };
+}

package/dist/agents/discover.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 子 Agent 定义发现（docs/wave5-plan.md §7.1，D22）。[W5-G]
+ *
+ * 顺序：`--agent-dir`（可重复，profile `agentDirs` 由启动步骤并在其后）→ config `agents.dirs` →
+ * `<configDir>/agents/*.md`（用户级）→ `<cwd>/.ama/agents/*.md`（项目级，需信任；未信任跳过并记入
+ * `skippedUntrusted`）。每个来源目录只看直接下层的 `*.md`（按名排序）；同名先发现者胜并 warning。
+ * 内置类型（builtin.ts）由 catalog.ts 合并，可被这里发现的同名定义覆盖。
+ *
+ * 同步实现：定义目录小而平，发现在会话装配时一次完成（compose-agents.ts）。
+ */
+import type { AgentDefinition, AgentSource } from "./types.js";
+export interface AgentDirSource {
+    dir: string;
+    source: AgentSource;
+    requiresTrust: boolean;
+}
+export interface AgentDirSources {
+    cwd: string;
+    /** 用户级配置目录（`~/.config/ama`）。 */
+    configDir: string;
+    /** `--agent-dir` 与 profile `agentDirs`（已按顺序合并）。 */
+    cliDirs?: readonly string[];
+    /** config `agents.dirs`。 */
+    configDirs?: readonly string[];
+}
+export interface AgentDiscovery {
+    agents: AgentDefinition[];
+    warnings: string[];
+    /** 因未信任而跳过的目录（存在的才列出）。 */
+    skippedUntrusted: string[];
+}
+export declare function agentSources(options: AgentDirSources): AgentDirSource[];
+export declare function discoverAgents(sources: readonly AgentDirSource[], options: {
+    trusted: boolean;
+}): AgentDiscovery;

package/dist/agents/discover.js

@@ -0,0 +1,83 @@
+/**
+ * 子 Agent 定义发现（docs/wave5-plan.md §7.1，D22）。[W5-G]
+ *
+ * 顺序：`--agent-dir`（可重复，profile `agentDirs` 由启动步骤并在其后）→ config `agents.dirs` →
+ * `<configDir>/agents/*.md`（用户级）→ `<cwd>/.ama/agents/*.md`（项目级，需信任；未信任跳过并记入
+ * `skippedUntrusted`）。每个来源目录只看直接下层的 `*.md`（按名排序）；同名先发现者胜并 warning。
+ * 内置类型（builtin.ts）由 catalog.ts 合并，可被这里发现的同名定义覆盖。
+ *
+ * 同步实现：定义目录小而平，发现在会话装配时一次完成（compose-agents.ts）。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseAgentDefinition } from "./parse.js";
+export function agentSources(options) {
+    const out = [];
+    const add = (dir, source, requiresTrust) => out.push({ dir: resolve(options.cwd, dir), source, requiresTrust });
+    for (const dir of options.cliDirs ?? [])
+        add(dir, "cli", false);
+    for (const dir of options.configDirs ?? [])
+        add(dir, "user", false);
+    add(join(options.configDir, "agents"), "user", false);
+    add(join(options.cwd, ".ama", "agents"), "project", true);
+    return out;
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function markdownFiles(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+            .map((entry) => entry.name)
+            .sort()
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+export function discoverAgents(sources, options) {
+    const result = { agents: [], warnings: [], skippedUntrusted: [] };
+    const byName = new Map();
+    const seen = new Set();
+    for (const source of sources) {
+        if (seen.has(source.dir))
+            continue;
+        seen.add(source.dir);
+        if (!isDir(source.dir))
+            continue;
+        if (source.requiresTrust && !options.trusted) {
+            result.skippedUntrusted.push(source.dir);
+            continue;
+        }
+        for (const file of markdownFiles(source.dir)) {
+            let text;
+            try {
+                text = readFileSync(file, "utf8");
+            }
+            catch (error) {
+                result.warnings.push(`${file}: ${error.message}`);
+                continue;
+            }
+            const parsed = parseAgentDefinition(text, file, source.source);
+            result.warnings.push(...parsed.warnings);
+            const agent = parsed.agent;
+            if (agent === undefined)
+                continue;
+            const existing = byName.get(agent.name);
+            if (existing !== undefined) {
+                result.warnings.push(`${file}: agent "${agent.name}" already defined at ${existing.filePath ?? existing.source}; ignored`);
+                continue;
+            }
+            byName.set(agent.name, agent);
+            result.agents.push(agent);
+        }
+    }
+    return result;
+}

package/dist/agents/external.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
+ *
+ * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
+ *   描述在会话内字节不变）。
+ * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
+ *   与 auto 分类器）；有宿主时不自 spawn（D17），只认宿主注入的。
+ * - 首次在本会话以某个外部 Agent 运行：一次 `execute` 类确认「将以你在 X 的现有登录运行，模式 Y」——
+ *   deny 规则 `task(<id>)` 拒绝；allow 规则 `task` / `task(<id>)` 或 full-auto 放行；allowlist 与无人值守
+ *   拒绝；其余问人。宿主 runner 不问（宿主自己管审批）。
+ * - 句柄包一层：被 stop 的外部任务续聊时以外部会话 id `resume` 重开。
+ * - `/agents`、RPC `get_agents` 的外部部分要探测（异步），这里按会话缓存，启动与变化时刷新。
+ */
+import type { SessionCore } from "../agent/session-core.js";
+import { type AgentsConfig } from "../config/types-w5.js";
+import { ExternalAgents } from "../drivers/agents.js";
+import type { DriverDeps } from "../drivers/base.js";
+import type { HostRunnerRegistry } from "../drivers/host-runners.js";
+import type { HostRunner } from "../host/types.js";
+import type { SubagentRunner } from "../tools/types.js";
+import type { AgentCatalog } from "./catalog.js";
+import type { AgentDefinition, AgentInfo } from "./types.js";
+/** 启动时按 PATH 登记进 task 描述的外部 Agent。 */
+export declare const LISTED_EXTERNAL_AGENTS: readonly ["claude", "codex"];
+/** 关闭外部 Agent 的 PATH 探测与版本探测（测试；`/agents` 只列类型目录）。 */
+export declare const NO_AGENT_PROBE_ENV = "AMA_NO_AGENT_PROBE";
+/** 测试注入（spawn / probe）：进程内对端代替真实子进程。生产代码不设置。 */
+export declare const externalTesting: {
+    driverDeps?: DriverDeps;
+};
+/** 是不是外部 Agent 的名字（`claude` / `codex` / `acp:<program>` / 驱动表 id，`ama` 除外）。 */
+export declare function isExternalSpec(name: string): boolean;
+/** 外部 CLI 的类型（`task(agent="claude")`）。 */
+export declare function externalDefinition(spec: string): AgentDefinition;
+export declare function hostDefinition(runner: HostRunner): AgentDefinition;
+/** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
+export declare function externalOnPath(spec: string, env: NodeJS.ProcessEnv): boolean;
+export interface ExternalWiring {
+    env: NodeJS.ProcessEnv;
+    /** 有宿主适配器：不自 spawn 外部 CLI（D17）。 */
+    hosted: boolean;
+    hostRunners?: HostRunnerRegistry;
+    dataDir?: string;
+    config?: AgentsConfig;
+    /** config `subagents.defaultModel`：那是 ama 的模型，不传给外部 CLI。 */
+    defaultModel?: string;
+    /** 项目是否已被 ama 信任。 */
+    trusted: boolean;
+    /** PATH 与版本探测（`AMA_NO_AGENT_PROBE=1` 关闭）。 */
+    probe: boolean;
+}
+/** 启动时登记：PATH 上的 claude / codex（无宿主时）与已注入的宿主 runner；其余按需解析。 */
+export declare function registerExternalAgents(catalog: AgentCatalog, wiring: ExternalWiring): void;
+/** RPC `get_agents` / `/agents`：会话的类型与外部 Agent（含安装与版本）；未缓存返回 undefined。 */
+export declare function cachedAgentInfos(sessionId: string): AgentInfo[] | undefined;
+/** 合并：类型目录在前；外部探测结果补 installed / version，目录里没有的追加在后。 */
+export declare function mergeAgentInfos(base: readonly AgentInfo[], external: readonly AgentInfo[]): AgentInfo[];
+/** 一个主会话的外部 Agent 入口（`SubagentEnvironment.runners` 的实现）。 */
+export declare class SessionExternalAgents {
+    private readonly core;
+    private readonly wiring;
+    private readonly catalog;
+    readonly agents: ExternalAgents;
+    private readonly approved;
+    private readonly pending;
+    private disposed;
+    private unsubscribe;
+    constructor(core: SessionCore, wiring: ExternalWiring, catalog: AgentCatalog);
+    private mode;
+    /** 注册表的 `runners(agent)`：ama 子会话类型返回 undefined。 */
+    runner(agent: AgentDefinition): SubagentRunner | undefined;
+    /** 发给外部 runner 的请求：去掉 ama 自己的缺省模型（`subagents.defaultModel`）。 */
+    private forward;
+    /** 首次在本会话以 `spec` 运行的确认（同一 Agent 并发的首次只问一次）。 */
+    private firstRun;
+    private confirm;
+    /** 重新探测并缓存 `/agents` 的数据（不阻塞；会话关闭后不再写）。 */
+    refreshInfos(): Promise<AgentInfo[]>;
+    dispose(): void;
+}

package/dist/agents/external.js

@@ -0,0 +1,326 @@
+/**
+ * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
+ *
+ * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
+ *   描述在会话内字节不变）。
+ * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
+ *   与 auto 分类器）；有宿主时不自 spawn（D17），只认宿主注入的。
+ * - 首次在本会话以某个外部 Agent 运行：一次 `execute` 类确认「将以你在 X 的现有登录运行，模式 Y」——
+ *   deny 规则 `task(<id>)` 拒绝；allow 规则 `task` / `task(<id>)` 或 full-auto 放行；allowlist 与无人值守
+ *   拒绝；其余问人。宿主 runner 不问（宿主自己管审批）。
+ * - 句柄包一层：被 stop 的外部任务续聊时以外部会话 id `resume` 重开。
+ * - `/agents`、RPC `get_agents` 的外部部分要探测（异步），这里按会话缓存，启动与变化时刷新。
+ */
+import { randomUUID } from "node:crypto";
+import { requestApproval } from "../agent/session-tools.js";
+import { agentEntry } from "../config/types-w5.js";
+import { ExternalAgents } from "../drivers/agents.js";
+import { candidatesFor, catalogEntry } from "../drivers/catalog.js";
+import { clampMode } from "../drivers/permissions.js";
+import { findOnPath } from "../drivers/probe.js";
+import { createAgentStore } from "../drivers/store.js";
+import { AmaError } from "../errors.js";
+import { findAllowRule, findDenyRule } from "../permissions/rules.js";
+/** 启动时按 PATH 登记进 task 描述的外部 Agent。 */
+export const LISTED_EXTERNAL_AGENTS = ["claude", "codex"];
+/** 关闭外部 Agent 的 PATH 探测与版本探测（测试；`/agents` 只列类型目录）。 */
+export const NO_AGENT_PROBE_ENV = "AMA_NO_AGENT_PROBE";
+/** 测试注入（spawn / probe）：进程内对端代替真实子进程。生产代码不设置。 */
+export const externalTesting = {};
+/** 是不是外部 Agent 的名字（`claude` / `codex` / `acp:<program>` / 驱动表 id，`ama` 除外）。 */
+export function isExternalSpec(name) {
+    if (name === "ama")
+        return false;
+    if (name.startsWith("acp:"))
+        return name.slice(4).trim() !== "";
+    return catalogEntry(name) !== undefined;
+}
+function labelOf(spec) {
+    return (catalogEntry(spec)?.label ?? (spec.startsWith("acp:") ? `ACP agent ${spec.slice(4)}` : spec));
+}
+function definition(name, runner, description, source) {
+    return {
+        name,
+        description,
+        permissionMode: "inherit",
+        model: "inherit",
+        maxTurns: 30,
+        isolation: "none",
+        background: false,
+        // 驱动表 id（gemini 等）与宿主 id 不在 AgentRunnerSpec 的字面量里，线上照样是字符串
+        runner: runner,
+        prompt: "",
+        source,
+    };
+}
+/** 外部 CLI 的类型（`task(agent="claude")`）。 */
+export function externalDefinition(spec) {
+    return definition(spec, spec, `External ${labelOf(spec)} CLI (its own login, model and permission policy; full instructions in prompt).`, "builtin");
+}
+export function hostDefinition(runner) {
+    return definition(runner.id, runner.id, runner.description, "host");
+}
+/** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
+export function externalOnPath(spec, env) {
+    const found = candidatesFor(spec);
+    return found?.candidates.some((c) => findOnPath(c.program, env) !== undefined) ?? false;
+}
+/** 启动时登记：PATH 上的 claude / codex（无宿主时）与已注入的宿主 runner；其余按需解析。 */
+export function registerExternalAgents(catalog, wiring) {
+    for (const runner of wiring.hostRunners?.list() ?? [])
+        catalog.add(hostDefinition(runner));
+    if (!wiring.hosted && wiring.probe)
+        for (const spec of LISTED_EXTERNAL_AGENTS)
+            if (externalOnPath(spec, wiring.env))
+                catalog.add(externalDefinition(spec));
+    catalog.setResolver((name) => {
+        const hosted = wiring.hostRunners?.get(name);
+        if (hosted !== undefined)
+            return hostDefinition(hosted);
+        return isExternalSpec(name) ? externalDefinition(name) : undefined;
+    });
+}
+/** 续聊时能重开的句柄：被 stop 的外部会话以 `resume` 接上（同一任务、同一外部会话）。 */
+class ExternalTaskHandle {
+    inner;
+    reopen;
+    stopped = false;
+    constructor(inner, reopen) {
+        this.inner = inner;
+        this.reopen = reopen;
+    }
+    get id() {
+        return this.inner.id;
+    }
+    async send(text) {
+        if (!this.stopped) {
+            try {
+                await this.inner.send(text);
+                return;
+            }
+            catch (error) {
+                if (!(error instanceof AmaError) || error.code !== "agent_closed")
+                    throw error;
+            }
+        }
+        if (this.inner.id === "")
+            throw new AmaError("agent_closed", "外部 Agent 会话没有建立，不能续聊");
+        this.inner = await this.reopen(this.inner.id, text);
+        this.stopped = false;
+    }
+    wait() {
+        return this.inner.wait();
+    }
+    async stop() {
+        this.stopped = true;
+        await this.inner.stop();
+    }
+}
+/**
+ * 启动返回前到达的进度事件（第一回合的 `turn` 等）推迟到注册表发出 `subagent_start` 之后：
+ * 注册表在 `start()` resolve 后的微任务里发 start，这里在下一个宏任务再放行。
+ */
+function deferEvents(request) {
+    let queue = [];
+    const onEvent = (event) => {
+        if (queue !== undefined)
+            queue.push(event);
+        else
+            request.onEvent(event);
+    };
+    return {
+        request: { ...request, onEvent },
+        release() {
+            setImmediate(() => {
+                const pending = queue ?? [];
+                queue = undefined;
+                for (const event of pending)
+                    request.onEvent(event);
+            });
+        },
+    };
+}
+const infoCache = new Map();
+/** RPC `get_agents` / `/agents`：会话的类型与外部 Agent（含安装与版本）；未缓存返回 undefined。 */
+export function cachedAgentInfos(sessionId) {
+    return infoCache.get(sessionId);
+}
+/** 合并：类型目录在前；外部探测结果补 installed / version，目录里没有的追加在后。 */
+export function mergeAgentInfos(base, external) {
+    const out = base.map((info) => ({ ...info }));
+    for (const raw of external) {
+        // 驱动表里的 ama 经 ACP 驱动，名字是 acp:ama（裸 ama 是子会话类型的 runner 名）
+        const probe = raw.name === "ama" ? { ...raw, name: "acp:ama", runner: "acp:ama" } : raw;
+        const known = out.find((info) => info.name === probe.name);
+        if (known === undefined) {
+            out.push({ ...probe });
+            continue;
+        }
+        if (probe.installed !== undefined)
+            known.installed = probe.installed;
+        if (probe.version !== undefined)
+            known.version = probe.version;
+    }
+    return out;
+}
+/** 一个主会话的外部 Agent 入口（`SubagentEnvironment.runners` 的实现）。 */
+export class SessionExternalAgents {
+    core;
+    wiring;
+    catalog;
+    agents;
+    approved = new Set();
+    pending = new Map();
+    disposed = false;
+    unsubscribe;
+    constructor(core, wiring, catalog) {
+        this.core = core;
+        this.wiring = wiring;
+        this.catalog = catalog;
+        const store = createAgentStore({
+            appendCustom: (customType, data) => void core.appendEntry({ type: "custom", customType, data }),
+            entries: () => core.manager.branch(),
+        });
+        const driverDeps = externalTesting.driverDeps;
+        this.agents = new ExternalAgents({
+            env: wiring.env,
+            cwd: core.cwd,
+            hosted: wiring.hosted,
+            ...(wiring.hostRunners !== undefined ? { hostRunners: wiring.hostRunners } : {}),
+            ...(wiring.dataDir !== undefined ? { dataDir: wiring.dataDir } : {}),
+            ...(wiring.config !== undefined ? { config: wiring.config } : {}),
+            approve: (request, signal) => requestApproval(core, request, signal),
+            store,
+            parentMode: () => this.mode(),
+            unattended: () => core.options.unattended === true,
+            trusted: () => wiring.trusted,
+            ...(driverDeps !== undefined ? { driverDeps } : {}),
+            log: (level, message) => core.log(level, message),
+        });
+        this.unsubscribe = wiring.hostRunners?.onChange(() => void this.refreshInfos());
+    }
+    mode() {
+        return this.core.options.permission?.mode ?? "default";
+    }
+    /** 注册表的 `runners(agent)`：ama 子会话类型返回 undefined。 */
+    runner(agent) {
+        if (agent.runner === "ama")
+            return undefined;
+        const spec = agent.runner;
+        const host = this.wiring.hostRunners?.get(spec);
+        let inner;
+        try {
+            inner = this.agents.resolve(spec);
+        }
+        catch (error) {
+            // 不可用的原因（宿主环境、未知 id）作为任务失败的说明返回给模型
+            return { id: spec, start: () => Promise.reject(error) };
+        }
+        return {
+            id: inner.id,
+            start: async (request) => {
+                if (host === undefined)
+                    await this.firstRun(spec, request);
+                const events = deferEvents(request);
+                const handle = await inner.start(this.forward(spec, events.request));
+                events.release();
+                void handle.wait().finally(() => void this.refreshInfos());
+                if (host !== undefined)
+                    return handle;
+                const reopen = async (resume, prompt) => {
+                    return inner.start({
+                        ...this.forward(spec, request),
+                        prompt,
+                        resume,
+                        mode: this.mode(),
+                        signal: new AbortController().signal,
+                    });
+                };
+                return new ExternalTaskHandle(handle, reopen);
+            },
+        };
+    }
+    /** 发给外部 runner 的请求：去掉 ama 自己的缺省模型（`subagents.defaultModel`）。 */
+    forward(spec, request) {
+        const own = agentEntry(this.wiring.config, spec)?.model;
+        if (request.model !== undefined &&
+            request.model === this.wiring.defaultModel &&
+            request.model !== own) {
+            const { model: _ama, ...rest } = request;
+            return rest;
+        }
+        return request;
+    }
+    /** 首次在本会话以 `spec` 运行的确认（同一 Agent 并发的首次只问一次）。 */
+    firstRun(spec, request) {
+        if (this.approved.has(spec))
+            return Promise.resolve();
+        let pending = this.pending.get(spec);
+        if (pending === undefined) {
+            pending = this.confirm(spec, request).finally(() => this.pending.delete(spec));
+            this.pending.set(spec, pending);
+        }
+        return pending;
+    }
+    async confirm(spec, request) {
+        const core = this.core;
+        const mode = this.mode();
+        const rules = core.options.permission?.rules ?? [];
+        const subject = { command: spec };
+        const label = labelOf(spec);
+        if (findDenyRule(rules, "task", subject, core.cwd) !== undefined)
+            throw new AmaError("permission_denied", `A deny rule blocks running ${label} (task(${spec})).`);
+        let decision = findAllowRule(rules, "task", subject, core.cwd) !== undefined || mode === "full-auto"
+            ? "allow"
+            : mode === "allowlist"
+                ? "deny"
+                : "ask";
+        if (decision === "ask" && core.options.unattended === true)
+            decision = "deny";
+        if (decision === "deny")
+            throw new AmaError("permission_denied", `Running ${label} needs approval the first time in a session, and nobody can approve it here. ` +
+                `Add an allow rule task(${spec}) to permit it.`);
+        if (decision === "ask") {
+            const effective = clampMode(request.mode, mode, agentEntry(this.wiring.config, spec)?.maxMode);
+            const approval = {
+                requestId: randomUUID(),
+                toolName: "task",
+                input: {
+                    agent: spec,
+                    mode: effective,
+                    note: `Runs ${label} with your existing login in that CLI (mode ${effective}).`,
+                },
+                reason: "mode",
+                context: { depth: 0, ...(request.taskId !== undefined ? { taskId: request.taskId } : {}) },
+            };
+            const answer = await requestApproval(core, approval, request.signal);
+            if (answer === "deny")
+                throw new AmaError("permission_denied", `The user declined running ${label}.`);
+        }
+        this.approved.add(spec);
+    }
+    /** 重新探测并缓存 `/agents` 的数据（不阻塞；会话关闭后不再写）。 */
+    async refreshInfos() {
+        const base = this.catalog.infos();
+        let external = [];
+        if (this.wiring.probe || this.wiring.hosted) {
+            try {
+                external = await this.agents.list();
+            }
+            catch (error) {
+                this.core.log("warn", `external agent probe failed: ${String(error)}`);
+            }
+        }
+        const merged = mergeAgentInfos(base, external);
+        if (!this.disposed)
+            infoCache.set(this.core.manager.id, merged);
+        return merged;
+    }
+    dispose() {
+        this.disposed = true;
+        this.unsubscribe?.();
+        infoCache.delete(this.core.manager.id);
+    }
+}

package/dist/agents/parse.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 子 Agent 定义文件解析（docs/wave5-plan.md §7.1，D22）。[W5-G]
+ *
+ * 一个 `*.md` = 一个类型：frontmatter 与 Skill 同一套 YAML 子集（skills/frontmatter.ts），字段名
+ * kebab-case；正文 = 追加到子会话系统提示末尾的角色说明。不合格的文件不加载并给出 warning（拼错的
+ * 字段比静默按缺省运行更容易发现）。不支持的字段（`hooks`、`mcpServers`、`memory`、`color`、
+ * `initialPrompt`、`skills`）与未知字段忽略。
+ */
+import type { AgentDefinition, AgentSource } from "./types.js";
+export declare const AGENT_NAME_RE: RegExp;
+export declare const MAX_AGENT_DESCRIPTION = 1024;
+export declare const DEFAULT_AGENT_MAX_TURNS = 30;
+export interface ParsedAgent {
+    agent?: AgentDefinition;
+    warnings: string[];
+}
+/** 解析一份定义文件；`filePath` 用于缺省名与 warning。 */
+export declare function parseAgentDefinition(text: string, filePath: string, source: AgentSource): ParsedAgent;