@armadra/agent 0.3.0 → 0.4.0

package/dist/session/stats-aggregate.js

@@ -0,0 +1,163 @@
+/**
+ * `ama stats` 的汇总（纯函数）：文件摘要 → 合计、分组、按来源的请求数、工具 Top N。[W4-D]
+ *
+ * 口径（与 `/session`、`get_session_stats` 一致）：
+ * - 请求 = 每次模型请求（回合里的 assistant、保温、权限分类、压缩摘要…），按 kind 分开计；
+ * - 命中率 = cacheRead /（input + cacheRead + cacheWrite），只算「报告缓存」的端点：同一
+ *   provider/model@channel 在扫描范围内出现过任何非零缓存读写才算；其余端点不进分母；
+ * - 费用只加有价请求；`unpriced` 是无价请求数（全无价时 cost 缺省，展示层只给 token）。
+ */
+export const STATS_GROUPS = [
+    "day",
+    "week",
+    "month",
+    "provider",
+    "channel",
+    "model",
+    "project",
+];
+const newAcc = () => ({
+    requests: 0,
+    turns: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    costed: 0,
+    hitRead: 0,
+    hitPrompt: 0,
+    errors: 0,
+    retries: 0,
+    turnMs: 0,
+    timedTurns: 0,
+    sessions: new Set(),
+});
+export function endpointOf(b) {
+    return `${b.provider}/${b.model}${b.channel !== undefined ? `@${b.channel}` : ""}`;
+}
+function add(acc, b, reported, session) {
+    acc.requests += b.requests;
+    acc.turns += b.turns;
+    acc.input += b.input;
+    acc.output += b.output;
+    acc.cacheRead += b.cacheRead;
+    acc.cacheWrite += b.cacheWrite;
+    acc.cost += b.cost;
+    acc.costed += b.costed;
+    if (reported) {
+        acc.hitRead += b.cacheRead;
+        acc.hitPrompt += b.input + b.cacheRead + b.cacheWrite;
+    }
+    acc.errors += b.errors;
+    acc.retries += b.retries;
+    acc.turnMs += b.turnMs;
+    acc.timedTurns += b.timedTurns;
+    acc.sessions.add(session);
+}
+function totals(acc) {
+    const out = {
+        requests: acc.requests,
+        turns: acc.turns,
+        input: acc.input,
+        output: acc.output,
+        cacheRead: acc.cacheRead,
+        cacheWrite: acc.cacheWrite,
+        unpriced: acc.requests - acc.costed,
+        errors: acc.errors,
+        retries: acc.retries,
+    };
+    if (acc.costed > 0)
+        out.cost = acc.cost;
+    if (acc.hitPrompt > 0)
+        out.hitRate = acc.hitRead / acc.hitPrompt;
+    if (acc.timedTurns > 0)
+        out.avgTurnMs = acc.turnMs / acc.timedTurns;
+    return out;
+}
+/** 本地日期 → ISO 周 `2026-W40`。 */
+export function isoWeek(day) {
+    const [y = 0, m = 1, d = 1] = day.split("-").map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    const weekday = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - weekday);
+    const yearStart = Date.UTC(date.getUTCFullYear(), 0, 1);
+    const week = Math.ceil(((date.getTime() - yearStart) / 86_400_000 + 1) / 7);
+    return `${date.getUTCFullYear()}-W${week < 10 ? `0${week}` : week}`;
+}
+function groupKey(by, b, cwd) {
+    switch (by) {
+        case "day":
+            return b.day;
+        case "week":
+            return isoWeek(b.day);
+        case "month":
+            return b.day.slice(0, 7);
+        case "provider":
+            return b.provider;
+        case "channel":
+            return endpointOf(b);
+        case "model":
+            return `${b.provider}/${b.model}`;
+        case "project":
+            return cwd;
+    }
+}
+export function aggregateStats(summaries, options = {}) {
+    const inRange = (day) => (options.since === undefined || day >= options.since) &&
+        (options.until === undefined || day <= options.until);
+    const reported = new Set();
+    const endpoints = new Set();
+    for (const s of summaries)
+        for (const b of s.buckets) {
+            endpoints.add(endpointOf(b));
+            if (b.cacheSeen)
+                reported.add(endpointOf(b));
+        }
+    const all = newAcc();
+    const groups = new Map();
+    const byKind = {};
+    const tools = new Map();
+    for (const s of summaries) {
+        for (const b of s.buckets) {
+            if (!inRange(b.day))
+                continue;
+            const isReported = reported.has(endpointOf(b));
+            add(all, b, isReported, s.id);
+            byKind[b.kind] = (byKind[b.kind] ?? 0) + b.requests;
+            if (options.by !== undefined) {
+                const key = groupKey(options.by, b, s.cwd);
+                let acc = groups.get(key);
+                if (acc === undefined)
+                    groups.set(key, (acc = newAcc()));
+                add(acc, b, isReported, s.id);
+            }
+        }
+        for (const [day, name, count] of s.tools)
+            if (inRange(day))
+                tools.set(name, (tools.get(name) ?? 0) + count);
+    }
+    const report = {
+        sessions: all.sessions.size,
+        totals: totals(all),
+        byKind,
+        tools: [...tools]
+            .map(([name, count]) => ({ name, count }))
+            .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+            .slice(0, options.topTools ?? 10),
+        endpoints: { reported: reported.size, total: endpoints.size },
+    };
+    if (options.since !== undefined)
+        report.since = options.since;
+    if (options.until !== undefined)
+        report.until = options.until;
+    if (options.by !== undefined) {
+        const timeOrdered = options.by === "day" || options.by === "week" || options.by === "month";
+        report.groups = [...groups]
+            .map(([key, acc]) => ({ key, sessions: acc.sessions.size, ...totals(acc) }))
+            .sort((a, b) => timeOrdered
+            ? a.key.localeCompare(b.key)
+            : b.requests - a.requests || a.key.localeCompare(b.key));
+    }
+    return report;
+}

