@armadra/agent 0.3.0 → 0.5.0

package/dist/drivers/native/oneshot.js

@@ -0,0 +1,312 @@
+/**
+ * 一次性打印模式兜底（docs/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
+ *
+ * `claude -p --output-format json`、`codex exec --json`、`gemini -p --output-format stream-json`：
+ * **不能审批**（能力 `permissions: "none"`），所以只在只读任务下用——open 时模式不是
+ * plan / allowlist 直接拒绝；子进程一律以只读方式启动（Claude `--permission-mode plan
+ * --permission-prompts none`，Codex `sandbox_mode="read-only"` + `approval_policy="never"`，
+ * Gemini `--approval-mode default`，无头时需要批准的工具不可用；未实测）。每回合起一个进程，提示从 stdin 给（Gemini 走 `-p` 参数）；
+ * 续聊用各 CLI 自己的 resume。中断 = 结束进程树。
+ */
+import { randomUUID } from "node:crypto";
+import { AmaError } from "../../errors.js";
+import { createLineReader } from "../../modes/rpc/jsonl.js";
+import { isReadOnlyMode, probeCandidate, spawnOf } from "../base.js";
+import { stderrHint } from "../process.js";
+import { TurnCollector, oneLine } from "../turn.js";
+import { claudeStopReason } from "./claude-normalize.js";
+export function oneshotArgs(dialect, options, session, prompt) {
+    switch (dialect) {
+        case "claude": {
+            const args = [
+                "-p",
+                "--output-format",
+                "json",
+                "--permission-mode",
+                "plan",
+                "--permission-prompts",
+                "none",
+            ];
+            args.push(session.resume ? "--resume" : "--session-id", session.id);
+            if (options.model !== undefined)
+                args.push("--model", options.model);
+            if (options.budgetUsd !== undefined)
+                args.push("--max-budget-usd", String(options.budgetUsd));
+            return args;
+        }
+        case "codex": {
+            const common = ["--json", "-c", 'sandbox_mode="read-only"', "-c", 'approval_policy="never"'];
+            if (options.model !== undefined)
+                common.push("-m", options.model);
+            return session.resume
+                ? ["exec", "resume", session.id, ...common, "-"]
+                : ["exec", ...common, "-"];
+        }
+        case "gemini": {
+            // default：无头模式下需要批准的工具直接不可用（Gemini 没有交互审批通道）
+            const args = ["--output-format", "stream-json", "--approval-mode", "default"];
+            if (options.model !== undefined)
+                args.push("--model", options.model);
+            return [...args, "-p", prompt];
+        }
+    }
+}
+export class OneshotDriver {
+    agentId;
+    candidate;
+    deps;
+    kind = "oneshot";
+    constructor(agentId, candidate, deps = {}) {
+        this.agentId = agentId;
+        this.candidate = candidate;
+        this.deps = deps;
+    }
+    probe() {
+        return probeCandidate(this.candidate, this.deps);
+    }
+    async open(options) {
+        if (!isReadOnlyMode(options.mode))
+            throw new AmaError("agent_mode_unsupported", `${this.agentId} 只有一次性打印模式可用，它不能审批，只能用于只读（plan）任务`);
+        const probed = await probeCandidate(this.candidate, this.deps);
+        const dialect = this.candidate.oneshot ?? "claude";
+        return new OneshotSession(this.agentId, dialect, probed.path ?? this.candidate.program, options, this.deps);
+    }
+}
+class OneshotSession {
+    agentId;
+    dialect;
+    program;
+    options;
+    deps;
+    id;
+    resumable;
+    transport;
+    interrupted = false;
+    closed = false;
+    constructor(agentId, dialect, program, options, deps) {
+        this.agentId = agentId;
+        this.dialect = dialect;
+        this.program = program;
+        this.options = options;
+        this.deps = deps;
+        this.id = options.resume ?? (dialect === "claude" ? randomUUID() : "");
+        this.resumable = options.resume !== undefined;
+    }
+    get sessionId() {
+        return this.id;
+    }
+    async prompt(content, hooks) {
+        if (this.closed)
+            throw new AmaError("agent_closed", `${this.agentId} 会话已关闭`);
+        if (this.transport !== undefined)
+            throw new AmaError("busy", `${this.agentId} 正在运行`);
+        const turn = new TurnCollector((e) => hooks.onEvent(e));
+        const text = content.map((b) => (b.type === "text" ? b.text : "")).join("\n");
+        if (content.some((b) => b.type === "image"))
+            turn.push({
+                type: "notice",
+                level: "warn",
+                text: `${this.agentId} 一次性模式不传图片，已省略`,
+            });
+        const resume = this.resumable && this.id !== "";
+        const transport = spawnOf(this.deps)({
+            program: this.program,
+            args: oneshotArgs(this.dialect, this.options, { id: this.id, resume }, text),
+            cwd: this.options.cwd,
+            env: this.options.env,
+        });
+        this.transport = transport;
+        this.interrupted = false;
+        let claude;
+        let failure;
+        const done = new Promise((resolve) => createLineReader(transport.stdout, (line) => {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (this.dialect === "claude") {
+                if (msg["type"] === "result")
+                    claude = msg;
+            }
+            else if (this.dialect === "codex")
+                failure = this.onCodex(msg, turn) ?? failure;
+            else
+                failure = this.onGemini(msg, turn) ?? failure;
+        }, resolve));
+        if (this.dialect !== "gemini")
+            transport.stdin.write(text);
+        transport.stdin.end();
+        try {
+            await done;
+            const code = await transport.exited;
+            if (this.dialect === "claude")
+                return this.claudeResult(claude, turn, code, transport);
+            if (this.interrupted)
+                return turn.result("cancelled");
+            if (failure !== undefined || code !== 0)
+                throw new AmaError("agent_failed", `${this.agentId} 失败：${oneLine(failure ?? (stderrHint(transport) || `退出码 ${String(code)}`), 300)}`);
+            this.resumable = this.dialect !== "gemini" && this.id !== "";
+            return turn.result("end_turn");
+        }
+        finally {
+            this.transport = undefined;
+        }
+    }
+    async cancel() {
+        if (this.transport === undefined)
+            return;
+        this.interrupted = true;
+        await this.transport.terminate(0);
+    }
+    async close() {
+        this.closed = true;
+        await this.cancel();
+    }
+    claudeResult(result, turn, code, transport) {
+        if (result === undefined) {
+            if (this.interrupted)
+                return turn.result("cancelled");
+            throw new AmaError("agent_failed", `${this.agentId} 没有输出结果（退出码 ${String(code)}）：${stderrHint(transport)}`);
+        }
+        if (typeof result.session_id === "string")
+            this.id = result.session_id;
+        this.resumable = true;
+        const u = result.usage ?? {};
+        turn.push({
+            type: "usage",
+            ...(u.input_tokens !== undefined ? { input: u.input_tokens } : {}),
+            ...(u.output_tokens !== undefined ? { output: u.output_tokens } : {}),
+            ...(u.cache_read_input_tokens !== undefined ? { cacheRead: u.cache_read_input_tokens } : {}),
+            ...(typeof result.total_cost_usd === "number" ? { costUsd: result.total_cost_usd } : {}),
+        });
+        if (typeof result.result === "string")
+            turn.setFinalText(result.result);
+        const stop = claudeStopReason(result, this.interrupted);
+        if (stop === undefined)
+            throw new AmaError("agent_failed", `${this.agentId} 失败：${oneLine(result.result ?? result.subtype ?? "", 300)}`);
+        return turn.result(stop);
+    }
+    /** codex exec --json 的一行；返回失败信息（turn.failed / error）。 */
+    onCodex(msg, turn) {
+        const item = (msg["item"] ?? {});
+        switch (msg["type"]) {
+            case "thread.started":
+                if (typeof msg["thread_id"] === "string")
+                    this.id = msg["thread_id"];
+                return undefined;
+            case "item.completed":
+            case "item.started": {
+                const started = msg["type"] === "item.started";
+                const id = String(item["id"] ?? "");
+                switch (item["type"]) {
+                    case "agent_message":
+                        if (!started && typeof item["text"] === "string") {
+                            turn.push({
+                                type: "message_delta",
+                                text: turn.finalText === "" ? item["text"] : `\n${item["text"]}`,
+                            });
+                        }
+                        return undefined;
+                    case "reasoning":
+                        if (!started && typeof item["text"] === "string")
+                            turn.push({ type: "thought_delta", text: item["text"] });
+                        return undefined;
+                    case "command_execution":
+                        turn.push({
+                            type: "tool_call",
+                            id,
+                            title: `$ ${oneLine(String(item["command"] ?? ""), 100)}`,
+                            kind: "execute",
+                            status: started
+                                ? "in_progress"
+                                : item["status"] === "failed"
+                                    ? "failed"
+                                    : "completed",
+                        });
+                        return undefined;
+                    case "web_search":
+                        turn.push({
+                            type: "tool_call",
+                            id,
+                            title: `search ${oneLine(String(item["query"] ?? ""), 80)}`,
+                            kind: "fetch",
+                            status: started ? "in_progress" : "completed",
+                        });
+                        return undefined;
+                    default:
+                        return undefined;
+                }
+            }
+            case "turn.completed": {
+                const u = (msg["usage"] ?? {});
+                turn.push({
+                    type: "usage",
+                    ...(u["input_tokens"] !== undefined ? { input: u["input_tokens"] } : {}),
+                    ...(u["output_tokens"] !== undefined ? { output: u["output_tokens"] } : {}),
+                    ...(u["cached_input_tokens"] !== undefined
+                        ? { cacheRead: u["cached_input_tokens"] }
+                        : {}),
+                });
+                return undefined;
+            }
+            case "turn.failed":
+                return String((msg["error"] ?? {})["message"] ?? "turn failed");
+            case "error":
+                return String(msg["message"] ?? "error");
+            default:
+                return undefined;
+        }
+    }
+    /** gemini -p --output-format stream-json 的一行。 */
+    onGemini(msg, turn) {
+        switch (msg["type"]) {
+            case "init":
+                if (typeof msg["session_id"] === "string")
+                    this.id = msg["session_id"];
+                return undefined;
+            case "message":
+                if (msg["role"] === "assistant" && typeof msg["content"] === "string")
+                    turn.push({ type: "message_delta", text: msg["content"] });
+                return undefined;
+            case "tool_use":
+                turn.push({
+                    type: "tool_call",
+                    id: String(msg["tool_id"] ?? ""),
+                    title: String(msg["tool_name"] ?? "tool"),
+                    kind: "other",
+                    status: "in_progress",
+                });
+                return undefined;
+            case "tool_result": {
+                const id = String(msg["tool_id"] ?? "");
+                const known = turn.tool(id);
+                turn.push({
+                    type: "tool_call",
+                    id,
+                    title: known?.title ?? "tool",
+                    kind: known?.kind ?? "other",
+                    status: msg["status"] === "error" ? "failed" : "completed",
+                });
+                return undefined;
+            }
+            case "result": {
+                const stats = (msg["stats"] ?? {});
+                turn.push({
+                    type: "usage",
+                    ...(stats["input_tokens"] !== undefined ? { input: stats["input_tokens"] } : {}),
+                    ...(stats["output_tokens"] !== undefined ? { output: stats["output_tokens"] } : {}),
+                });
+                return msg["status"] === "error"
+                    ? String((msg["error"] ?? {})["message"] ?? "error")
+                    : undefined;
+            }
+            case "error":
+                return String(msg["message"] ?? "error");
+            default:
+                return undefined;
+        }
+    }
+}

