@armadra/agent 0.2.1 → 0.4.0

package/dist/cli/subcommands/sessions.js

@@ -3,16 +3,22 @@
  *
  * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
- * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
+ * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
  * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
  */
 import { resolve } from "node:path";
 import { expandHome, resolveDataDir } from "../../config/paths.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
+import { numberUserMessages } from "../../session/reuse.js";
+import { runSessionsExport } from "./sessions-export.js";
+import { runSessionsSearch } from "./sessions-search.js";
 export const SESSIONS_USAGE = `用法：ama sessions list [--all] [--session-dir <目录>]
       ama sessions show <id> [--session-dir <目录>]
       ama sessions prune [--older-than <天>] [--dry-run] [--all] [--session-dir <目录>]
+      ama sessions search <关键词|/正则/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]
+      ama sessions export <id> [--format md|json|jsonl] [--output <文件>] [--branch leaf|all]
 `;
 function shortTime(iso) {
     return iso.replace("T", " ").replace(/\.\d+Z$|Z$/, "");
@@ -24,6 +30,10 @@ function oneLine(text, max = 60) {
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
 export async function runSessions(argv, io, deps) {
+    if (argv[0] === "search")
+        return runSessionsSearch(argv.slice(1), io);
+    if (argv[0] === "export")
+        return runSessionsExport(argv.slice(1), io);
     const { positionals, values, flags } = parseSubArgs(argv, ["session-dir", "older-than"], ["all", "dry-run"]);
     const action = positionals[0];
     if (flags.has("help") || action === undefined) {
@@ -73,6 +83,17 @@ export async function runSessions(argv, io, deps) {
                     ? [`首条提示：${oneLine(item.firstPrompt, 200)}`]
                     : []),
             ].join("\n") + "\n");
+            const users = numberUserMessages(entries);
+            if (users.length > 0) {
+                io.stdout(`用户消息（ama --from ${item.id.slice(0, 8)}#<编号> 复用）：\n`);
+                for (const user of users) {
+                    const tags = [
+                        ...(user.origin !== undefined ? [`[${user.origin}]`] : []),
+                        ...(user.images.length > 0 ? [`[图片 ${user.images.length}]`] : []),
+                    ];
+                    io.stdout(`  #${String(user.n).padEnd(3)} ${shortTime(user.timestamp)}  ${[...tags, oneLine(user.text, 100)].join(" ")}\n`);
+                }
+            }
             return ExitCode.Ok;
         }
         case "prune": {

package/dist/cli/subcommands/stats.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `ama stats`：跨会话的用量统计（只读扫描会话 JSONL）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话；`--project <目录>` 指定项目；`--all` 全部（`--by project` 未指定范围时也看全部）。
+ * - 时间：`--since` / `--until` 接受 `7d`（含今天的最近 7 天）、`today`、`YYYY-MM-DD`（本地日期，含当天）。
+ * - 分组：`--by day|week|month|provider|channel|model|project`。
+ * - 缓存：`<数据目录>/stats-index.json`，按文件 mtime / size 失效；`--no-cache` 不读也不写。
+ * - 口径见 session/stats-aggregate.ts 与 docs/sessions.md「统计」。
+ */
+import { type StatsReport } from "../../session/stats-aggregate.js";
+import type { CliIo } from "../deps.js";
+export declare const STATS_USAGE = "\u7528\u6CD5\uFF1Aama stats [--since 7d|30d|today|YYYY-MM-DD] [--until \u2026]\n                 [--by day|week|month|provider|channel|model|project]\n                 [--project <\u76EE\u5F55> | --all] [--top N] [--json] [--no-cache] [--session-dir <\u76EE\u5F55>]\n";
+/** `7d` / `today` / `YYYY-MM-DD` → 本地日期。 */
+export declare function parseDaySpec(option: string, raw: string, now?: Date): string;
+export declare function formatTokens(count: number): string;
+export declare function renderStats(report: StatsReport, scope: string): string;
+export declare function runStats(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/cli/subcommands/stats.js

@@ -0,0 +1,198 @@
+/**
+ * `ama stats`：跨会话的用量统计（只读扫描会话 JSONL）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话；`--project <目录>` 指定项目；`--all` 全部（`--by project` 未指定范围时也看全部）。
+ * - 时间：`--since` / `--until` 接受 `7d`（含今天的最近 7 天）、`today`、`YYYY-MM-DD`（本地日期，含当天）。
+ * - 分组：`--by day|week|month|provider|channel|model|project`。
+ * - 缓存：`<数据目录>/stats-index.json`，按文件 mtime / size 失效；`--no-cache` 不读也不写。
+ * - 口径见 session/stats-aggregate.ts 与 docs/sessions.md「统计」。
+ */
+import { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { sessionFilesInScope } from "../../session/scan.js";
+import { STATS_GROUPS, aggregateStats, } from "../../session/stats-aggregate.js";
+import { STATS_INDEX_FILE, collectSummaries } from "../../session/stats-index.js";
+import { localDay } from "../../session/stats-scan.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const STATS_USAGE = `用法：ama stats [--since 7d|30d|today|YYYY-MM-DD] [--until …]
+                 [--by day|week|month|provider|channel|model|project]
+                 [--project <目录> | --all] [--top N] [--json] [--no-cache] [--session-dir <目录>]
+`;
+/** `7d` / `today` / `YYYY-MM-DD` → 本地日期。 */
+export function parseDaySpec(option, raw, now = new Date()) {
+    if (raw === "today")
+        return localDay(now.toISOString()) ?? "";
+    const rel = /^(\d+)d$/.exec(raw);
+    if (rel !== null) {
+        const days = Number(rel[1]);
+        if (days < 1)
+            throw new UsageError(`--${option} 的天数至少为 1（收到 ${raw}）`);
+        const d = new Date(now);
+        d.setDate(d.getDate() - (days - 1));
+        return localDay(d.toISOString()) ?? "";
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) && Number.isFinite(Date.parse(`${raw}T00:00:00`)))
+        return raw;
+    throw new UsageError(`--${option} 应为 7d、today 或 YYYY-MM-DD（收到 ${raw}）`);
+}
+export function formatTokens(count) {
+    const trim = (text) => text.replace(/\.?0+$/, "");
+    if (count < 1000)
+        return String(Math.round(count));
+    if (count < 100_000)
+        return `${trim((count / 1000).toFixed(1))}k`;
+    if (count < 1_000_000)
+        return `${Math.round(count / 1000)}k`;
+    return `${trim((count / 1_000_000).toFixed(2))}M`;
+}
+const percent = (rate) => rate === undefined ? "—" : `${(rate * 100).toFixed(1)}%`;
+const usd = (t) => {
+    if (t.cost === undefined)
+        return "—";
+    return t.cost >= 1 || t.cost === 0 ? `$${t.cost.toFixed(2)}` : `$${t.cost.toFixed(4)}`;
+};
+function seconds(ms) {
+    if (ms === undefined)
+        return "—";
+    return ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${(ms / 60_000).toFixed(1)}m`;
+}
+function width(text) {
+    let w = 0;
+    for (const ch of text)
+        w += (ch.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1;
+    return w;
+}
+function table(rows, rightAlign) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, width(cell))));
+    return rows
+        .map((row) => row
+        .map((cell, i) => {
+        const padding = " ".repeat((widths[i] ?? 0) - width(cell));
+        return rightAlign(i) ? padding + cell : cell + padding;
+    })
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+export function renderStats(report, scope) {
+    const t = report.totals;
+    const range = report.since === undefined && report.until === undefined
+        ? "全部时间"
+        : `${report.since ?? "最早"} – ${report.until ?? "今天"}`;
+    const lines = [`${range} · ${scope} · ${report.sessions} 个会话`];
+    if (t.requests === 0) {
+        lines.push("没有模型请求");
+        return lines.join("\n") + "\n";
+    }
+    const kinds = Object.entries(report.byKind)
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, n]) => `${kind === "turn" ? "对话" : kind} ${n}`)
+        .join(" · ");
+    const costLine = t.cost === undefined
+        ? "— （所有请求的模型都无价格，见 token）"
+        : t.unpriced > 0
+            ? `${usd(t)}（另有 ${t.unpriced} 次请求无价，未计入）`
+            : usd(t);
+    const rows = [
+        ["请求", `${t.requests}（${kinds}）`],
+        ["回合", `${t.turns} · 平均耗时 ${seconds(t.avgTurnMs)}`],
+        [
+            "Token",
+            `输入 ${formatTokens(t.input)} · 输出 ${formatTokens(t.output)} · 缓存读 ${formatTokens(t.cacheRead)} · 缓存写 ${formatTokens(t.cacheWrite)}`,
+        ],
+        [
+            "缓存命中率",
+            `${percent(t.hitRate)}（报告缓存的端点 ${report.endpoints.reported}/${report.endpoints.total}，其余不进分母）`,
+        ],
+        ["费用", costLine],
+        ["错误 / 重试", `${t.errors} / ${t.retries}`],
+    ];
+    lines.push(table(rows, () => false));
+    if (report.groups !== undefined && report.groups.length > 0) {
+        const head = ["", "会话", "请求", "回合", "输入", "输出", "缓存读", "缓存写", "命中率", "费用"];
+        const body = report.groups.map((g) => [
+            g.key,
+            String(g.sessions),
+            String(g.requests),
+            String(g.turns),
+            formatTokens(g.input),
+            formatTokens(g.output),
+            formatTokens(g.cacheRead),
+            formatTokens(g.cacheWrite),
+            percent(g.hitRate),
+            usd(g) + (g.cost !== undefined && g.unpriced > 0 ? "+" : ""),
+        ]);
+        lines.push("", table([head, ...body], (i) => i > 0));
+    }
+    if (report.tools.length > 0) {
+        lines.push("", `工具调用 Top ${report.tools.length}`);
+        lines.push(table(report.tools.map((tool) => [`  ${tool.name}`, String(tool.count)]), (i) => i > 0));
+    }
+    return lines.join("\n") + "\n";
+}
+export async function runStats(argv, io) {
+    const { positionals, values, flags } = parseSubArgs(argv, ["since", "until", "by", "project", "session-dir", "top"], ["all", "json", "no-cache"]);
+    if (flags.has("help")) {
+        io.stdout(STATS_USAGE);
+        return ExitCode.Ok;
+    }
+    if (positionals.length > 0)
+        throw new UsageError(`ama stats 不接受位置参数：${positionals[0]}`);
+    const now = new Date();
+    const since = values.has("since") ? parseDaySpec("since", values.get("since"), now) : undefined;
+    const until = values.has("until") ? parseDaySpec("until", values.get("until"), now) : undefined;
+    const byRaw = values.get("by");
+    if (byRaw !== undefined && !STATS_GROUPS.includes(byRaw)) {
+        throw new UsageError(`--by 的取值应为 ${STATS_GROUPS.join(" | ")}（收到 ${byRaw}）`);
+    }
+    const by = byRaw;
+    const top = Number(values.get("top") ?? "10");
+    if (!Number.isInteger(top) || top < 0)
+        throw new UsageError("--top 应为非负整数");
+    if (flags.has("all") && values.has("project")) {
+        throw new UsageError("--project 与 --all 不能同时使用");
+    }
+    const dataDir = resolveDataDir({ env: io.env });
+    const dirFlag = values.get("session-dir");
+    const root = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : join(dataDir, "sessions");
+    const projectFlag = values.get("project");
+    const project = projectFlag !== undefined
+        ? resolve(io.cwd, expandHome(projectFlag, { env: io.env }))
+        : flags.has("all") || by === "project"
+            ? undefined
+            : io.cwd;
+    const files = sessionFilesInScope(root, project);
+    const useCache = !flags.has("no-cache");
+    const collected = collectSummaries(files, {
+        ...(useCache ? { indexFile: join(dataDir, STATS_INDEX_FILE) } : {}),
+        prune: project === undefined,
+    });
+    const report = aggregateStats(collected.summaries, {
+        ...(since !== undefined ? { since } : {}),
+        ...(until !== undefined ? { until } : {}),
+        ...(by !== undefined ? { by } : {}),
+        topTools: top,
+    });
+    if (flags.has("json")) {
+        io.stdout(JSON.stringify({
+            scope: project === undefined ? { all: true } : { project },
+            ...report,
+            files: {
+                total: files.length,
+                scanned: collected.scanned,
+                cached: collected.cached,
+                invalid: collected.invalid,
+            },
+        }, null, 2) + "\n");
+        return ExitCode.Ok;
+    }
+    io.stdout(renderStats(report, project === undefined ? "全部项目" : `项目 ${project}`));
+    if (collected.invalid > 0)
+        io.stderr(`ama: 跳过 ${collected.invalid} 个无法读取的会话文件\n`);
+    return ExitCode.Ok;
+}

