@armadra/agent 0.4.0 → 0.5.1

package/dist/drivers/pool.js

@@ -0,0 +1,96 @@
+/**
+ * 外部 Agent 并发池（docs/wave5-plan.md §5.4 并发）。[W5-E]
+ *
+ * 总并发 `agents.maxConcurrent`（缺省 3）+ 每个 Agent 的上限 `agents.<id>.maxConcurrent`
+ * （claude 缺省 2：订阅有速率限制）；超出排队（先来先得），排队可被 abort。与 ama 自己的
+ * `SubagentPool`（子会话）分开计数。
+ */
+import { AmaError } from "../errors.js";
+import { agentEntry } from "../config/types-w5.js";
+export const DEFAULT_MAX_CONCURRENT = 3;
+export const DEFAULT_PER_AGENT = { claude: 2 };
+export class DriverPool {
+    maxTotal;
+    perAgent;
+    active = new Map();
+    total = 0;
+    queue = [];
+    constructor(maxTotal = DEFAULT_MAX_CONCURRENT, perAgent = () => undefined) {
+        this.maxTotal = maxTotal;
+        this.perAgent = perAgent;
+    }
+    running(agentId) {
+        return agentId === undefined ? this.total : (this.active.get(agentId) ?? 0);
+    }
+    queued() {
+        return this.queue.length;
+    }
+    limitFor(agentId) {
+        return this.perAgent(agentId) ?? this.maxTotal;
+    }
+    canRun(agentId) {
+        return this.total < this.maxTotal && this.running(agentId) < this.limitFor(agentId);
+    }
+    take(agentId) {
+        this.total += 1;
+        this.active.set(agentId, this.running(agentId) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.total -= 1;
+            this.active.set(agentId, this.running(agentId) - 1);
+            this.drain();
+        };
+    }
+    drain() {
+        for (let i = 0; i < this.queue.length;) {
+            const waiter = this.queue[i];
+            if (this.canRun(waiter.agentId)) {
+                this.queue.splice(i, 1);
+                waiter.grant(this.take(waiter.agentId));
+            }
+            else
+                i++;
+        }
+    }
+    /** 拿到一个名额（返回释放函数）；abort 时离开队列并以 `aborted` 失败。 */
+    acquire(agentId, signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(abortedError());
+        // 有空位时，排队的只可能是卡在各自上限上的其它 Agent：同一 Agent 已有人排队就跟在后面
+        if (this.canRun(agentId) && !this.queue.some((w) => w.agentId === agentId))
+            return Promise.resolve(this.take(agentId));
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const at = this.queue.indexOf(waiter);
+                if (at >= 0)
+                    this.queue.splice(at, 1);
+                reject(abortedError());
+            };
+            const waiter = {
+                agentId,
+                grant: (release) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve(release);
+                },
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.queue.push(waiter);
+        });
+    }
+}
+function abortedError() {
+    return new AmaError("aborted", "外部 Agent 排队时被中断");
+}
+/** 按配置建池（`agents.maxConcurrent`、`agents.<id>.maxConcurrent`）。 */
+export function poolFromConfig(config) {
+    const total = typeof config?.maxConcurrent === "number" && config.maxConcurrent > 0
+        ? config.maxConcurrent
+        : DEFAULT_MAX_CONCURRENT;
+    return new DriverPool(total, (agentId) => {
+        const own = agentEntry(config, agentId)?.maxConcurrent;
+        return typeof own === "number" && own > 0 ? own : DEFAULT_PER_AGENT[agentId];
+    });
+}