package/dist/drivers/permissions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 外部 Agent 的权限：交人、不代答（docs/wave5-plan.md §5.3，D15）。[W5-E]
+ *
+ * 1. 子 Agent 自己的策略先判，它决定要问人的才到 ama；到了以后只走审批通道（宿主 → UI →
+ *    无人值守拒绝），auto 分类器与模型都不参与——`approve` 由调用方接到会话的
+ *    `requestApproval`（发 permission_request 事件、走 broker 链），而不是 `gateToolCall`。
+ * 2. 选项映射：允许 → 首个 allow_once；本会话允许 → allow_always（由子 Agent 自己记，ama 不缓存）；
+ *    拒绝 → reject_once。reject_always（会改子 CLI 的持久配置）不由这里选。
+ * 3. 无人值守：reject_once（没有则 cancelled），不询问。
+ * 4. 父 abort / stop / 超时：cancelled。
+ * 5. 模式：外部 Agent 的模式不得比 ama 当前模式宽；`agents.<id>.maxMode`（只认用户级）显式放宽。
+ */
+import type { ApprovalDecision, ApprovalRequest, PermissionMode } from "../permissions/types.js";
+import type { DriverPermissionOutcome, DriverPermissionRequest } from "./types.js";
+export type ApproveFn = (request: ApprovalRequest, signal: AbortSignal) => Promise<ApprovalDecision>;
+export interface AskHumanContext {
+    agent: string;
+    sessionId: string;
+    unattended: boolean;
+    approve: ApproveFn;
+    signal: AbortSignal;
+    /** 发起的 task 任务 id（对话框与 RPC `context.taskId`）。 */
+    taskId?: string;
+}
+/** 审批对话框里显示的工具名：`agent:<id>`（RPC permission_request 的 toolName）。 */
+export declare function externalToolName(agent: string): string;
+/** ApprovalDecision → 外部 Agent 的选项。 */
+export declare function outcomeFor(request: DriverPermissionRequest, decision: ApprovalDecision): DriverPermissionOutcome;
+/** 把外部 Agent 的权限请求交给人。 */
+export declare function askHuman(request: DriverPermissionRequest, ctx: AskHumanContext): Promise<DriverPermissionOutcome>;
+/** 两个模式里更严的那个。 */
+export declare function stricterMode(a: PermissionMode, b: PermissionMode): PermissionMode;
+/**
+ * 外部 Agent 实际使用的模式：请求的模式夹到上限之内；上限 = `maxMode`（用户显式配置）或父会话
+ * 当前模式。结果为 `allowlist` 时按 `plan` 运行：外部 Agent 的放行规则来自它自己的配置，与 ama 的
+ * allowlist 不等价，父会话在 plan / allowlist 时外部 Agent 只能只读。
+ */
+export declare function clampMode(requested: PermissionMode, parent: PermissionMode | undefined, maxMode: PermissionMode | undefined): PermissionMode;
+/** 驱动支持的模式里，不宽于 `mode` 的最宽的一个；没有返回 undefined。 */
+export declare function supportedMode(mode: PermissionMode, supported: readonly PermissionMode[]): PermissionMode | undefined;