package/dist/session/stats-index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `ama stats` 的增量索引缓存：`<数据目录>/stats-index.json`。[W4-D]
+ *
+ * - 每个会话文件一条：`{ mtimeMs, size, summary }`；mtime 或 size 变了就重扫，否则直接用摘要。
+ * - 摘要里的日期是本地日期，所以索引记下时区（`Intl` 的 timeZone 与当前 UTC 偏移）；变了整份作废。
+ * - 只是缓存：读不到、版本不对、JSON 坏了都当没有；写入走临时文件 + rename，失败忽略。
+ * - 扫描全部目录时顺带删掉已不存在的文件的条目；只扫一个项目时保留别的条目。
+ */
+import { type FileStatsSummary } from "./stats-scan.js";
+export declare const STATS_INDEX_FILE = "stats-index.json";
+export declare function timeZoneKey(now?: Date): string;
+export interface CollectResult {
+    summaries: FileStatsSummary[];
+    /** 本次重扫的文件数（其余命中缓存）。 */
+    scanned: number;
+    cached: number;
+    /** 无效 / 不可读的文件数。 */
+    invalid: number;
+}
+/**
+ * 取一批文件的摘要。`indexFile` 为 undefined 时不用缓存；`prune` 为 true 时删掉不在 `files` 里的条目。
+ */
+export declare function collectSummaries(files: readonly string[], options?: {
+    indexFile?: string;
+    prune?: boolean;
+}): CollectResult;

package/dist/session/stats-index.js

