@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tools/ignore.js

@@ -0,0 +1,174 @@
+/**
+ * `.gitignore` / `.ignore` 解析与匹配，以及尊重它们的目录遍历（设计 §5.2 grep / glob）。[B3]
+ *
+ * 规则语义（gitignore 子集）：空行与 `#` 注释；`\#`、`\!`、`\ ` 转义；`!` 取反；末尾 `/` 只匹配目录；
+ * 中间或开头含 `/` 的模式锚定在 ignore 文件所在目录，否则匹配任意深度的名字；`**` 的三种位置；
+ * 同一路径**最后**命中的规则生效；被忽略的目录不再下钻（其下的取反规则无效，与 git 一致）。
+ * 嵌套：每个目录的 `.gitignore` 先、`.ignore` 后（后者优先）；从搜索根向上到仓库根（含 `.git` 的
+ * 目录）的祖先 ignore 文件也生效。`.git` 目录永远跳过；目录符号链接不跟随。
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { toPosix } from "./paths.js";
+import { globBody } from "./glob.js";
+export const IGNORE_FILES = [".gitignore", ".ignore"];
+function trimTrailingSpaces(line) {
+    let end = line.length;
+    while (end > 0 && line[end - 1] === " " && line[end - 2] !== "\\")
+        end--;
+    return line.slice(0, end);
+}
+/** 解析一行；空 / 注释返回 undefined。 */
+export function parseIgnoreLine(rawLine, base, nocase = false) {
+    let line = trimTrailingSpaces(rawLine.replace(/\r$/, ""));
+    if (line === "" || line.startsWith("#"))
+        return undefined;
+    let negate = false;
+    if (line.startsWith("!")) {
+        negate = true;
+        line = line.slice(1);
+    }
+    else if (line.startsWith("\\!") || line.startsWith("\\#")) {
+        line = line.slice(1);
+    }
+    let dirOnly = false;
+    if (line.endsWith("/") && !line.endsWith("\\/")) {
+        dirOnly = true;
+        line = line.replace(/\/+$/, "");
+    }
+    if (line === "")
+        return undefined;
+    const anchored = line.includes("/");
+    if (line.startsWith("/"))
+        line = line.slice(1);
+    const body = globBody(line, { braces: false });
+    const prefix = anchored || line.startsWith("**/") ? "" : "(?:[^/]*/)*";
+    return {
+        negate,
+        dirOnly,
+        regex: new RegExp(`^${prefix}${body}$`, nocase ? "i" : ""),
+        base: base.replace(/\/+$/, ""),
+        source: rawLine,
+    };
+}
+export function parseIgnoreFile(content, base, nocase = false) {
+    const rules = [];
+    for (const line of content.split("\n")) {
+        const rule = parseIgnoreLine(line, base, nocase);
+        if (rule)
+            rules.push(rule);
+    }
+    return rules;
+}
+/** `absPosix` 相对 `base` 的路径；不在其下返回 undefined。 */
+function relativeTo(base, absPosix) {
+    if (base === "")
+        return absPosix.replace(/^\/+/, "");
+    if (absPosix === base)
+        return "";
+    const prefix = base.endsWith("/") ? base : `${base}/`;
+    return absPosix.startsWith(prefix) ? absPosix.slice(prefix.length) : undefined;
+}
+/** 按规则顺序求值，最后命中者生效。 */
+export function isIgnoredBy(rules, absPath, isDir) {
+    const absPosix = toPosix(absPath);
+    let ignored = false;
+    for (const rule of rules) {
+        if (rule.dirOnly && !isDir)
+            continue;
+        const rel = relativeTo(rule.base, absPosix);
+        if (rel === undefined || rel === "")
+            continue;
+        if (rule.regex.test(rel))
+            ignored = !rule.negate;
+    }
+    return ignored;
+}
+async function readRules(dir, nocase) {
+    const rules = [];
+    for (const name of IGNORE_FILES) {
+        try {
+            const text = await readFile(join(dir, name), "utf8");
+            rules.push(...parseIgnoreFile(text, toPosix(dir), nocase));
+        }
+        catch {
+            // 不存在
+        }
+    }
+    return rules;
+}
+/** 搜索根之上、直到仓库根（含 `.git` 的目录）的祖先 ignore 规则，外层在前。 */
+export async function ancestorRules(root, nocase = false) {
+    const chain = [];
+    let dir = root;
+    let foundRepo = await exists(join(root, ".git"));
+    while (!foundRepo) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return [];
+        dir = parent;
+        chain.unshift(dir);
+        foundRepo = await exists(join(dir, ".git"));
+    }
+    const rules = [];
+    for (const d of chain)
+        rules.push(...(await readRules(d, nocase)));
+    return rules;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 深度优先、目录内按名字排序的遍历；产出文件与目录（目录先于其内容）。 */
+export async function* walk(root, options = {}) {
+    const respect = options.respectIgnore ?? true;
+    const nocase = options.nocase ?? process.platform === "win32";
+    const base = respect ? await ancestorRules(root, nocase) : [];
+    yield* walkDir(root, "", base, respect, nocase, options.signal);
+}
+async function* walkDir(dir, rel, inherited, respect, nocase, signal) {
+    if (signal?.aborted)
+        return;
+    const rules = respect ? [...inherited, ...(await readRules(dir, nocase))] : inherited;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        if (signal?.aborted)
+            return;
+        if (entry.name === ".git")
+            continue;
+        const abs = join(dir, entry.name);
+        const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        let isDir = entry.isDirectory();
+        if (entry.isSymbolicLink()) {
+            // 链接到文件的照常产出；链接到目录的不跟随（避免环），作为普通条目跳过。
+            try {
+                if ((await stat(abs)).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            isDir = false;
+        }
+        else if (!isDir && !entry.isFile()) {
+            continue;
+        }
+        if (respect && isIgnoredBy(rules, abs, isDir))
+            continue;
+        yield { abs, rel: childRel, isDir };
+        if (isDir)
+            yield* walkDir(abs, childRel, rules, respect, nocase, signal);
+    }
+}

package/dist/tools/ls.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ls` 工具（设计 §5.2）。[B3]
+ *
+ * 目录项按名字排序（目录与文件混排，与 `ls` 一致）；目录写 `name/`，文件附大小，符号链接写
+ * `name -> target`；含点文件，不过滤 ignore；缺省上限 500。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface LsInput {
+    path?: string;
+    limit?: number;
+}
+export declare const DEFAULT_LS_LIMIT = 500;
+export interface LsEntry {
+    name: string;
+    type: "file" | "dir" | "symlink" | "other";
+    size?: number;
+    target?: string;
+}
+export declare function formatEntry(entry: LsEntry): string;
+export declare function executeLs(input: LsInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createLsTool(): ToolDefinition<LsInput>;

package/dist/tools/ls.js

@@ -0,0 +1,96 @@
+/**
+ * `ls` 工具（设计 §5.2）。[B3]
+ *
+ * 目录项按名字排序（目录与文件混排，与 `ls` 一致）；目录写 `name/`，文件附大小，符号链接写
+ * `name -> target`；含点文件，不过滤 ignore；缺省上限 500。
+ */
+import { lstat, readdir, readlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { displayPath, resolvePath } from "./paths.js";
+import { formatSize } from "./truncate.js";
+export const DEFAULT_LS_LIMIT = 500;
+async function describe(dir, name) {
+    const abs = join(dir, name);
+    try {
+        const info = await lstat(abs);
+        if (info.isSymbolicLink()) {
+            let target = "?";
+            try {
+                target = await readlink(abs);
+            }
+            catch {
+                // 保留 ?
+            }
+            let pointsToDir = false;
+            try {
+                pointsToDir = (await stat(abs)).isDirectory();
+            }
+            catch {
+                // 悬空链接
+            }
+            return { name: pointsToDir ? `${name}/` : name, type: "symlink", target };
+        }
+        if (info.isDirectory())
+            return { name: `${name}/`, type: "dir" };
+        if (info.isFile())
+            return { name, type: "file", size: info.size };
+        return { name, type: "other" };
+    }
+    catch {
+        return { name, type: "other" };
+    }
+}
+export function formatEntry(entry) {
+    if (entry.type === "symlink")
+        return `${entry.name} -> ${entry.target ?? "?"}`;
+    if (entry.type === "file")
+        return `${entry.name}  (${formatSize(entry.size ?? 0)})`;
+    return entry.name;
+}
+export async function executeLs(input, ctx) {
+    const limit = input.limit ?? DEFAULT_LS_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        return { content: "limit must be an integer ≥ 1", isError: true };
+    }
+    const dir = resolvePath(input.path ?? ".", ctx.cwd);
+    const shown = displayPath(dir, ctx.cwd);
+    let names;
+    try {
+        if (!(await stat(dir)).isDirectory())
+            return { content: `${shown} is not a directory`, isError: true };
+        names = await readdir(dir);
+    }
+    catch {
+        return { content: `Directory not found: ${shown}`, isError: true };
+    }
+    names.sort((a, b) => a.localeCompare(b, "en"));
+    if (names.length === 0)
+        return { content: `(${shown} is empty)`, details: { count: 0 } };
+    const entries = await Promise.all(names.slice(0, limit).map((n) => describe(dir, n)));
+    let content = entries.map(formatEntry).join("\n");
+    if (names.length > limit) {
+        content += `\n\n[${names.length} entries; showing the first ${limit}. Raise limit to see more.]`;
+    }
+    return { content, details: { count: names.length, entries } };
+}
+export function createLsTool() {
+    return {
+        name: "ls",
+        label: "List",
+        description: "List a directory: subdirectories end with `/`, files show their size, symlinks show their " +
+            `target. Includes dotfiles. Default limit ${DEFAULT_LS_LIMIT}.`,
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Directory (default: cwd)" },
+                limit: { type: "integer", description: `Maximum entries (default ${DEFAULT_LS_LIMIT})` },
+            },
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { readOnly: true },
+        promptSnippet: "ls: list directory contents",
+        execute: executeLs,
+    };
+}

package/dist/tools/output-accumulator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 进程输出累积（设计 §5.2 bash）。[B3]
+ *
+ * - 保留滚动尾部（约 2 × maxBytes）用于流式 `onUpdate` 与最终尾截断；
+ * - 内存里最多攒 `memoryLimitBytes`，超出即把已有内容落文件，之后增量追加，内存只留尾部；
+ * - `finish()` 做尾截断（行数 + 字节）；发生截断而尚未落盘时补写全文，给出 `fullOutputPath`；
+ * - 输出清洗：去 ANSI 转义与除 `\t\n` 外的控制字符，`\r\n` → `\n`。
+ */
+export interface OutputAccumulatorOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    /** 内存上限，缺省 1 MB。 */
+    memoryLimitBytes?: number;
+    /** 全文落盘路径（懒求值，只在需要时调用一次）。 */
+    spillPath(): string;
+}
+export interface AccumulatedOutput {
+    /** 尾截断后的输出。 */
+    output: string;
+    truncated: boolean;
+    fullOutputPath?: string;
+    totalBytes: number;
+    totalLines: number;
+    outputLines: number;
+}
+export declare function sanitizeOutput(text: string): string;
+export declare class OutputAccumulator {
+    private readonly options;
+    private readonly maxLines;
+    private readonly maxBytes;
+    private readonly memoryLimit;
+    private readonly decoder;
+    private chunks;
+    private memoryBytes;
+    private tailText;
+    private spilledTo;
+    private bytes;
+    private newlines;
+    private lastChar;
+    constructor(options: OutputAccumulatorOptions);
+    get totalBytes(): number;
+    append(chunk: Buffer | string): void;
+    private pushText;
+    private spill;
+    /** 当前滚动尾部（已清洗、尾截断），给流式 onUpdate。 */
+    tail(maxLines?: number): string;
+    finish(): AccumulatedOutput;
+}

package/dist/tools/output-accumulator.js

@@ -0,0 +1,106 @@
+/**
+ * 进程输出累积（设计 §5.2 bash）。[B3]
+ *
+ * - 保留滚动尾部（约 2 × maxBytes）用于流式 `onUpdate` 与最终尾截断；
+ * - 内存里最多攒 `memoryLimitBytes`，超出即把已有内容落文件，之后增量追加，内存只留尾部；
+ * - `finish()` 做尾截断（行数 + 字节）；发生截断而尚未落盘时补写全文，给出 `fullOutputPath`；
+ * - 输出清洗：去 ANSI 转义与除 `\t\n` 外的控制字符，`\r\n` → `\n`。
+ */
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, sliceTailBytes, truncateTail } from "./truncate.js";
+const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+const CONTROL = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+export function sanitizeOutput(text) {
+    return text.replace(/\r\n/g, "\n").replace(ANSI, "").replace(/\r/g, "\n").replace(CONTROL, "");
+}
+export class OutputAccumulator {
+    options;
+    maxLines;
+    maxBytes;
+    memoryLimit;
+    decoder = new StringDecoder("utf8");
+    chunks = [];
+    memoryBytes = 0;
+    tailText = "";
+    spilledTo;
+    bytes = 0;
+    newlines = 0;
+    lastChar = "";
+    constructor(options) {
+        this.options = options;
+        this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.memoryLimit = options.memoryLimitBytes ?? 1024 * 1024;
+    }
+    get totalBytes() {
+        return this.bytes;
+    }
+    append(chunk) {
+        const raw = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        this.bytes += raw.length;
+        this.pushText(this.decoder.write(raw));
+    }
+    pushText(text) {
+        if (text === "")
+            return;
+        for (let i = 0; i < text.length; i++)
+            if (text.charCodeAt(i) === 10)
+                this.newlines++;
+        this.lastChar = text[text.length - 1] ?? this.lastChar;
+        this.tailText += text;
+        if (this.tailText.length > this.maxBytes * 4) {
+            this.tailText = sliceTailBytes(this.tailText, this.maxBytes * 2);
+        }
+        if (this.spilledTo !== undefined) {
+            appendFileSync(this.spilledTo, text);
+            return;
+        }
+        this.chunks.push(text);
+        this.memoryBytes += Buffer.byteLength(text, "utf8");
+        if (this.memoryBytes > this.memoryLimit)
+            this.spill();
+    }
+    spill() {
+        const target = this.options.spillPath();
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, this.chunks.join(""));
+        this.spilledTo = target;
+        this.chunks = [];
+        this.memoryBytes = 0;
+    }
+    /** 当前滚动尾部（已清洗、尾截断），给流式 onUpdate。 */
+    tail(maxLines = 50) {
+        return truncateTail(sanitizeOutput(this.tailText), { maxLines, maxBytes: this.maxBytes })
+            .content;
+    }
+    finish() {
+        this.pushText(this.decoder.end());
+        const totalLines = this.newlines + (this.bytes > 0 && this.lastChar !== "\n" ? 1 : 0);
+        let source;
+        if (this.spilledTo !== undefined) {
+            // 尾部可能从半行开始：去掉第一行残片。
+            const cut = this.tailText.indexOf("\n");
+            source = cut >= 0 ? this.tailText.slice(cut + 1) : this.tailText;
+        }
+        else {
+            source = this.chunks.join("");
+        }
+        const result = truncateTail(sanitizeOutput(source), {
+            maxLines: this.maxLines,
+            maxBytes: this.maxBytes,
+        });
+        const truncated = result.truncated || this.spilledTo !== undefined;
+        if (truncated && this.spilledTo === undefined)
+            this.spill();
+        return {
+            output: result.content,
+            truncated,
+            ...(truncated && this.spilledTo !== undefined ? { fullOutputPath: this.spilledTo } : {}),
+            totalBytes: this.bytes,
+            totalLines,
+            outputLines: result.outputLines,
+        };
+    }
+}

package/dist/tools/paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 路径解析（设计 §5.2「通用安全」）。[B3]
+ *
+ * - 展开 `~` / `~/…`（`~user` 不展开）；相对路径按 cwd 解析；结果是规范化绝对路径。
+ * - 含 NUL 的路径一律拒绝（AmaError invalid_arguments）。
+ * - 符号链接策略：**跟随**，不做沙箱（信任边界是容器 / VM）。规则匹配用词法路径，
+ *   `realPathOrSelf()` 给需要真实路径的调用方（如 ls 标注链接目标）。
+ * - `toPosix()` 把路径统一成 `/` 分隔，供 glob / ignore / 权限规则匹配。
+ */
+export declare function assertNoNul(path: string): void;
+/** 展开 `~` 与 `~/…`、`~\…`。 */
+export declare function expandHome(path: string, home?: string): string;
+/** 解析为绝对路径；空串视为 cwd。 */
+export declare function resolvePath(path: string, cwd: string, home?: string): string;
+export declare function toPosix(path: string): string;
+/** cwd 内给相对路径，cwd 外给绝对路径；统一 `/`。 */
+export declare function displayPath(absolutePath: string, cwd: string): string;
+/** 是否在 dir 之内（含 dir 本身）。 */
+export declare function isWithin(dir: string, target: string): boolean;
+export declare function realPathOrSelf(path: string): string;

package/dist/tools/paths.js

@@ -0,0 +1,58 @@
+/**
+ * 路径解析（设计 §5.2「通用安全」）。[B3]
+ *
+ * - 展开 `~` / `~/…`（`~user` 不展开）；相对路径按 cwd 解析；结果是规范化绝对路径。
+ * - 含 NUL 的路径一律拒绝（AmaError invalid_arguments）。
+ * - 符号链接策略：**跟随**，不做沙箱（信任边界是容器 / VM）。规则匹配用词法路径，
+ *   `realPathOrSelf()` 给需要真实路径的调用方（如 ls 标注链接目标）。
+ * - `toPosix()` 把路径统一成 `/` 分隔，供 glob / ignore / 权限规则匹配。
+ */
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { AmaError } from "../errors.js";
+export function assertNoNul(path) {
+    if (path.includes("\0")) {
+        throw new AmaError("invalid_arguments", "Path must not contain NUL characters");
+    }
+}
+/** 展开 `~` 与 `~/…`、`~\…`。 */
+export function expandHome(path, home = homedir()) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(home, path.slice(2));
+    return path;
+}
+/** 解析为绝对路径；空串视为 cwd。 */
+export function resolvePath(path, cwd, home) {
+    assertNoNul(path);
+    const trimmed = path.trim() === "" ? "." : path;
+    const expanded = expandHome(trimmed, home);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+}
+export function toPosix(path) {
+    return sep === "\\" ? path.replace(/\\/g, "/") : path;
+}
+/** cwd 内给相对路径，cwd 外给绝对路径；统一 `/`。 */
+export function displayPath(absolutePath, cwd) {
+    const rel = relative(cwd, absolutePath);
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return toPosix(absolutePath);
+    return toPosix(rel);
+}
+/** 是否在 dir 之内（含 dir 本身）。 */
+export function isWithin(dir, target) {
+    const rel = relative(dir, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function realPathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}

package/dist/tools/presets.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 工具预设（设计 §5.6）：模型直接看到哪些内置工具。
+ *
+ * | 预设          | 模型直接看到                              |
+ * | ------------- | ----------------------------------------- |
+ * | `default`     | read、edit、write、bash、grep、glob       |
+ * | `minimal`     | read、edit、write、bash                   |
+ * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `coordinator` | read + 宿主注册的工具                     |
+ *
+ * - 预设只管**内置**工具；宿主 / SDK 注册的工具（`canvas_*` 等）总在活动集里，除非用户
+ *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
+ * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
+ *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
+ * - codemode 开关跟随预设：`codemode` 预设 → `only`，其余 → `off`；`codemode.mode` 显式配置覆盖。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（`codemode.mode` 为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），`on` 同样忽略。
+ * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
+ */
+import type { AmaConfig, CodemodeMode, ToolsPreset } from "../config/types.js";
+import { ToolRegistry } from "./registry.js";
+import type { ToolDefinition, ToolSource } from "./types.js";
+export declare const CODEMODE_TOOL = "codemode";
+/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+export declare const PRESET_TOOLS: Readonly<Record<ToolsPreset, readonly string[]>>;
+/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
+export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">): CodemodeMode;
+/**
+ * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
+ * 返回去重后的名字（保持首次出现顺序）。
+ */
+export declare function applyToolAdjustments(base: readonly string[], adjustments: readonly string[] | undefined): string[];
+export interface PresetResolution {
+    /** 生效的预设（codemode 工具缺失时回退为 default）。 */
+    preset: ToolsPreset;
+    codemode: CodemodeMode;
+    /** 活动的内置工具名（按名排序）。 */
+    builtin: string[];
+    warnings: string[];
+}
+export declare function resolvePreset(input: {
+    config: Pick<AmaConfig, "tools" | "codemode">;
+    /** 该名字是否已注册（且未禁用）。 */
+    available(name: string): boolean;
+}): PresetResolution;
+type RegisterListener = (tool: ToolDefinition, source: ToolSource) => void;
+/**
+ * 带预设的注册表：活动集 = 预设里的内置工具 + 全部非内置工具；`setActive()`（`--tools`）之后
+ * 退回整组替换语义。`onRegister` 让组装根把会话创建之后才注册的宿主工具追加进会话。
+ */
+export declare class PresetToolRegistry extends ToolRegistry {
+    private presetNames;
+    private exclusive;
+    private explicit;
+    private readonly listeners;
+    /**
+     * 设预设的内置工具；undefined = 全部内置工具。`exclusive`（codemode only）：活动集只有这些名字，
+     * 宿主 / SDK 工具也不进活动集。
+     */
+    setPresetTools(names: readonly string[] | undefined, options?: {
+        exclusive?: boolean;
+    }): void;
+    /** 是否被 `setActive` 整组替换过。 */
+    get hasExplicitActive(): boolean;
+    setActive(names: readonly string[]): void;
+    active(): readonly ToolDefinition[];
+    register(tool: ToolDefinition, source: ToolSource): void;
+    onRegister(listener: RegisterListener): () => void;
+}
+export {};