package/dist/drivers/permissions.js

@@ -0,0 +1,92 @@
+/**
+ * 外部 Agent 的权限：交人、不代答（docs/wave5-plan.md §5.3，D15）。[W5-E]
+ *
+ * 1. 子 Agent 自己的策略先判，它决定要问人的才到 ama；到了以后只走审批通道（宿主 → UI →
+ *    无人值守拒绝），auto 分类器与模型都不参与——`approve` 由调用方接到会话的
+ *    `requestApproval`（发 permission_request 事件、走 broker 链），而不是 `gateToolCall`。
+ * 2. 选项映射：允许 → 首个 allow_once；本会话允许 → allow_always（由子 Agent 自己记，ama 不缓存）；
+ *    拒绝 → reject_once。reject_always（会改子 CLI 的持久配置）不由这里选。
+ * 3. 无人值守：reject_once（没有则 cancelled），不询问。
+ * 4. 父 abort / stop / 超时：cancelled。
+ * 5. 模式：外部 Agent 的模式不得比 ama 当前模式宽；`agents.<id>.maxMode`（只认用户级）显式放宽。
+ */
+import { randomUUID } from "node:crypto";
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+/** 审批对话框里显示的工具名：`agent:<id>`（RPC permission_request 的 toolName）。 */
+export function externalToolName(agent) {
+    return `agent:${agent}`;
+}
+function pick(request, kind) {
+    const option = request.options.find((o) => o.kind === kind);
+    return option === undefined ? undefined : { outcome: "selected", optionId: option.optionId };
+}
+const CANCELLED = { outcome: "cancelled" };
+/** ApprovalDecision → 外部 Agent 的选项。 */
+export function outcomeFor(request, decision) {
+    switch (decision) {
+        case "allow":
+            return pick(request, "allow_once") ?? CANCELLED;
+        case "allow_session":
+            return pick(request, "allow_always") ?? pick(request, "allow_once") ?? CANCELLED;
+        case "deny":
+            return pick(request, "reject_once") ?? CANCELLED;
+    }
+}
+/** 把外部 Agent 的权限请求交给人。 */
+export async function askHuman(request, ctx) {
+    if (ctx.signal.aborted)
+        return CANCELLED;
+    if (ctx.unattended)
+        return pick(request, "reject_once") ?? CANCELLED;
+    const approval = {
+        requestId: randomUUID(),
+        toolName: externalToolName(ctx.agent),
+        input: request.toolCall,
+        reason: "mode",
+        context: {
+            depth: 1,
+            ...(ctx.taskId !== undefined ? { taskId: ctx.taskId } : {}),
+            origin: {
+                agent: ctx.agent,
+                sessionId: ctx.sessionId,
+                toolCall: request.toolCall,
+                options: request.options,
+            },
+        },
+    };
+    let decision;
+    try {
+        decision = await ctx.approve(approval, ctx.signal);
+    }
+    catch {
+        return CANCELLED;
+    }
+    if (ctx.signal.aborted)
+        return CANCELLED;
+    return outcomeFor(request, decision);
+}
+function rank(mode) {
+    return PERMISSION_MODES_STRICT_FIRST.indexOf(mode);
+}
+/** 两个模式里更严的那个。 */
+export function stricterMode(a, b) {
+    return rank(a) <= rank(b) ? a : b;
+}
+/**
+ * 外部 Agent 实际使用的模式：请求的模式夹到上限之内；上限 = `maxMode`（用户显式配置）或父会话
+ * 当前模式。结果为 `allowlist` 时按 `plan` 运行：外部 Agent 的放行规则来自它自己的配置，与 ama 的
+ * allowlist 不等价，父会话在 plan / allowlist 时外部 Agent 只能只读。
+ */
+export function clampMode(requested, parent, maxMode) {
+    const bound = maxMode ?? parent;
+    const mode = bound === undefined ? requested : stricterMode(requested, bound);
+    return mode === "allowlist" ? "plan" : mode;
+}
+/** 驱动支持的模式里，不宽于 `mode` 的最宽的一个；没有返回 undefined。 */
+export function supportedMode(mode, supported) {
+    let best;
+    for (const m of supported)
+        if (rank(m) <= rank(mode) && (best === undefined || rank(m) > rank(best)))
+            best = m;
+    return best;
+}