package/dist/cli/system-prompt-arg.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import type { SystemPromptOverride } from "./deps.js";
+export declare function resolveSystemPromptArg(value: string | undefined, mode: "append" | "replace" | undefined, cwd: string): SystemPromptOverride | undefined;

package/dist/cli/system-prompt-arg.js

@@ -0,0 +1,34 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+import { ExitCode } from "./exit-codes.js";
+export function resolveSystemPromptArg(value, mode, cwd) {
+    if (value === undefined)
+        return undefined;
+    let text = value;
+    if (value.startsWith("@")) {
+        const raw = value.slice(1);
+        const path = isAbsolute(raw) ? raw : resolve(cwd, raw);
+        try {
+            if (!statSync(path).isFile())
+                throw new Error("not a file");
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            throw new StartupError("config_invalid", `--system-prompt 文件不存在：${path}`, ExitCode.Config);
+        }
+    }
+    text = text.trim();
+    if (text === "")
+        throw new StartupError("config_invalid", "--system-prompt 的内容为空", ExitCode.Config);
+    return { text, mode: mode ?? "append" };
+}

package/dist/codemode/modes.d.ts

@@ -4,20 +4,13 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import type { CodemodeMode } from "../config/types.js";
 import { type PresetResolution, type PresetToolRegistry } from "../tools/presets.js";