@@ -0,0 +1,91 @@
+/**
+ * `ama stats` 的增量索引缓存：`<数据目录>/stats-index.json`。[W4-D]
+ *
+ * - 每个会话文件一条：`{ mtimeMs, size, summary }`；mtime 或 size 变了就重扫，否则直接用摘要。
+ * - 摘要里的日期是本地日期，所以索引记下时区（`Intl` 的 timeZone 与当前 UTC 偏移）；变了整份作废。
+ * - 只是缓存：读不到、版本不对、JSON 坏了都当没有；写入走临时文件 + rename，失败忽略。
+ * - 扫描全部目录时顺带删掉已不存在的文件的条目；只扫一个项目时保留别的条目。
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { summarizeSessionFile } from "./stats-scan.js";
+export const STATS_INDEX_FILE = "stats-index.json";
+const INDEX_VERSION = 1;
+export function timeZoneKey(now = new Date()) {
+    let zone = "";
+    try {
+        zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        // 无 Intl 时只看偏移
+    }
+    return `${zone}|${now.getTimezoneOffset()}`;
+}
+/**
+ * 取一批文件的摘要。`indexFile` 为 undefined 时不用缓存；`prune` 为 true 时删掉不在 `files` 里的条目。
+ */
+export function collectSummaries(files, options = {}) {
+    const zone = timeZoneKey();
+    let index = { version: INDEX_VERSION, zone, files: {} };
+    if (options.indexFile !== undefined) {
+        try {
+            const loaded = JSON.parse(readFileSync(options.indexFile, "utf8"));
+            if (loaded.version === INDEX_VERSION &&
+                loaded.zone === zone &&
+                typeof loaded.files === "object")
+                index = loaded;
+        }
+        catch {
+            // 没有或坏了：重建
+        }
+    }
+    let dirty = false;
+    const result = { summaries: [], scanned: 0, cached: 0, invalid: 0 };
+    for (const file of files) {
+        let stat;
+        try {
+            stat = statSync(file);
+        }
+        catch {
+            result.invalid++;
+            continue;
+        }
+        const hit = index.files[file];
+        let summary;
+        if (hit !== undefined && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) {
+            summary = hit.summary;
+            result.cached++;
+        }
+        else {
+            summary = summarizeSessionFile(file) ?? null;
+            result.scanned++;
+            index.files[file] = { mtimeMs: stat.mtimeMs, size: stat.size, summary };
+            dirty = true;
+        }
+        if (summary === null)
+            result.invalid++;
+        else
+            result.summaries.push(summary);
+    }
+    if (options.prune === true) {
+        const keep = new Set(files);
+        for (const key of Object.keys(index.files)) {
+            if (!keep.has(key)) {
+                delete index.files[key];
+                dirty = true;
+            }
+        }
+    }
+    if (dirty && options.indexFile !== undefined) {
+        try {
+            mkdirSync(dirname(options.indexFile), { recursive: true, mode: 0o700 });
+            const tmp = `${options.indexFile}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(index), { mode: 0o600 });
+            renameSync(tmp, options.indexFile);
+        }
+        catch {
+            // 缓存写不进去不影响结果
+        }
+    }
+    return result;
+}

package/dist/session/stats-scan.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `ama stats` 的单文件摘要（只读、按行）。[W4-D]
+ *
+ * 一个会话文件 → 若干「桶」：按（本地日期、请求来源 kind、provider、model、channel）累加。
+ * - 请求来源：assistant 消息 = `turn`；`usage` 条目用自己的 `kind`（cache_warm、permission_classify…）；
+ *   `compaction` / `branch_summary` 带的 usage 记为同名 kind（模型取最近一条 assistant 的）。
+ * - token：input（不含缓存）/ output / cacheRead / cacheWrite；费用只累加有 `usage.cost` 的请求，
+ *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。
+ * - 缓存三态：桶记下是否出现过 cacheRead > 0 或 cacheWrite > 0（`cacheSeen`）；汇总时同一端点
+ *   （provider/model@channel）任一桶出现过即算报告缓存，其余端点不进命中率分母（同会话层三态）。
+ * - 回合：非 `steer` 的用户消息开始一个回合，到下一个回合开始为止；回合计入首条 assistant 的桶，
+ *   耗时 = 最后一条 assistant 条目时间 − 用户消息条目时间（都是落盘时间戳）。没有 assistant 的回合不计。
+ * - 工具调用：assistant 内容里的 toolCall 块按名字计（codemode 内层调用不展开）。
+ * - 重试：`context_edit{reason:"retry"}` 计入当时最近一条 assistant 的桶；`stopReason:"error"` 计错误。
+ * - toolResult、custom、label 等行按前缀跳过、不解析；末尾半行忽略；中间坏行跳过并计数。
+ * - channel：最近一条 `model_change` 与该请求同 provider / model 时取它的 channel。
+ */
+export interface StatsBucket {
+    /** 本地日期 YYYY-MM-DD。 */
+    day: string;
+    kind: string;
+    provider: string;
+    model: string;
+    channel?: string;
+    requests: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 有价请求的费用合计（美元）。 */
+    cost: number;
+    /** 有价请求数。 */
+    costed: number;
+    /** 出现过 cacheRead > 0 或 cacheWrite > 0。 */
+    cacheSeen: boolean;
+    errors: number;
+    retries: number;
+    turns: number;
+    /** 有耗时的回合的耗时合计与个数。 */
+    turnMs: number;
+    timedTurns: number;
+}
+export interface FileStatsSummary {
+    id: string;
+    cwd: string;
+    buckets: StatsBucket[];
+    /** `[日期, 工具名, 次数]`。 */
+    tools: Array<[string, string, number]>;
+    /** 跳过的坏行数。 */
+    badLines: number;
+}
+/** ISO → 本地日期；不可解析 → undefined。 */
+export declare function localDay(iso: unknown): string | undefined;
+export declare function summarizeSessionFile(file: string): FileStatsSummary | undefined;

package/dist/session/stats-scan.js

@@ -0,0 +1,236 @@
+/**
+ * `ama stats` 的单文件摘要（只读、按行）。[W4-D]
+ *
+ * 一个会话文件 → 若干「桶」：按（本地日期、请求来源 kind、provider、model、channel）累加。
+ * - 请求来源：assistant 消息 = `turn`；`usage` 条目用自己的 `kind`（cache_warm、permission_classify…）；
+ *   `compaction` / `branch_summary` 带的 usage 记为同名 kind（模型取最近一条 assistant 的）。
+ * - token：input（不含缓存）/ output / cacheRead / cacheWrite；费用只累加有 `usage.cost` 的请求，
+ *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。
+ * - 缓存三态：桶记下是否出现过 cacheRead > 0 或 cacheWrite > 0（`cacheSeen`）；汇总时同一端点
+ *   （provider/model@channel）任一桶出现过即算报告缓存，其余端点不进命中率分母（同会话层三态）。
+ * - 回合：非 `steer` 的用户消息开始一个回合，到下一个回合开始为止；回合计入首条 assistant 的桶，
+ *   耗时 = 最后一条 assistant 条目时间 − 用户消息条目时间（都是落盘时间戳）。没有 assistant 的回合不计。
+ * - 工具调用：assistant 内容里的 toolCall 块按名字计（codemode 内层调用不展开）。
+ * - 重试：`context_edit{reason:"retry"}` 计入当时最近一条 assistant 的桶；`stopReason:"error"` 计错误。
+ * - toolResult、custom、label 等行按前缀跳过、不解析；末尾半行忽略；中间坏行跳过并计数。
+ * - channel：最近一条 `model_change` 与该请求同 provider / model 时取它的 channel。
+ */
+import { forEachLine, lineType } from "./scan.js";
+const SKIP_TYPES = new Set([
+    "custom",
+    "custom_message",
+    "label",
+    "leaf",
+    "session_info",
+    "thinking_level_change",
+]);
+function pad(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+/** ISO → 本地日期；不可解析 → undefined。 */
+export function localDay(iso) {
+    if (typeof iso !== "string")
+        return undefined;
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return undefined;
+    const d = new Date(ms);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+export function summarizeSessionFile(file) {
+    let header;
+    const buckets = new Map();
+    const tools = new Map();
+    let badLines = 0;
+    let channel;
+    let lastAssistant;
+    let lastBucket;
+    let turn;
+    const bucketOf = (day, kind, ref) => {
+        const key = `${day}\u0000${kind}\u0000${ref.provider}\u0000${ref.model}\u0000${ref.channel ?? ""}`;
+        let bucket = buckets.get(key);
+        if (bucket === undefined) {
+            bucket = {
+                day,
+                kind,
+                provider: ref.provider,
+                model: ref.model,
+                requests: 0,
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                cost: 0,
+                costed: 0,
+                cacheSeen: false,
+                errors: 0,
+                retries: 0,
+                turns: 0,
+                turnMs: 0,
+                timedTurns: 0,
+            };
+            if (ref.channel !== undefined)
+                bucket.channel = ref.channel;
+            buckets.set(key, bucket);
+        }
+        return bucket;
+    };
+    const addUsage = (bucket, usage) => {
+        bucket.requests++;
+        if (!isRec(usage))
+            return;
+        const u = usage;
+        bucket.input += num(u.input);
+        bucket.output += num(u.output);
+        bucket.cacheRead += num(u.cacheRead);
+        bucket.cacheWrite += num(u.cacheWrite);
+        if (num(u.cacheRead) > 0 || num(u.cacheWrite) > 0)
+            bucket.cacheSeen = true;
+        if (isRec(u.cost) && typeof u.cost["total"] === "number") {
+            bucket.cost += num(u.cost["total"]);
+            bucket.costed++;
+        }
+    };
+    const refFor = (provider, model) => {
+        const ref = { provider, model };
+        if (channel?.channel !== undefined &&
+            channel.provider === provider &&
+            channel.model === model) {
+            ref.channel = channel.channel;
+        }
+        return ref;
+    };
+    const closeTurn = () => {
+        if (turn?.bucket !== undefined) {
+            turn.bucket.turns++;
+            if (turn.end !== undefined && turn.end >= turn.start) {
+                turn.bucket.turnMs += turn.end - turn.start;
+                turn.bucket.timedTurns++;
+            }
+        }
+        turn = undefined;
+    };
+    try {
+        forEachLine(file, (line, index, last) => {
+            if (index > 0) {
+                const quick = lineType(line);
+                if (quick !== undefined) {
+                    if (SKIP_TYPES.has(quick.type))
+                        return;
+                    if (quick.type === "message" && quick.role === "toolResult")
+                        return;
+                    if (quick.type === "message" && quick.role === "system")
+                        return;
+                }
+            }
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                if (!last)
+                    badLines++;
+                return;
+            }
+            if (!isRec(value))
+                return;
+            if (index === 0) {
+                if (value["type"] !== "session" || typeof value["cwd"] !== "string")
+                    return false;
+                header = value;
+                return;
+            }
+            const ts = value["timestamp"];
+            const day = localDay(ts);
+            if (day === undefined)
+                return;
+            switch (value["type"]) {
+                case "model_change": {
+                    const ref = {
+                        provider: String(value["provider"]),
+                        model: String(value["modelId"]),
+                    };
+                    if (typeof value["channel"] === "string")
+                        ref.channel = value["channel"];
+                    channel = ref;
+                    return;
+                }
+                case "message": {
+                    const message = value["message"];
+                    if (!isRec(message))
+                        return;
+                    if (message["role"] === "user") {
+                        if (message["origin"] === "steer" && turn !== undefined)
+                            return;
+                        closeTurn();
+                        turn = { start: Date.parse(ts), day };
+                        return;
+                    }
+                    if (message["role"] !== "assistant")
+                        return;
+                    const ref = refFor(String(message["provider"]), String(message["model"]));
+                    lastAssistant = ref;
+                    const bucket = bucketOf(day, "turn", ref);
+                    lastBucket = bucket;
+                    addUsage(bucket, message["usage"]);
+                    if (message["stopReason"] === "error")
+                        bucket.errors++;
+                    const content = message["content"];
+                    if (Array.isArray(content)) {
+                        for (const block of content) {
+                            if (isRec(block) &&
+                                block["type"] === "toolCall" &&
+                                typeof block["name"] === "string") {
+                                const key = `${day}\u0000${block["name"]}`;
+                                tools.set(key, (tools.get(key) ?? 0) + 1);
+                            }
+                        }
+                    }
+                    if (turn !== undefined) {
+                        if (turn.bucket === undefined)
+                            turn.bucket = bucketOf(turn.day, "turn", ref);
+                        turn.end = Date.parse(ts);
+                    }
+                    return;
+                }
+                case "usage": {
+                    const ref = refFor(String(value["provider"]), String(value["model"]));
+                    addUsage(bucketOf(day, String(value["kind"] ?? "usage"), ref), value["usage"]);
+                    return;
+                }
+                case "compaction":
+                case "branch_summary": {
+                    if (value["usage"] === undefined)
+                        return;
+                    const ref = lastAssistant ?? { provider: "?", model: "?" };
+                    addUsage(bucketOf(day, value["type"], ref), value["usage"]);
+                    return;
+                }
+                case "context_edit":
+                    if (value["reason"] === "retry" && lastBucket !== undefined)
+                        lastBucket.retries++;
+                    return;
+                default:
+                    return;
+            }
+        });
+    }
+    catch {
+        return undefined;
+    }
+    closeTurn();
+    if (header === undefined)
+        return undefined;
+    return {
+        id: String(header["id"]),
+        cwd: String(header["cwd"]),
+        buckets: [...buckets.values()],
+        tools: [...tools].map(([key, count]) => {
+            const [day = "", name = ""] = key.split("\u0000");
+            return [day, name, count];
+        }),
+        badLines,
+    };
+}

package/dist/tools/presets.d.ts

@@ -5,27 +5,52 @@
  * | ------------- | ----------------------------------------- |
  * | `default`     | read、edit、write、bash、grep、glob       |
  * | `minimal`     | read、edit、write、bash                   |
- * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `codemode-only` | 只有 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` 同样忽略。
+ * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
+ * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
+ *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
+ *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
+ * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
+ *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPreset } from "../config/types.js";
+import { type AmaConfig, type CodemodeMode, type 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`）。 */
+/** 各预设下模型直接看到的内置工具（codemode-only 预设见 `resolvePreset`）。 */
 export declare const PRESET_TOOLS: Readonly<Record<ToolsPreset, readonly string[]>>;
+/**
+ * 预设对应的 codemode 模式（没有显式 `codemode.mode` 时）。`default` 只在沙箱 strict（Node ≥ 25，
+ * 权限模型同时隔离网络）时开 `on`：Node 22 / 24 下 codemode 属 execute 类，每次都要审批，`-p` 下
+ * 直接被拒，所以缺省关闭（启动时提示一次，见 cli/codemode-notice.ts）。
+ */
+export declare function presetCodemodeMode(preset: ToolsPreset, strict: boolean): CodemodeMode;
+export interface CodemodeModeResolution {
+    mode: CodemodeMode;
+    /** `config`：显式 `codemode.mode`；`preset`：跟随预设。 */
+    source: "config" | "preset";
+    preset: ToolsPreset;
+    strict: boolean;
+}
+/** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
+export declare function resolveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeModeResolution;
 /** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">): CodemodeMode;
+export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeMode;
+/**
+ * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
+ * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
+ */
+export declare function codemodeCallableFilter(config: Pick<AmaConfig, "tools">): "active" | undefined;
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
  * 返回去重后的名字（保持首次出现顺序）。
@@ -43,6 +68,8 @@ export declare function resolvePreset(input: {
     config: Pick<AmaConfig, "tools" | "codemode">;
     /** 该名字是否已注册（且未禁用）。 */
     available(name: string): boolean;
+    /** 沙箱是否 strict；缺省按运行时探测。 */
+    strict?: boolean;
 }): PresetResolution;
 type RegisterListener = (tool: ToolDefinition, source: ToolSource) => void;
 /**