package/dist/drivers/pids.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 外部 Agent 进程登记与孤儿清理（docs/wave5-plan.md §5.4 孤儿进程）。[W5-E]
+ *
+ * `<dataDir>/drivers/pids.json` 记 `{ pid, program, owner }`（owner = 起它的 ama 进程）。
+ * 正常退出时 `process-tree.ts` 已同步杀掉仍存活的组；这里处理 ama 被 SIGKILL / 崩溃留下的孤儿：
+ * 下次建外部 runner 时，owner 已不在的条目若进程组仍在、且（POSIX）`ps` 看到的命令行含登记的
+ * 程序名，就杀进程树。对不上的（pid 被复用）只删登记不杀；Windows 不核对命令行，只删登记。
+ */
+export interface PidEntry {
+    pid: number;
+    program: string;
+    owner: number;
+    startedAt: number;
+}
+export declare function pidsFile(dataDir: string): string;
+export interface ReapDeps {
+    platform?: NodeJS.Platform;
+    isOwnerAlive?(pid: number): boolean;
+    isGroupAlive?(pid: number): boolean;
+    /** POSIX：进程的命令行（`ps -o command= -p pid`）。 */
+    commandOf?(pid: number): string | undefined;
+    kill?(pid: number): Promise<unknown>;
+}
+export declare class PidRegistry {
+    private readonly file;
+    constructor(file: string);
+    add(pid: number, program: string): void;
+    remove(pid: number): void;
+    entries(): PidEntry[];
+    /** 清理 owner 已不在的条目；返回被杀的 pid。 */
+    reapOrphans(deps?: ReapDeps): Promise<number[]>;
+}