package/dist/drivers/probe.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 外部 Agent 的探测（docs/wave5-plan.md §5.1 probe.ts）。[W5-E]
+ *
+ * - PATH 查找不起 shell：逐个目录拼程序名（Windows 加 PATHEXT 后缀）；绝对 / 相对路径直接认。
+ * - 版本：`<program> --version` 取第一个 `x.y.z`，5 s 超时，不联网、不计费。
+ * - 缓存：每进程一次（内存）；可选写 `<dataDir>/drivers.json`（按路径 + mtime 失效）。
+ */
+export declare const VERSION_TIMEOUT_MS = 5000;
+export interface LocatedProgram {
+    path: string;
+    version?: string;
+}
+export interface ProbeDeps {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    platform?: NodeJS.Platform;
+    /** 缺省：存在且是文件。 */
+    isFile?(path: string): boolean;
+    /** 缺省：execFile `<path> <args>`，返回 stdout + stderr；失败返回 undefined。 */
+    runVersion?(path: string, args: readonly string[]): Promise<string | undefined>;
+    /** `<dataDir>/drivers.json`；不给则只做内存缓存。 */
+    cacheFile?: string;
+}
+/** 在 PATH 里找程序；找不到返回 undefined。 */
+export declare function findOnPath(program: string, env: NodeJS.ProcessEnv, options?: {
+    platform?: NodeJS.Platform;
+    cwd?: string;
+    isFile?(path: string): boolean;
+}): string | undefined;
+/** 文本里第一个 `x.y.z`（可带预发布后缀）。 */
+export declare function parseVersion(text: string): string | undefined;
+/** 版本区间：空格分隔的 `>=x.y.z` / `<x.y.z` / `>` / `<=` / `=`；全部满足为真。 */
+export declare function versionSatisfies(version: string, range: string): boolean;
+export declare class ProgramProbe {
+    private readonly deps;
+    private readonly memo;
+    private readonly captured;
+    constructor(deps: ProbeDeps);
+    /** 找程序并取版本；同一进程同一程序只探一次。 */
+    locate(program: string, versionArgs?: readonly string[]): Promise<LocatedProgram | undefined>;
+    /** 跑一次 `<path> <args>` 取输出（如 `--help`，不联网、不计费）；每进程每组参数一次。 */
+    capture(path: string, args: readonly string[]): Promise<string | undefined>;
+    private locateNow;
+    private mtime;
+    private readCache;
+    private writeCache;
+}

package/dist/drivers/probe.js