-import type { ToolDefinition } from "../tools/types.js";
-export declare function codemodeHint(name: string): string;
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export declare function withCodemodeHint<I>(tool: ToolDefinition<I>): ToolDefinition<I>;
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export declare function decorateForMode(mode: CodemodeMode): <I>(tool: ToolDefinition<I>) => ToolDefinition<I>;
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export declare function applyCodemodeMode(registry: PresetToolRegistry, resolution: Pick<PresetResolution, "builtin" | "codemode">): void;

package/dist/codemode/modes.js

@@ -4,36 +4,14 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import { CODEMODE_TOOL } from "../tools/presets.js";
-export function codemodeHint(name) {
-    return `Also callable inside codemode scripts as tools.${name}(args).`;
-}
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export function withCodemodeHint(tool) {
-    const copy = Object.create(Object.getPrototypeOf(tool), {
-        ...Object.getOwnPropertyDescriptors(tool),
-    });
-    Object.defineProperty(copy, "description", {
-        value: `${tool.description}\n${codemodeHint(tool.name)}`,
-        enumerable: true,
-        writable: false,
-        configurable: true,
-    });
-    return copy;
-}
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export function decorateForMode(mode) {
-    if (mode !== "on")
-        return (tool) => tool;
-    return (tool) => (tool.name === CODEMODE_TOOL ? tool : withCodemodeHint(tool));
-}
+import {} from "../tools/presets.js";
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export function applyCodemodeMode(registry, resolution) {
     registry.setPresetTools(resolution.builtin, { exclusive: resolution.codemode === "only" });

package/dist/codemode/tool.d.ts

@@ -12,7 +12,11 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
+import type { AmaConfig } from "../config/types.js";
 import type { ToolDefinition, ToolResult } from "../tools/types.js";
 import { type SandboxCapability } from "./capability.js";
 import { type DeclarableTool } from "./declarations.js";
@@ -25,6 +29,8 @@ export interface CallableTool {
     tool: DeclarableTool;
     /** 内置工具（非 bash）解析为文本；宿主 / SDK 工具可能返回结构化值。 */
     textResult: boolean;
+    /** 模型也能直接调用（在活动集里）；`on` 模式的描述只列名字。 */
+    direct?: boolean;
 }
 export interface CodemodeToolOptions {
     /** 脚本里可调用的工具（不含 codemode 本身）；描述冻结时与每次执行时各调用一次。 */
@@ -37,6 +43,8 @@ export interface CodemodeToolOptions {
     maxResultChars?: number;
     /** `only` 模式：其它工具不直接暴露，系统提示的工具行与规则写明只能在脚本里调用。 */
     exclusive?: boolean;
+    /** 描述的写法：缺省 `only`（按预算内联声明）；`on` 只列名字（见 `buildCodemodeDescription`）。 */
+    layout?: DescriptionLayout;
     /** 子进程入口（测试 / 嵌入方覆盖）。 */
     entry?: string;
     nodePath?: string;
@@ -68,7 +76,8 @@ export declare const CODEMODE_EXAMPLE: readonly string[];
  * （实测模型常见的两种错误）。其它错误原样返回。
  */
 export declare function scriptErrorHint(error: string, toolNames: readonly string[]): string;
-export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability): string;
+export type DescriptionLayout = "only" | "on";
+export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability, layout?: DescriptionLayout): string;
 /** 结果文本：状态行 + 输出（超限保留首尾）+ 失败原因。 */
 export declare function formatCodemodeResult(run: Pick<SandboxRunResult, "ok" | "error" | "outputs" | "elapsedMs" | "droppedChars">, limitChars: number, saveFull: (text: string) => string | undefined): {
     text: string;
@@ -79,27 +88,22 @@ export declare const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the
 export declare function createCodemodeTool(options: CodemodeToolOptions): ToolDefinition<CodemodeInput>;
 /** 组装根用：从 ToolFactoryContext 的形状取所需（避免 codemode → cli 的依赖）。 */
 export interface CodemodeFactoryContext {
-    config: {
-        codemode?: {
-            mode?: "off" | "on" | "only";
-            inlineBudget?: number;
-            requireStrict?: boolean;
-        };
-        tools?: {
-            preset?: string;
-            maxToolResultChars?: number;
-        };
-    };
+    config: Pick<AmaConfig, "tools" | "codemode">;
     registry: {
         list(): readonly string[];
         get(name: string): ToolDefinition | undefined;
     } & {
         sourceOf?(name: string): string | undefined;
+        /** 活动集（coordinator 预设下脚本只能调这些）。 */
+        active?(): readonly {
+            name: string;
+        }[];
     };
     warn(message: string): void;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export declare function codemodeToolFactory(overrides?: Partial<Pick<CodemodeToolOptions, "capability" | "entry" | "nodePath">>): (ctx: CodemodeFactoryContext) => ToolDefinition | undefined;

package/dist/codemode/tool.js

@@ -12,14 +12,17 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { codemodeCallableFilter, resolveCodemodeMode } from "../tools/presets.js";
 import { codemodeAvailability, detectSandboxCapability, } from "./capability.js";
-import { DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
+import { BASH_RESULT_DECLARATION, DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
 import { runSandbox } from "./host-side.js";
-import { codemodeHint } from "./modes.js";
 import { parseOptionsLine } from "./protocol.js";
 import { commitStore, readStore } from "./store.js";
 export const CODEMODE_TOOL_NAME = "codemode";
@@ -54,13 +57,6 @@ export function toScriptValue(name, result) {
         throw new Error(textOf(result.content) || `Tool ${name} failed`);
     return result.structured !== undefined ? result.structured : textOf(result.content);
 }
-/** on 模式下其它工具描述末尾的提示不进声明。 */
-function declarable(tool) {
-    const suffix = `\n${codemodeHint(tool.name)}`;
-    if (!tool.description.endsWith(suffix))
-        return tool;
-    return { ...tool, description: tool.description.slice(0, -suffix.length) };
-}
 /** 描述里的示例脚本（6 行）：并发两个 read、过滤、return。 */
 export const CODEMODE_EXAMPLE = [
     "const [a, b] = await Promise.all([",
@@ -86,7 +82,39 @@ export function scriptErrorHint(error, toolNames) {
     }
     return error;
 }
-export function buildCodemodeDescription(tools, inlineBudget, capability) {
+/**
+ * `on` 模式的描述：规则压成三行 + 示例；已直接暴露的工具只列名字（参数同直接调用），仅脚本可调用的
+ * 工具也只列名字。不内联任何声明，字节只依赖工具名与沙箱能力。
+ */
+function buildOnDescription(tools, capability) {
+    const names = (list) => list
+        .map(({ tool }) => tool.name)
+        .sort()
+        .join(", ");
+    const direct = tools.filter((t) => t.direct === true);
+    const scriptOnly = tools.filter((t) => t.direct !== true);
+    const lines = [
+        "Run a JavaScript script that calls tools; only its output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
+        "Input: raw JavaScript (not JSON, no code fence), the body of an async function (top-level await and return work). Only tools.<name>(args) exists: no require, import, process, fetch or timers.",
+        "Example:",
+        ...CODEMODE_EXAMPLE,
+        "tools.<name>(args) returns a Promise that rejects when the call fails or is denied (Promise.allSettled keeps the rest); text(v) / console.log(...) append output; return v is text(v); store(key, v) / load(key) keep small JSON values across scripts; describeTool(name) returns a signature. At most 8 calls run at once, each through the normal permissions.",
+    ];
+    if (!capability.strict)
+        lines.push(`Sandbox: ${capability.reason}.`);
+    if (direct.length > 0) {
+        const bash = direct.some(({ tool }) => tool.name === "bash");
+        lines.push(`Your direct tools are callable here too, same arguments: ${names(direct)}${bash ? " (tools.bash resolves to BashResult; the others to text)" : ""}.`);
+        if (bash)
+            lines.push(BASH_RESULT_DECLARATION);
+    }
+    if (scriptOnly.length > 0)
+        lines.push(`Callable only from scripts: ${names(scriptOnly)}.`);
+    return lines.join("\n");
+}
+export function buildCodemodeDescription(tools, inlineBudget, capability, layout = "only") {
+    if (layout === "on")
+        return buildOnDescription(tools, capability);
     const lines = [
         "Run a JavaScript script that calls tools; only the script's output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
         "Only tools.<name>(args) is available. There is no require, import, process, fetch or timers; do not call tools directly as functions.",
@@ -98,7 +126,7 @@ export function buildCodemodeDescription(tools, inlineBudget, capability) {
     if (!capability.strict) {
         lines.push(`Sandbox: ${capability.reason}.`);
     }
-    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool: declarable(tool), textResult })), inlineBudget);
+    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool, textResult })), inlineBudget);
     if (block.text !== "")
         lines.push(block.text);
     return lines.join("\n");
@@ -151,7 +179,7 @@ export function createCodemodeTool(options) {
         name: CODEMODE_TOOL_NAME,
         label: "Codemode",
         get description() {
-            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability);
+            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability, options.layout);
             return frozenDescription;
         },
         parameters: {
@@ -179,8 +207,10 @@ export function createCodemodeTool(options) {
             }
             const tools = options.listTools().map(({ tool: t, textResult }) => ({
                 name: t.name,
-                declaration: toolDeclaration(declarable(t), textResult ? {} : { textResult: false }),
+                declaration: toolDeclaration(t, textResult ? {} : { textResult: false }),
             }));
+            // 只有清单里的工具可调（coordinator 预设的清单只含活动集）；脚本拼出别的名字也不放行。
+            const callable = new Set(tools.map((t) => t.name));
             let tail = "";
             const run = await runSandbox({
                 script: input.script,
@@ -190,7 +220,11 @@ export function createCodemodeTool(options) {
                 signal: ctx.signal,
                 ...(options.entry !== undefined ? { entry: options.entry } : {}),
                 ...(options.nodePath !== undefined ? { nodePath: options.nodePath } : {}),
-                callTool: async (name, args, signal) => toScriptValue(name, await ctx.tools.executeTool(name, args, { signal })),
+                callTool: async (name, args, signal) => {
+                    if (!callable.has(name))
+                        throw new Error(`Tool ${name} is not available in codemode`);
+                    return toScriptValue(name, await ctx.tools.executeTool(name, args, { signal }));
+                },
                 onOutput: (text) => {
                     tail = `${tail}${tail === "" ? "" : "\n"}${text}`.slice(-TAIL_CHARS);
                     ctx.onUpdate(tail);
@@ -240,33 +274,42 @@ export function createCodemodeTool(options) {
     return tool;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export function codemodeToolFactory(overrides = {}) {
     return (ctx) => {
-        const explicit = ctx.config.codemode?.mode;
-        const mode = explicit ?? (ctx.config.tools?.preset === "codemode" ? "only" : "off");
+        const capability = overrides.capability ?? detectSandboxCapability();
+        const mode = resolveCodemodeMode(ctx.config, capability.strict).mode;
         if (mode === "off")
             return undefined;
-        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, overrides.capability ?? detectSandboxCapability());
+        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, capability);
         if (!availability.available) {
             ctx.warn(availability.warning);
             return undefined;
         }
         const registry = ctx.registry;
+        const onlyActive = codemodeCallableFilter(ctx.config) === "active";
+        const allowed = (name) => !onlyActive || (registry.active?.() ?? []).some((tool) => tool.name === name);
+        const direct = () => new Set(mode === "on" ? (registry.active?.() ?? []).map((tool) => tool.name) : []);
         const options = {
             capability: availability.capability,
             exclusive: mode === "only",
-            listTools: () => registry
-                .list()
-                .filter((name) => name !== CODEMODE_TOOL_NAME)
-                .map((name) => registry.get(name))
-                .filter((t) => t !== undefined)
-                .map((t) => ({
-                tool: t,
-                textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
-            })),
+            layout: mode === "on" ? "on" : "only",
+            listTools: () => {
+                const active = direct();
+                return registry
+                    .list()
+                    .filter((name) => name !== CODEMODE_TOOL_NAME && allowed(name))
+                    .map((name) => registry.get(name))
+                    .filter((t) => t !== undefined)
+                    .map((t) => ({
+                    tool: t,
+                    textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
+                    ...(active.has(t.name) ? { direct: true } : {}),
+                }));
+            },
         };
         const budget = ctx.config.codemode?.inlineBudget;
         if (budget !== undefined)