package/dist/drivers/pids.js

@@ -0,0 +1,93 @@
+/**
+ * 外部 Agent 进程登记与孤儿清理（docs/wave5-plan.md §5.4 孤儿进程）。[W5-E]
+ *
+ * `<dataDir>/drivers/pids.json` 记 `{ pid, program, owner }`（owner = 起它的 ama 进程）。
+ * 正常退出时 `process-tree.ts` 已同步杀掉仍存活的组；这里处理 ama 被 SIGKILL / 崩溃留下的孤儿：
+ * 下次建外部 runner 时，owner 已不在的条目若进程组仍在、且（POSIX）`ps` 看到的命令行含登记的
+ * 程序名，就杀进程树。对不上的（pid 被复用）只删登记不杀；Windows 不核对命令行，只删登记。
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isGroupAlive, killProcessTree } from "../tools/process-tree.js";
+export function pidsFile(dataDir) {
+    return join(dataDir, "drivers", "pids.json");
+}
+function read(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+function write(file, entries) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify({ version: 1, entries }, null, 2)}\n`);
+        renameSync(tmp, file);
+    }
+    catch {
+        // 登记失败不影响运行（退出时仍有 process-tree 的同步清理）
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function psCommand(pid) {
+    const out = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" });
+    return out.status === 0 ? out.stdout.trim() : undefined;
+}
+export class PidRegistry {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    add(pid, program) {
+        const entries = read(this.file).filter((e) => e.pid !== pid);
+        entries.push({ pid, program, owner: process.pid, startedAt: Date.now() });
+        write(this.file, entries);
+    }
+    remove(pid) {
+        const entries = read(this.file);
+        const next = entries.filter((e) => e.pid !== pid);
+        if (next.length !== entries.length)
+            write(this.file, next);
+    }
+    entries() {
+        return read(this.file);
+    }
+    /** 清理 owner 已不在的条目；返回被杀的 pid。 */
+    async reapOrphans(deps = {}) {
+        const platform = deps.platform ?? process.platform;
+        const ownerAlive = deps.isOwnerAlive ?? processAlive;
+        const groupAlive = deps.isGroupAlive ?? ((pid) => isGroupAlive(pid));
+        const commandOf = deps.commandOf ?? psCommand;
+        const kill = deps.kill ?? ((pid) => killProcessTree(pid, { platform }));
+        const keep = [];
+        const killed = [];
+        for (const entry of read(this.file)) {
+            if (entry.owner === process.pid || ownerAlive(entry.owner)) {
+                keep.push(entry);
+                continue;
+            }
+            if (platform === "win32" || !groupAlive(entry.pid))
+                continue;
+            const command = commandOf(entry.pid);
+            if (command !== undefined && command.includes(basename(entry.program))) {
+                await kill(entry.pid);
+                killed.push(entry.pid);
+            }
+        }
+        write(this.file, keep);
+        return killed;
+    }
+}

