@armadra/agent 0.0.0-stage → 0.3.0

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 {};

package/dist/tools/presets.js

@@ -0,0 +1,128 @@
+/**
+ * 工具预设（设计 §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 { ToolRegistry } from "./registry.js";
+export const CODEMODE_TOOL = "codemode";
+/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+export const PRESET_TOOLS = Object.freeze({
+    default: ["bash", "edit", "glob", "grep", "read", "write"],
+    minimal: ["bash", "edit", "read", "write"],
+    codemode: [CODEMODE_TOOL],
+    coordinator: ["read"],
+});
+/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
+export function effectiveCodemodeMode(config) {
+    const explicit = config.codemode?.mode;
+    if (explicit !== undefined)
+        return explicit;
+    return config.tools?.preset === "codemode" ? "only" : "off";
+}
+/**
+ * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
+ * 返回去重后的名字（保持首次出现顺序）。
+ */
+export function applyToolAdjustments(base, adjustments) {
+    if (adjustments === undefined || adjustments.length === 0)
+        return [...base];
+    const plain = adjustments.filter((a) => !a.startsWith("+") && !a.startsWith("-"));
+    const names = new Set(plain.length > 0 ? plain.map((a) => a.trim()) : base);
+    for (const item of adjustments) {
+        const name = item.slice(1).trim();
+        if (item.startsWith("+"))
+            names.add(name);
+        else if (item.startsWith("-"))
+            names.delete(name);
+    }
+    names.delete("");
+    return [...names];
+}
+export function resolvePreset(input) {
+    const warnings = [];
+    let preset = input.config.tools?.preset ?? "default";
+    let codemode = effectiveCodemodeMode(input.config);
+    if (codemode !== "off" && !input.available(CODEMODE_TOOL)) {
+        warnings.push(preset === "codemode"
+            ? "工具预设 codemode 需要 codemode 工具（不可用），已回退到 default"
+            : `codemode.mode ${codemode} 需要 codemode 工具（不可用），已忽略`);
+        if (preset === "codemode")
+            preset = "default";
+        codemode = "off";
+    }
+    let base;
+    if (codemode === "only")
+        base = [CODEMODE_TOOL];
+    else {
+        base = [...PRESET_TOOLS[preset === "codemode" ? "default" : preset]];
+        if (codemode === "on")
+            base.push(CODEMODE_TOOL);
+    }
+    const names = [];
+    for (const name of applyToolAdjustments(base, input.config.tools?.default)) {
+        if (input.available(name))
+            names.push(name);
+        else
+            warnings.push(`tools.default：未知工具 ${name}，已忽略`);
+    }
+    return { preset, codemode, builtin: names.sort(), warnings };
+}
+/**
+ * 带预设的注册表：活动集 = 预设里的内置工具 + 全部非内置工具；`setActive()`（`--tools`）之后
+ * 退回整组替换语义。`onRegister` 让组装根把会话创建之后才注册的宿主工具追加进会话。
+ */
+export class PresetToolRegistry extends ToolRegistry {
+    presetNames;
+    exclusive = false;
+    explicit = false;
+    listeners = new Set();
+    /**
+     * 设预设的内置工具；undefined = 全部内置工具。`exclusive`（codemode only）：活动集只有这些名字，
+     * 宿主 / SDK 工具也不进活动集。
+     */
+    setPresetTools(names, options = {}) {
+        this.presetNames = names === undefined ? undefined : new Set(names);
+        this.exclusive = names !== undefined && options.exclusive === true;
+    }
+    /** 是否被 `setActive` 整组替换过。 */
+    get hasExplicitActive() {
+        return this.explicit;
+    }
+    setActive(names) {
+        super.setActive(names);
+        this.explicit = true;
+    }
+    active() {
+        const preset = this.presetNames;
+        if (this.explicit || preset === undefined)
+            return super.active();
+        return this.list()
+            .filter((name) => preset.has(name) || (!this.exclusive && this.sourceOf(name) !== "builtin"))
+            .map((name) => this.get(name))
+            .filter((tool) => tool !== undefined);
+    }
+    register(tool, source) {
+        super.register(tool, source);
+        for (const listener of [...this.listeners])
+            listener(tool, source);
+    }
+    onRegister(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}

package/dist/tools/process-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 进程组与杀树（设计 §5.2 bash、§4.2）。[B3]
+ *
+ * - POSIX：bash 以 `detached: true` 启动，自成进程组（pgid = pid）；杀树 = 对 `-pid` 发 SIGTERM，
+ *   每 50 ms 探测组是否还在，宽限 2 s 后 SIGKILL。
+ * - Windows：`taskkill /PID <pid> /T /F`（没有优雅阶段）。
+ * - 信号退出的退出码按 shell 惯例 `128 + signo`。
+ * - 启动过的进程组登记在案；本进程 `exit` 时同步 SIGKILL 仍存活的组（Windows 同步 taskkill）。
+ */
+export declare const KILL_GRACE_MS = 2000;
+export interface ProcessDeps {
+    platform?: NodeJS.Platform;
+    /** 缺省 process.kill。 */
+    kill?(pid: number, signal: NodeJS.Signals | 0): void;
+    /** Windows taskkill 的执行器；缺省 spawn。 */
+    runTaskkill?(args: readonly string[]): Promise<void>;
+    graceMs?: number;
+}
+/** 信号名 → `128 + signo`；未知信号按 SIGTERM 处理。 */
+export declare function signalExitCode(signal: NodeJS.Signals | string): number;
+/** 子进程结束时的退出码：正常退出取 code，信号退出取 128+signo。 */
+export declare function exitCodeOf(code: number | null, signal: NodeJS.Signals | null): number;
+export declare function taskkillArgs(pid: number): string[];
+/** 进程组（POSIX）是否还有成员。 */
+export declare function isGroupAlive(pid: number, deps?: ProcessDeps): boolean;
+/**
+ * 杀整棵进程树。POSIX：SIGTERM → 宽限（缺省 2 s，组提前消失则提前返回）→ SIGKILL。
+ * 返回实际是否升级到了 SIGKILL（Windows 恒为 false）。
+ */
+export declare function killProcessTree(pid: number, deps?: ProcessDeps): Promise<boolean>;
+export declare function trackProcessGroup(pid: number): void;
+export declare function untrackProcessGroup(pid: number): void;
+export declare function trackedProcessGroups(): readonly number[];
+/** 同步清理（只能在 `exit` 里用同步 API）。 */
+export declare function killTrackedSync(deps?: ProcessDeps): void;

package/dist/tools/process-tree.js

@@ -0,0 +1,125 @@
+/**
+ * 进程组与杀树（设计 §5.2 bash、§4.2）。[B3]
+ *
+ * - POSIX：bash 以 `detached: true` 启动，自成进程组（pgid = pid）；杀树 = 对 `-pid` 发 SIGTERM，
+ *   每 50 ms 探测组是否还在，宽限 2 s 后 SIGKILL。
+ * - Windows：`taskkill /PID <pid> /T /F`（没有优雅阶段）。
+ * - 信号退出的退出码按 shell 惯例 `128 + signo`。
+ * - 启动过的进程组登记在案；本进程 `exit` 时同步 SIGKILL 仍存活的组（Windows 同步 taskkill）。
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { constants } from "node:os";
+export const KILL_GRACE_MS = 2000;
+const POLL_MS = 50;
+/** 信号名 → `128 + signo`；未知信号按 SIGTERM 处理。 */
+export function signalExitCode(signal) {
+    const signo = constants.signals[signal];
+    return 128 + (signo ?? constants.signals.SIGTERM);
+}
+/** 子进程结束时的退出码：正常退出取 code，信号退出取 128+signo。 */
+export function exitCodeOf(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal !== null)
+        return signalExitCode(signal);
+    return 1;
+}
+export function taskkillArgs(pid) {
+    return ["/PID", String(pid), "/T", "/F"];
+}
+function defaultTaskkill(args) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn("taskkill", [...args], { stdio: "ignore", windowsHide: true });
+            child.on("error", () => resolve());
+            child.on("exit", () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+/** 进程组（POSIX）是否还有成员。 */
+export function isGroupAlive(pid, deps = {}) {
+    const kill = deps.kill ?? ((p, s) => process.kill(p, s));
+    try {
+        kill(-pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function sendGroup(pid, signal, deps) {
+    const kill = deps.kill ?? ((p, s) => process.kill(p, s));
+    try {
+        kill(-pid, signal);
+    }
+    catch {
+        try {
+            kill(pid, signal);
+        }
+        catch {
+            // 已退出
+        }
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 杀整棵进程树。POSIX：SIGTERM → 宽限（缺省 2 s，组提前消失则提前返回）→ SIGKILL。
+ * 返回实际是否升级到了 SIGKILL（Windows 恒为 false）。
+ */
+export async function killProcessTree(pid, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform === "win32") {
+        await (deps.runTaskkill ?? defaultTaskkill)(taskkillArgs(pid));
+        return false;
+    }
+    sendGroup(pid, "SIGTERM", deps);
+    const deadline = Date.now() + (deps.graceMs ?? KILL_GRACE_MS);
+    while (Date.now() < deadline) {
+        if (!isGroupAlive(pid, deps))
+            return false;
+        await sleep(POLL_MS);
+    }
+    if (!isGroupAlive(pid, deps))
+        return false;
+    sendGroup(pid, "SIGKILL", deps);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// 登记与退出清理
+// ---------------------------------------------------------------------------
+const tracked = new Set();
+let exitHookInstalled = false;
+export function trackProcessGroup(pid) {
+    tracked.add(pid);
+    if (!exitHookInstalled) {
+        exitHookInstalled = true;
+        process.once("exit", () => killTrackedSync());
+    }
+}
+export function untrackProcessGroup(pid) {
+    tracked.delete(pid);
+}
+export function trackedProcessGroups() {
+    return [...tracked];
+}
+/** 同步清理（只能在 `exit` 里用同步 API）。 */
+export function killTrackedSync(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    for (const pid of tracked) {
+        if (platform === "win32") {
+            try {
+                spawnSync("taskkill", taskkillArgs(pid), { stdio: "ignore", windowsHide: true });
+            }
+            catch {
+                // 忽略
+            }
+        }
+        else if (isGroupAlive(pid, deps)) {
+            sendGroup(pid, "SIGKILL", deps);
+        }
+    }
+    tracked.clear();
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `read` 工具（设计 §5.2）。[B3]
+ *
+ * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
+ * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
+ * `ctx.markRead(abs)`。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export { imageSize, type ImageSize } from "./image-file.js";
+export interface ReadInput {
+    path: string;
+    offset?: number;
+    limit?: number;
+}
+export interface ReadToolOptions {
+    /** 当前模型是否接受图片输入；缺省 true。 */
+    supportsImages?(ctx: ToolContext): boolean;
+}
+export declare function isBinary(buf: Buffer): boolean;
+/** `cat -n` 形状。 */
+export declare function numberLines(lines: readonly string[], firstLine: number): string;
+export declare function executeRead(input: ReadInput, ctx: ToolContext, options?: ReadToolOptions): Promise<ToolResult>;
+export declare function createReadTool(options?: ReadToolOptions): ToolDefinition<ReadInput>;

package/dist/tools/read.js

@@ -0,0 +1,132 @@
+/**
+ * `read` 工具（设计 §5.2）。[B3]
+ *
+ * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
+ * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
+ * `ctx.markRead(abs)`。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { displayPath, resolvePath } from "./paths.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
+import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
+import { MAX_IMAGE_BYTES, imageMimeFromPath, imageSize, sniffImageMime } from "./image-file.js";
+export { imageSize } from "./image-file.js";
+const SNIFF_BYTES = 8000;
+export function isBinary(buf) {
+    const end = Math.min(buf.length, SNIFF_BYTES);
+    for (let i = 0; i < end; i++)
+        if (buf[i] === 0)
+            return true;
+    return false;
+}
+function error(message) {
+    return { content: message, isError: true };
+}
+/** `cat -n` 形状。 */
+export function numberLines(lines, firstLine) {
+    return lines.map((line, i) => `${String(firstLine + i).padStart(6)}\t${line}`).join("\n");
+}
+async function readImage(abs, shown, ctx, options) {
+    const buf = await readFile(abs);
+    const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(abs) ?? "application/octet-stream";
+    const size = imageSize(buf, mimeType);
+    const dims = size ? `${size.width}x${size.height}, ` : "";
+    const caption = `Image: ${shown} (${dims}${mimeType}, ${formatSize(buf.length)})`;
+    ctx.markRead(abs);
+    const details = { path: abs, mimeType, bytes: buf.length, ...(size ? { size } : {}) };
+    if (options.supportsImages && !options.supportsImages(ctx)) {
+        return { content: `${caption}\n[The current model does not accept image input.]`, details };
+    }
+    if (buf.length > MAX_IMAGE_BYTES) {
+        return {
+            content: `${caption}\n[Image exceeds the ${formatSize(MAX_IMAGE_BYTES)} attachment limit; not attached.]`,
+            details,
+        };
+    }
+    const blocks = [
+        { type: "text", text: caption },
+        { type: "image", data: buf.toString("base64"), mimeType },
+    ];
+    return { content: blocks, details };
+}
+export async function executeRead(input, ctx, options = {}) {
+    const abs = resolvePath(input.path, ctx.cwd);
+    const shown = displayPath(abs, ctx.cwd);
+    let info;
+    try {
+        info = await stat(abs);
+    }
+    catch {
+        return error(`File not found: ${shown}`);
+    }
+    if (info.isDirectory())
+        return error(`${shown} is a directory; use the ls tool instead`);
+    if (imageMimeFromPath(abs) !== undefined)
+        return readImage(abs, shown, ctx, options);
+    const buf = await readFile(abs);
+    if (isBinary(buf))
+        return error(`${shown} appears to be a binary file; refusing to read it`);
+    const { text } = splitBom(buf.toString("utf8"));
+    const normalized = normalizeToLF(text);
+    const allLines = normalized === "" ? [] : normalized.replace(/\n$/, "").split("\n");
+    ctx.markRead(abs);
+    if (allLines.length === 0) {
+        return { content: `(${shown} is empty)`, details: { path: abs, totalLines: 0 } };
+    }
+    const offset = input.offset ?? 1;
+    if (!Number.isInteger(offset) || offset < 1)
+        return error("offset must be an integer ≥ 1");
+    if (offset > allLines.length) {
+        return error(`offset ${offset} is beyond the end of ${shown} (${allLines.length} lines)`);
+    }
+    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1)) {
+        return error("limit must be an integer ≥ 1");
+    }
+    const end = input.limit === undefined ? allLines.length : offset - 1 + input.limit;
+    const selected = allLines.slice(offset - 1, end);
+    const numbered = numberLines(selected, offset);
+    const cut = truncateHead(numbered, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+    const lastShown = offset - 1 + cut.outputLines;
+    let content = cut.content;
+    if (lastShown < allLines.length) {
+        const reason = cut.truncated
+            ? ` (output limit ${cut.truncatedBy === "bytes" ? formatSize(DEFAULT_MAX_BYTES) : `${DEFAULT_MAX_LINES} lines`} reached)`
+            : "";
+        content += `\n\n[Showing lines ${offset}-${lastShown} of ${allLines.length}${reason}. Use offset=${lastShown + 1} to continue.]`;
+    }
+    return {
+        content,
+        details: {
+            path: abs,
+            totalLines: allLines.length,
+            firstLine: offset,
+            lastLine: lastShown,
+            truncated: cut.truncated,
+        },
+    };
+}
+export function createReadTool(options = {}) {
+    return {
+        name: "read",
+        label: "Read",
+        description: "Read a file. Text comes with line numbers (cat -n), limited to " +
+            `${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; page with offset/limit. ` +
+            "Images (png, jpg, gif, webp) come as attachments.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Absolute or relative to cwd" },
+                offset: { type: "integer", description: "First line (1-based)" },
+                limit: { type: "integer", description: "Max lines" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { readOnly: true },
+        promptSnippet: "read: read files (text or images)",
+        execute: (input, ctx) => executeRead(input, ctx, options),
+    };
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ToolRegistry：内置 + 宿主 / SDK 注册、disable、活动集、按名排序（设计 §1.2、§5.1）。[B3]
+ *
+ * - 注册校验：名字 `^[a-z][a-z0-9_]{1,63}$`、`parameters` 只用 JSON Schema 子集（checkSchemaSubset）、
+ *   同名 → AmaError{code:"tool_exists"}；
+ * - `disable(name)` 后不再出现在 `list()` / `active()`，也不能被 `setActive` 选中；未注册的名字也
+ *   记下（宿主可能先 disable 再由内置注册，例如 `disable("task")`）；
+ * - 活动集缺省 = 全部已注册且未禁用；`setActive(names)` 之后只用这些（未知名 → tool_not_found）；
+ * - `builtinTools()` 给出全部内置工具；Skill 正文由模型用 read 读取（设计 §5.6 删除了 skill 工具），
+ *   `/skill:` 命令展开在 skills/expand.ts。
+ */
+import type { ToolDefinition, ToolExecutionMode, ToolRegistryApi, ToolSource } from "./types.js";
+import { type ReadToolOptions } from "./read.js";
+import { type BashToolOptions } from "./bash.js";
+import { type TaskToolOptions } from "./task.js";
+export declare const TOOL_NAME_RE: RegExp;
+/** 未声明时：read → parallel；write / execute → sequential。 */
+export declare function executionModeOf(tool: Pick<ToolDefinition, "permission" | "executionMode">): ToolExecutionMode;
+export declare function validateToolDefinition(tool: ToolDefinition): void;
+export declare class ToolRegistry implements ToolRegistryApi {
+    private readonly entries;
+    private readonly disabled;
+    private activeNames;
+    register(tool: ToolDefinition, source: ToolSource): void;
+    disable(name: string): void;
+    isDisabled(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    sourceOf(name: string): ToolSource | undefined;
+    list(): readonly string[];
+    active(): readonly ToolDefinition[];
+    setActive(names: readonly string[]): void;
+}
+export interface BuiltinToolOptions {
+    read?: ReadToolOptions;
+    bash?: BashToolOptions;
+    task?: TaskToolOptions;
+}
+/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task）。 */
+export declare function builtinTools(options?: BuiltinToolOptions): ToolDefinition[];
+/** 新建注册表并登记全部内置工具；`disabled` 来自 config.tools.disabled。 */
+export declare function createToolRegistry(options?: BuiltinToolOptions & {
+    disabled?: readonly string[];
+}): ToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,106 @@
+/**
+ * ToolRegistry：内置 + 宿主 / SDK 注册、disable、活动集、按名排序（设计 §1.2、§5.1）。[B3]
+ *
+ * - 注册校验：名字 `^[a-z][a-z0-9_]{1,63}$`、`parameters` 只用 JSON Schema 子集（checkSchemaSubset）、
+ *   同名 → AmaError{code:"tool_exists"}；
+ * - `disable(name)` 后不再出现在 `list()` / `active()`，也不能被 `setActive` 选中；未注册的名字也
+ *   记下（宿主可能先 disable 再由内置注册，例如 `disable("task")`）；
+ * - 活动集缺省 = 全部已注册且未禁用；`setActive(names)` 之后只用这些（未知名 → tool_not_found）；
+ * - `builtinTools()` 给出全部内置工具；Skill 正文由模型用 read 读取（设计 §5.6 删除了 skill 工具），
+ *   `/skill:` 命令展开在 skills/expand.ts。
+ */
+import { AmaError } from "../errors.js";
+import { checkSchemaSubset } from "../agent/schema.js";
+import { createReadTool } from "./read.js";
+import { createWriteTool } from "./write.js";
+import { createEditTool } from "./edit.js";
+import { createBashTool } from "./bash.js";
+import { createGrepTool } from "./grep.js";
+import { createGlobTool } from "./glob.js";
+import { createLsTool } from "./ls.js";
+import { createTodoTool } from "./todo.js";
+import { createTaskTool } from "./task.js";
+export const TOOL_NAME_RE = /^[a-z][a-z0-9_]{1,63}$/;
+/** 未声明时：read → parallel；write / execute → sequential。 */
+export function executionModeOf(tool) {
+    return tool.executionMode ?? (tool.permission === "read" ? "parallel" : "sequential");
+}
+export function validateToolDefinition(tool) {
+    if (typeof tool.name !== "string" || !TOOL_NAME_RE.test(tool.name)) {
+        throw new AmaError("invalid_arguments", `Invalid tool name "${String(tool.name)}"`);
+    }
+    if (!["read", "write", "execute"].includes(tool.permission)) {
+        throw new AmaError("invalid_arguments", `Tool ${tool.name}: invalid permission`);
+    }
+    if (typeof tool.execute !== "function") {
+        throw new AmaError("invalid_arguments", `Tool ${tool.name}: execute must be a function`);
+    }
+    const problems = checkSchemaSubset(tool.parameters);
+    if (problems.length > 0) {
+        throw new AmaError("invalid_arguments", `Tool ${tool.name}: parameters use unsupported schema features: ${problems.join("; ")}`);
+    }
+}
+export class ToolRegistry {
+    entries = new Map();
+    disabled = new Set();
+    activeNames;
+    register(tool, source) {
+        validateToolDefinition(tool);
+        if (this.entries.has(tool.name)) {
+            throw new AmaError("tool_exists", `Tool "${tool.name}" is already registered`);
+        }
+        this.entries.set(tool.name, { tool, source });
+    }
+    disable(name) {
+        this.disabled.add(name);
+        this.activeNames?.delete(name);
+    }
+    isDisabled(name) {
+        return this.disabled.has(name);
+    }
+    get(name) {
+        return this.disabled.has(name) ? undefined : this.entries.get(name)?.tool;
+    }
+    sourceOf(name) {
+        return this.entries.get(name)?.source;
+    }
+    list() {
+        return [...this.entries.keys()].filter((n) => !this.disabled.has(n)).sort();
+    }
+    active() {
+        const names = this.list().filter((n) => this.activeNames === undefined || this.activeNames.has(n));
+        return names.map((n) => this.entries.get(n).tool);
+    }
+    setActive(names) {
+        for (const name of names) {
+            if (!this.entries.has(name) || this.disabled.has(name)) {
+                throw new AmaError("tool_not_found", `Unknown or disabled tool "${name}"`);
+            }
+        }
+        this.activeNames = new Set(names);
+    }
+}
+/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task）。 */
+export function builtinTools(options = {}) {
+    const tools = [
+        createReadTool(options.read),
+        createWriteTool(),
+        createEditTool(),
+        createBashTool(options.bash),
+        createGrepTool(),
+        createGlobTool(),
+        createLsTool(),
+        createTodoTool(),
+        createTaskTool(options.task),
+    ];
+    return tools;
+}
+/** 新建注册表并登记全部内置工具；`disabled` 来自 config.tools.disabled。 */
+export function createToolRegistry(options = {}) {
+    const registry = new ToolRegistry();
+    for (const tool of builtinTools(options))
+        registry.register(tool, "builtin");
+    for (const name of options.disabled ?? [])
+        registry.disable(name);
+    return registry;
+}