@@ -0,0 +1,172 @@
+/**
+ * 外部 Agent 的探测（docs/wave5-plan.md §5.1 probe.ts）。[W5-E]
+ *
+ * - PATH 查找不起 shell：逐个目录拼程序名（Windows 加 PATHEXT 后缀）；绝对 / 相对路径直接认。
+ * - 版本：`<program> --version` 取第一个 `x.y.z`，5 s 超时，不联网、不计费。
+ * - 缓存：每进程一次（内存）；可选写 `<dataDir>/drivers.json`（按路径 + mtime 失效）。
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { commandLine } from "./process.js";
+export const VERSION_TIMEOUT_MS = 5_000;
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** 在 PATH 里找程序；找不到返回 undefined。 */
+export function findOnPath(program, env, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const isFile = options.isFile ?? defaultIsFile;
+    const exts = platform === "win32"
+        ? ["", ...(env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
+        : [""];
+    const candidates = (base) => exts.map((ext) => base + ext.toLowerCase());
+    if (isAbsolute(program) || program.includes("/") || program.includes("\\")) {
+        const base = resolve(options.cwd ?? process.cwd(), program);
+        return candidates(base).find(isFile);
+    }
+    const path = env["PATH"] ?? env["Path"] ?? "";
+    const sep = platform === "win32" ? ";" : delimiter;
+    for (const dir of path.split(sep)) {
+        if (dir === "")
+            continue;
+        const hit = candidates(join(dir, program)).find(isFile);
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+/** 文本里第一个 `x.y.z`（可带预发布后缀）。 */
+export function parseVersion(text) {
+    return /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(text)?.[1];
+}
+function compare(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** 版本区间：空格分隔的 `>=x.y.z` / `<x.y.z` / `>` / `<=` / `=`；全部满足为真。 */
+export function versionSatisfies(version, range) {
+    for (const part of range.trim().split(/\s+/)) {
+        const m = /^(>=|<=|>|<|=)?(\d+\.\d+\.\d+)$/.exec(part);
+        if (m === null)
+            continue;
+        const c = compare(version, m[2]);
+        const op = m[1] ?? "=";
+        const ok = op === ">="
+            ? c >= 0
+            : op === "<="
+                ? c <= 0
+                : op === ">"
+                    ? c > 0
+                    : op === "<"
+                        ? c < 0
+                        : c === 0;
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+function defaultRunVersion(env, platform) {
+    return (path, args) => new Promise((done) => {
+        const line = commandLine({ program: path, args, env }, platform);
+        execFile(line.file, line.args, {
+            env,
+            timeout: VERSION_TIMEOUT_MS,
+            windowsHide: true,
+            windowsVerbatimArguments: line.verbatim,
+        }, (error, stdout, stderr) => done(error !== null && stdout === "" ? undefined : `${stdout}${stderr}`));
+    });
+}
+export class ProgramProbe {
+    deps;
+    memo = new Map();
+    captured = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 找程序并取版本；同一进程同一程序只探一次。 */
+    locate(program, versionArgs = ["--version"]) {
+        const key = `${program}\0${versionArgs.join(" ")}`;
+        let hit = this.memo.get(key);
+        if (hit === undefined) {
+            hit = this.locateNow(program, versionArgs);
+            this.memo.set(key, hit);
+        }
+        return hit;
+    }
+    /** 跑一次 `<path> <args>` 取输出（如 `--help`，不联网、不计费）；每进程每组参数一次。 */
+    capture(path, args) {
+        const key = `capture\0${path}\0${args.join(" ")}`;
+        let hit = this.captured.get(key);
+        if (hit === undefined) {
+            const platform = this.deps.platform ?? process.platform;
+            const run = this.deps.runVersion ?? defaultRunVersion(this.deps.env, platform);
+            hit = run(path, args).catch(() => undefined);
+            this.captured.set(key, hit);
+        }
+        return hit;
+    }
+    async locateNow(program, versionArgs) {
+        const platform = this.deps.platform ?? process.platform;
+        const path = findOnPath(program, this.deps.env, {
+            platform,
+            ...(this.deps.cwd !== undefined ? { cwd: this.deps.cwd } : {}),
+            ...(this.deps.isFile !== undefined ? { isFile: this.deps.isFile } : {}),
+        });
+        if (path === undefined)
+            return undefined;
+        const mtimeMs = this.mtime(path);
+        const cached = this.readCache()[path];
+        if (cached !== undefined && cached.mtimeMs === mtimeMs)
+            return { path, ...(cached.version !== undefined ? { version: cached.version } : {}) };
+        const run = this.deps.runVersion ?? defaultRunVersion(this.deps.env, platform);
+        const output = await run(path, versionArgs).catch(() => undefined);
+        const version = output === undefined ? undefined : parseVersion(output);
+        this.writeCache(path, { mtimeMs, ...(version !== undefined ? { version } : {}) });
+        return { path, ...(version !== undefined ? { version } : {}) };
+    }
+    mtime(path) {
+        try {
+            return statSync(path).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    readCache() {
+        const file = this.deps.cacheFile;
+        if (file === undefined || !existsSync(file))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            return parsed.programs ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    writeCache(path, entry) {
+        const file = this.deps.cacheFile;
+        if (file === undefined)
+            return;
+        try {
+            const programs = { ...this.readCache(), [path]: entry };
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, `${JSON.stringify({ version: 1, programs }, null, 2)}\n`);
+        }
+        catch {
+            // 缓存写不进去不影响探测
+        }
+    }
+}

package/dist/drivers/process.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 外部 Agent 子进程（docs/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
+ *
+ * - POSIX 以 `detached` 自成进程组，结束时 `killProcessTree`（SIGTERM → 宽限 → SIGKILL）；
+ *   登记到 `tools/process-tree.ts`，ama 退出时同步清掉仍存活的组。
+ * - Windows 上 npm 装的 CLI 是 `.cmd` 垫片，Node 不允许直接 spawn，改经 `cmd.exe /d /s /c`。
+ * - stderr 只保留尾部 8 KB 供诊断（不落盘、不进会话，§5.4 敏感数据）。
+ * - 测试与宿主可注入 {@link SpawnTransport}（内存流），驱动不关心对端是不是真进程。
+ */
+import { type ProcessDeps } from "../tools/process-tree.js";
+export declare const STDERR_TAIL_BYTES: number;
+/** 关 stdin 之后等进程自己退出的时间，过了再杀进程树。 */
+export declare const STDIN_CLOSE_GRACE_MS = 2000;
+export interface TransportSpec {
+    program: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export interface AgentTransport {
+    readonly stdin: NodeJS.WritableStream;
+    readonly stdout: NodeJS.ReadableStream;
+    readonly pid?: number;
+    /** stderr 尾部（≤ 8 KB）。 */
+    stderrTail(): string;
+    /** 进程结束（退出码；信号退出为 null）。 */
+    readonly exited: Promise<number | null>;
+    /** 关 stdin → 等 `graceMs` → 杀进程树。幂等。 */
+    terminate(graceMs?: number): Promise<void>;
+}
+export type SpawnTransport = (spec: TransportSpec) => AgentTransport;
+export interface SpawnDeps {
+    platform?: NodeJS.Platform;
+    process?: ProcessDeps;
+    /** 进程起来 / 结束时回调（pid 登记，§5.4 孤儿进程）。 */
+    onSpawn?(pid: number, spec: TransportSpec): void;
+    onExit?(pid: number): void;
+}
+/** Windows `.cmd` / `.bat` 垫片改经 cmd.exe；其余原样。 */
+export declare function commandLine(spec: Pick<TransportSpec, "program" | "args" | "env">, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    verbatim: boolean;
+};
+/** 起真实子进程。spawn 失败（程序不存在等）时 `exited` 以 -1 结束、stdout 立即结束。 */
+export declare function spawnTransport(spec: TransportSpec, deps?: SpawnDeps): AgentTransport;
+/** 最近一段 stderr，单行化后截断（放进错误信息）。 */
+export declare function stderrHint(transport: AgentTransport, max?: number): string;

package/dist/drivers/process.js

@@ -0,0 +1,100 @@
+/**
+ * 外部 Agent 子进程（docs/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
+ *
+ * - POSIX 以 `detached` 自成进程组，结束时 `killProcessTree`（SIGTERM → 宽限 → SIGKILL）；
+ *   登记到 `tools/process-tree.ts`，ama 退出时同步清掉仍存活的组。
+ * - Windows 上 npm 装的 CLI 是 `.cmd` 垫片，Node 不允许直接 spawn，改经 `cmd.exe /d /s /c`。
+ * - stderr 只保留尾部 8 KB 供诊断（不落盘、不进会话，§5.4 敏感数据）。
+ * - 测试与宿主可注入 {@link SpawnTransport}（内存流），驱动不关心对端是不是真进程。
+ */
+import { spawn } from "node:child_process";
+import { killProcessTree, trackProcessGroup, untrackProcessGroup, } from "../tools/process-tree.js";
+export const STDERR_TAIL_BYTES = 8 * 1024;
+/** 关 stdin 之后等进程自己退出的时间，过了再杀进程树。 */
+export const STDIN_CLOSE_GRACE_MS = 2_000;
+function quoteCmd(arg) {
+    return /[\s"&|<>^%]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+/** Windows `.cmd` / `.bat` 垫片改经 cmd.exe；其余原样。 */
+export function commandLine(spec, platform = process.platform) {
+    if (platform === "win32" && /\.(cmd|bat)$/i.test(spec.program)) {
+        const shell = spec.env["ComSpec"] ?? spec.env["COMSPEC"] ?? "cmd.exe";
+        const line = [spec.program, ...spec.args].map(quoteCmd).join(" ");
+        return { file: shell, args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+    }
+    return { file: spec.program, args: [...spec.args], verbatim: false };
+}
+/** 起真实子进程。spawn 失败（程序不存在等）时 `exited` 以 -1 结束、stdout 立即结束。 */
+export function spawnTransport(spec, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const line = commandLine(spec, platform);
+    let tail = "";
+    let resolveExit;
+    const exited = new Promise((resolve) => (resolveExit = resolve));
+    const child = spawn(line.file, line.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: platform !== "win32",
+        windowsHide: true,
+        windowsVerbatimArguments: line.verbatim,
+    });
+    const pid = child.pid;
+    if (pid !== undefined) {
+        if (platform !== "win32")
+            trackProcessGroup(pid);
+        deps.onSpawn?.(pid, spec);
+    }
+    child.stderr?.on("data", (chunk) => {
+        tail = (tail + chunk.toString("utf8")).slice(-STDERR_TAIL_BYTES);
+    });
+    // 写一个已退出进程的 stdin 会 EPIPE；交给 exited 处理，不让它变成未捕获异常
+    child.stdin?.on("error", () => undefined);
+    child.on("error", (error) => {
+        tail = `${tail}\n${error.message}`.slice(-STDERR_TAIL_BYTES);
+        child.stdout?.destroy();
+        finish(-1);
+    });
+    let done = false;
+    const finish = (code) => {
+        if (done)
+            return;
+        done = true;
+        if (pid !== undefined) {
+            untrackProcessGroup(pid);
+            deps.onExit?.(pid);
+        }
+        resolveExit(code);
+    };
+    child.on("close", (code) => finish(code));
+    let terminating;
+    return {
+        stdin: child.stdin,
+        stdout: child.stdout,
+        ...(pid !== undefined ? { pid } : {}),
+        stderrTail: () => tail,
+        exited,
+        terminate(graceMs = STDIN_CLOSE_GRACE_MS) {
+            terminating ??= (async () => {
+                if (done)
+                    return;
+                child.stdin?.end();
+                const timer = new Promise((resolve) => setTimeout(() => resolve("timeout"), graceMs).unref());
+                if ((await Promise.race([exited, timer])) !== "timeout")
+                    return;
+                if (pid !== undefined)
+                    await killProcessTree(pid, { platform, ...deps.process });
+                else
+                    child.kill("SIGKILL");
+            })();
+            return terminating;
+        },
+    };
+}
+/** 最近一段 stderr，单行化后截断（放进错误信息）。 */
+export function stderrHint(transport, max = 400) {
+    const text = transport.stderrTail().trim().replace(/\s+/g, " ");
+    if (text === "")
+        return "";
+    return text.length > max ? `…${text.slice(-max)}` : text;
+}

package/dist/drivers/runner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
+ *
+ * 外部 CLI Agent 由此与 ama 子 Agent 共用 `task(agent=…)` 入口（D13）。`start()`：
+ * 1. 只在已信任目录里起（§5.4 信任；`claude -p` 会跳过目录信任对话框并执行项目 hooks）；
+ * 2. 模式夹到父会话当前模式（`agents.<id>.maxMode` 例外），再取驱动支持的不更宽的模式；
+ *    按候选顺序选第一个已安装且支持该模式的驱动（D14 优先级；oneshot 只在只读下可选）；
+ * 3. 会话级美元预算 `agents.sessionBudgetUsd` 用尽则不再起；
+ * 4. 子进程环境按 D16 清理；并发池（总 3 / claude 2）每回合取一个名额，排队可被 abort；
+ * 5. 权限请求只交给人（{@link askHuman}）；中断 / stop / 超时时挂起的请求回 cancelled；
+ * 6. 每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`；
+ *    只回 finalText + 工具摘要（原始事件不落盘，§5.4 敏感数据）；
+ * 7. 看门狗：单回合缺省 30 min；空闲 10 min 关进程（能续接的下次 `send` 以 resume 重开）。
+ */
+import { type AgentsConfig } from "../config/types-w5.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { RunnerHandle, SubagentRunRequest, SubagentRunner } from "../tools/types.js";
+import { type ApproveFn } from "./permissions.js";
+import type { DriverPool } from "./pool.js";
+import type { AgentStore } from "./store.js";
+import type { AgentDriver, DriverTurnResult } from "./types.js";
+export declare const RUN_TIMEOUT_MS: number;
+export declare const IDLE_CLOSE_MS: number;
+export interface ProcessRunnerDeps {
+    /** 审批：只交给人。接到会话的 `requestApproval`（发 permission_request、走 broker 链）。 */
+    approve: ApproveFn;
+    pool: DriverPool;
+    store?: AgentStore;
+    /** 原始环境（runner 按 D16 清理）。 */
+    env: NodeJS.ProcessEnv;
+    config?: AgentsConfig;
+    /** 父会话当前模式（外部 Agent 不得更宽）。 */
+    parentMode?(): PermissionMode;
+    /** 无人值守（`-p`、RPC 未声明 approvals）：审批一律拒绝。 */
+    unattended?: boolean | (() => boolean);
+    /** 目录是否已被 ama 信任。 */
+    trusted(cwd: string): boolean;
+    /** runner id（缺省取驱动的 agentId）。 */
+    id?: string;
+    timeoutMs?: number;
+    idleMs?: number;
+    setTimer?(fn: () => void, ms: number): () => void;
+    log?(level: "debug" | "info" | "warn", message: string): void;
+}
+/** 最终报告：最终文本 + 工具摘要 / 触及文件（给协调者当资料，不是指令）。 */
+export declare function reportText(turn: DriverTurnResult): string;
+export declare class ProcessRunner implements SubagentRunner {
+    private readonly deps;
+    readonly id: string;
+    private readonly drivers;
+    constructor(driver: AgentDriver | readonly AgentDriver[], deps: ProcessRunnerDeps);
+    get agentId(): string;
+    private unattended;
+    /** 选驱动：第一个已安装、且支持（不宽于）目标模式的候选。 */
+    private choose;
+    start(request: SubagentRunRequest): Promise<RunnerHandle>;
+    /** ProcessHandle 用。 */
+    get options(): ProcessRunnerDeps;
+}
+/** §10.2 的签名：`createProcessRunner(driver, { approve, pool, store, … })`。 */
+export declare function createProcessRunner(driver: AgentDriver | readonly AgentDriver[], deps: ProcessRunnerDeps): ProcessRunner;