package/dist/drivers/pool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 外部 Agent 并发池（docs/wave5-plan.md §5.4 并发）。[W5-E]
+ *
+ * 总并发 `agents.maxConcurrent`（缺省 3）+ 每个 Agent 的上限 `agents.<id>.maxConcurrent`
+ * （claude 缺省 2：订阅有速率限制）；超出排队（先来先得），排队可被 abort。与 ama 自己的
+ * `SubagentPool`（子会话）分开计数。
+ */
+import { type AgentsConfig } from "../config/types-w5.js";
+export declare const DEFAULT_MAX_CONCURRENT = 3;
+export declare const DEFAULT_PER_AGENT: Readonly<Record<string, number>>;
+export declare class DriverPool {
+    private readonly maxTotal;
+    private readonly perAgent;
+    private readonly active;
+    private total;
+    private readonly queue;
+    constructor(maxTotal?: number, perAgent?: (agentId: string) => number | undefined);
+    running(agentId?: string): number;
+    queued(): number;
+    private limitFor;
+    private canRun;
+    private take;
+    private drain;
+    /** 拿到一个名额（返回释放函数）；abort 时离开队列并以 `aborted` 失败。 */
+    acquire(agentId: string, signal?: AbortSignal): Promise<() => void>;
+}
+/** 按配置建池（`agents.maxConcurrent`、`agents.<id>.maxConcurrent`）。 */
+export declare function poolFromConfig(config: AgentsConfig | undefined): DriverPool;