@armadra/agent 0.3.0 → 0.5.0

package/dist/compaction/estimate.js

@@ -2,64 +2,106 @@
  * 上下文 token 估算（设计 §9「估算」）。[B2]
  *
  * `contextTokens` = 最后一条非 error / aborted 助手消息的 `totalTokens`（缺则
- * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（字符 / 4，图片 1 600）。
+ * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（图片 1 600）。
  * 若该 usage 之后活动分支上出现过 `context_edit` 或 `compaction`，usage 不再可信，按投影全量重估。
+ *
+ * [W5-H1] 文本估算按脚本区分（wave5 D28 / C10）：CJK 统一表意文字（含扩展区与兼容区）、假名、
+ * 谚文、CJK 符号与全角形式每字 1 token，其余字符合计 / 4 向上取整。「字符 / 4」对中文低估 3–4 倍，
+ * 中文会话会晚触发直至溢出；所有阈值（档一、档二、保留区）都用这个口径。
  */
 export const IMAGE_TOKENS = 1600;
 const CHARS_PER_TOKEN = 4;
+/** 按 1 token / 字计的码位（BMP 内）。 */
+function isWideCode(code) {
+    return ((code >= 0x4e00 && code <= 0x9fff) || // CJK 统一表意文字
+        (code >= 0x3400 && code <= 0x4dbf) || // 扩展 A
+        (code >= 0xf900 && code <= 0xfaff) || // 兼容表意文字
+        (code >= 0x3040 && code <= 0x30ff) || // 平假名、片假名
+        (code >= 0x31f0 && code <= 0x31ff) || // 片假名音标扩展
+        (code >= 0xac00 && code <= 0xd7af) || // 谚文音节
+        (code >= 0x1100 && code <= 0x11ff) || // 谚文字母
+        (code >= 0x3130 && code <= 0x318f) || // 谚文兼容字母
+        (code >= 0x3000 && code <= 0x303f) || // CJK 符号与标点
+        (code >= 0xff00 && code <= 0xffef) // 半角与全角形式
+    );
+}
+/** 文本的 token 估算：CJK / 假名 / 谚文每字 1，其余字符 / 4（向上取整）。 */
+export function estimateTextTokens(text) {
+    return tokensOf(countText(text, { wide: 0, narrow: 0 }));
+}
+function countText(text, into) {
+    let wide = 0;
+    let narrow = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x1100)
+            narrow++;
+        else if (code >= 0xd840 && code <= 0xd87f) {
+            // 补充平面 CJK 扩展 B–F（U+20000–U+2FFFF）的代理对：整对算 1 个字
+            wide++;
+            i++;
+        }
+        else if (isWideCode(code))
+            wide++;
+        else
+            narrow++;
+    }
+    into.wide += wide;
+    into.narrow += narrow;
+    return into;
+}
+function tokensOf(count) {
+    return count.wide + Math.ceil(count.narrow / CHARS_PER_TOKEN);
+}
 export function calculateContextTokens(usage) {
     return usage.totalTokens > 0
         ? usage.totalTokens
         : usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
 }
-function contentChars(content) {
+/** 内容的估算（文本按脚本，图片每张 1 600）。 */
+export function estimateContentTokens(content) {
     if (typeof content === "string")
-        return { chars: content.length, images: 0 };
-    let chars = 0;
+        return estimateTextTokens(content);
+    const count = { wide: 0, narrow: 0 };
     let images = 0;
     for (const block of content) {
         if (block.type === "text")
-            chars += block.text.length;
+            countText(block.text, count);
         else
             images++;
     }
-    return { chars, images };
+    return tokensOf(count) + images * IMAGE_TOKENS;
 }
-/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+/** 单条消息的估算（文本按脚本区分，图片每张 1 600）。 */
 export function estimateMessageTokens(message) {
-    let chars = 0;
-    let images = 0;
+    const count = { wide: 0, narrow: 0 };
     switch (message.role) {
         case "system":
             for (const text of Object.values(message.sections))
-                chars += text?.length ?? 0;
+                countText(text ?? "", count);
             if (message.toolsAdded !== undefined)
-                chars += JSON.stringify(message.toolsAdded).length;
+                countText(JSON.stringify(message.toolsAdded), count);
             break;
         case "user":
         case "toolResult":
-        case "custom": {
-            const counted = contentChars(message.content);
-            chars = counted.chars;
-            images = counted.images;
-            break;
-        }
+        case "custom":
+            return estimateContentTokens(message.content);
         case "assistant":
             for (const block of message.content) {
                 if (block.type === "text")
-                    chars += block.text.length;
+                    countText(block.text, count);
                 else if (block.type === "thinking")
-                    chars += block.thinking.length;
+                    countText(block.thinking, count);
                 else
-                    chars += block.name.length + JSON.stringify(block.arguments).length;
+                    countText(block.name + JSON.stringify(block.arguments), count);
             }
             break;
         case "compactionSummary":
         case "branchSummary":
-            chars = message.summary.length;
+            countText(message.summary, count);
             break;
     }
-    return Math.ceil(chars / CHARS_PER_TOKEN) + images * IMAGE_TOKENS;
+    return tokensOf(count);
 }
 export function estimateMessagesTokens(messages) {
     let total = 0;

package/dist/compaction/image-budget.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 单请求图片总量预算（docs/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
+ *
+ * base64 图片在历史里每轮重发，几张截图就可能撞上 Anthropic 32 MB / Gemini 20 MB 的请求上限。
+ * `planImageBudget` 给出要降级的消息：调用方把每条写成 `context_edit{reason:"image_budget"}`，
+ * 之后前缀稳定（不是请求时临时处理），未命中归因把它当重置点。
+ *
+ * 规则（按投影顺序，最旧在前）：
+ * 1. 单张超过 `perImageBytes`（换了更小上限的模型 / 中转）的消息必降——发出去必被拒；
+ * 2. 总量（含本回合新提示里的图 `reserve`）> 预算时，从最旧的开始降，直到 ≤ 预算 × 60%
+ *    （一次多降一些，减少反复失效）；
+ * 3. 图片数 > 20 且还有边长 > 2000 px 的图时，继续从最旧的开始降，直到不超过 20 张或没有大图；
+ * 规则 2、3 不降最新一条带图的消息（刚读的图要让模型看到）。降级以消息为单位：文本块原样保留，
+ * 每个图片块换成占位文本。
+ */
+import type { ContentBlock, ImageBlock } from "../ai/types.js";
+import type { ContextItem } from "../session/projection.js";
+import { type ImageSize } from "../tools/image-file.js";
+export declare const IMAGE_BUDGET_TARGET_RATIO = 0.6;
+export declare const IMAGE_OMITTED_FOR_BUDGET = "[earlier image omitted to fit request size]";
+export declare const IMAGE_OMITTED_TOO_LARGE = "[image omitted: larger than this endpoint's per-image limit]";
+export interface ImageBudgetOptions {
+    /** 单张上限（base64 后）；超过的必降。缺省不检查。 */
+    perImageBytes?: number;
+    /** 本回合即将发送、不能降级的图片（新提示里的附件）：计入总量与张数。 */
+    reserve?: readonly ImageBlock[];
+    /** 降到预算的这个比例以下；缺省 0.6。 */
+    targetRatio?: number;
+    /** 测试注入：图片尺寸。缺省解 base64 读文件头。 */
+    sizeOf?(block: ImageBlock): ImageSize | undefined;
+}
+export interface ImageBudgetEdit {
+    targetId: string;
+    replacement: string;
+    /** `per_image`：单张超限；`budget`：总量；`many_images`：> 20 张时的边长。 */
+    cause: "per_image" | "budget" | "many_images";
+    /** 本条消息里被省略的图片数与 base64 字节。 */
+    images: number;
+    bytes: number;
+}
+/** 降级后的文本：文本块原样，图片块换成 `placeholder`，块间换行。 */
+export declare function budgetReplacement(content: readonly ContentBlock[], placeholder?: string): string;
+/** 解 base64 读文件头取尺寸（先解前 384 KB；JPEG 的 SOF 更靠后时再解全量）；按块缓存。 */
+export declare function base64ImageSize(block: ImageBlock): ImageSize | undefined;
+export declare function planImageBudget(items: readonly ContextItem[], budgetBytes: number, options?: ImageBudgetOptions): ImageBudgetEdit[];

package/dist/compaction/image-budget.js

@@ -0,0 +1,115 @@
+/**
+ * 单请求图片总量预算（docs/wave5-plan.md §4、D11）。[W5-I] 纯函数，无模型调用。
+ *
+ * base64 图片在历史里每轮重发，几张截图就可能撞上 Anthropic 32 MB / Gemini 20 MB 的请求上限。
+ * `planImageBudget` 给出要降级的消息：调用方把每条写成 `context_edit{reason:"image_budget"}`，
+ * 之后前缀稳定（不是请求时临时处理），未命中归因把它当重置点。
+ *
+ * 规则（按投影顺序，最旧在前）：
+ * 1. 单张超过 `perImageBytes`（换了更小上限的模型 / 中转）的消息必降——发出去必被拒；
+ * 2. 总量（含本回合新提示里的图 `reserve`）> 预算时，从最旧的开始降，直到 ≤ 预算 × 60%
+ *    （一次多降一些，减少反复失效）；
+ * 3. 图片数 > 20 且还有边长 > 2000 px 的图时，继续从最旧的开始降，直到不超过 20 张或没有大图；
+ * 规则 2、3 不降最新一条带图的消息（刚读的图要让模型看到）。降级以消息为单位：文本块原样保留，
+ * 每个图片块换成占位文本。
+ */
+import { MANY_IMAGES_COUNT, MANY_IMAGES_EDGE } from "../ai/image-limits.js";
+import { imageSize } from "../tools/image-file.js";
+export const IMAGE_BUDGET_TARGET_RATIO = 0.6;
+export const IMAGE_OMITTED_FOR_BUDGET = "[earlier image omitted to fit request size]";
+export const IMAGE_OMITTED_TOO_LARGE = "[image omitted: larger than this endpoint's per-image limit]";
+function imagesOf(content) {
+    return content.filter((block) => block.type === "image");
+}
+function candidates(items) {
+    const out = [];
+    for (const { entry, message } of items) {
+        if (entry.type !== "message" && entry.type !== "custom_message")
+            continue;
+        if (message.role !== "user" && message.role !== "toolResult" && message.role !== "custom")
+            continue;
+        if (typeof message.content === "string")
+            continue;
+        const images = imagesOf(message.content);
+        if (images.length === 0)
+            continue;
+        const bytes = images.reduce((sum, image) => sum + image.data.length, 0);
+        out.push({ targetId: entry.id, content: message.content, images, bytes });
+    }
+    return out;
+}
+/** 降级后的文本：文本块原样，图片块换成 `placeholder`，块间换行。 */
+export function budgetReplacement(content, placeholder = IMAGE_OMITTED_FOR_BUDGET) {
+    return content
+        .map((block) => (block.type === "text" ? block.text : placeholder))
+        .filter((text) => text !== "")
+        .join("\n");
+}
+const HEAD_CHARS = 512 * 1024;
+const sizeCache = new WeakMap();
+/** 解 base64 读文件头取尺寸（先解前 384 KB；JPEG 的 SOF 更靠后时再解全量）；按块缓存。 */
+export function base64ImageSize(block) {
+    const cached = sizeCache.get(block);
+    if (cached !== undefined)
+        return cached ?? undefined;
+    let size = imageSize(Buffer.from(block.data.slice(0, HEAD_CHARS), "base64"), block.mimeType);
+    if (size === undefined && block.data.length > HEAD_CHARS)
+        size = imageSize(Buffer.from(block.data, "base64"), block.mimeType);
+    sizeCache.set(block, size ?? null);
+    return size;
+}
+export function planImageBudget(items, budgetBytes, options = {}) {
+    const all = candidates(items);
+    const plan = [];
+    const drop = (c, cause) => {
+        const placeholder = cause === "per_image" ? IMAGE_OMITTED_TOO_LARGE : IMAGE_OMITTED_FOR_BUDGET;
+        plan.push({
+            targetId: c.targetId,
+            replacement: budgetReplacement(c.content, placeholder),
+            cause,
+            images: c.images.length,
+            bytes: c.bytes,
+        });
+    };
+    // 1. 单张超限
+    const perImage = options.perImageBytes;
+    const kept = [];
+    for (const c of all) {
+        if (perImage !== undefined && c.images.some((image) => image.data.length > perImage))
+            drop(c, "per_image");
+        else
+            kept.push(c);
+    }
+    const reserve = options.reserve ?? [];
+    let total = kept.reduce((sum, c) => sum + c.bytes, 0) +
+        reserve.reduce((sum, image) => sum + image.data.length, 0);
+    let count = kept.reduce((sum, c) => sum + c.images.length, 0) + reserve.length;
+    // 最新一条带图的消息不降
+    const droppable = kept.slice(0, -1);
+    let next = 0;
+    // 2. 总量
+    if (total > budgetBytes) {
+        const target = budgetBytes * (options.targetRatio ?? IMAGE_BUDGET_TARGET_RATIO);
+        while (total > target && next < droppable.length) {
+            const c = droppable[next++];
+            drop(c, "budget");
+            total -= c.bytes;
+            count -= c.images.length;
+        }
+    }
+    // 3. > 20 张时的边长
+    if (count > MANY_IMAGES_COUNT) {
+        const sizeOf = options.sizeOf ?? base64ImageSize;
+        const tooWide = (image) => {
+            const size = sizeOf(image);
+            return size !== undefined && Math.max(size.width, size.height) > MANY_IMAGES_EDGE;
+        };
+        const remaining = () => reserve.some(tooWide) || kept.slice(next).some((c) => c.images.some(tooWide));
+        while (count > MANY_IMAGES_COUNT && next < droppable.length && remaining()) {
+            const c = droppable[next++];
+            drop(c, "many_images");
+            count -= c.images.length;
+        }
+    }
+    return plan;
+}

package/dist/compaction/post-compact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 压缩后回注（wave5 §8.2 C6，D26）。[W5-H1]
+ *
+ * 把压缩可能丢掉的关键状态以**清单与指针**放回上下文（不含文件正文）：
+ * - todo 快照（分支上最近一条 `ama.todo`）；
+ * - 当前计划（最近一条未被拒绝 / 取代的 `ama.plan`：编号、状态、文件路径与步骤标题）；
+ * - 已加载的 Skill（用 `read` 读过的索引路径，或 `skill` 工具的调用）；
+ * - 最近修改 / 读取的文件路径（按最近使用排序，各至多 20 个）；
+ * - 完整转录与 `outputs/` 路径（模型需要细节时自己 `read`）；
+ * - 续接说明。
+ *
+ * 放在哪：作为 `<post-compact-state>` 块接在 compaction 条目的 `summary` 末尾（与已有的
+ * `<read-files>` / `<modified-files>` 同一做法），模型看到的顺序就是「摘要 → 回注 → 保留区」。
+ * 不另写 `custom_message`：投影把 compaction 之后的条目放在保留区之后，溢出恢复时保留区以用户刚发
+ * 的提示结尾，追加在末尾的回注会排在那条提示后面、让模型先回应回注。压缩后本来就是新前缀，
+ * 回注不额外打断缓存。下一次增量摘要前先剥掉这个块（`stripPostCompact`），每次重新生成。
+ */
+import type { SessionEntry } from "../session/types.js";
+export declare const POST_COMPACT_TAG = "post-compact-state";
+export declare const PLAN_CUSTOM_TYPE = "ama.plan";
+export declare const MAX_RECENT_FILES = 20;
+export interface PostCompactInput {
+    /** 活动分支（含刚追加的 compaction）。 */
+    branch: readonly SessionEntry[];
+    cwd: string;
+    /** Skill 索引里的文件路径（`skillLocations`）。 */
+    skillPaths?: readonly string[];
+    /** 会话转录文件；内存会话 undefined。 */
+    transcriptPath?: string | undefined;
+    /** 裁剪 / 截断全文目录。 */
+    outputDir?: string | undefined;
+}
+/** 去掉摘要里的回注块（上一份摘要作增量合并的输入前、模型照抄进新摘要时）。 */
+export declare function stripPostCompact(summary: string): string;
+/** 回注块（`<post-compact-state>…</post-compact-state>`）；无任何可回注的状态时仍给出续接说明。 */
+export declare function buildPostCompactBlock(input: PostCompactInput): string;
+/** 回注正文。 */
+export declare function buildPostCompactContent(input: PostCompactInput): string;

package/dist/compaction/post-compact.js

@@ -0,0 +1,152 @@
+/**
+ * 压缩后回注（wave5 §8.2 C6，D26）。[W5-H1]
+ *
+ * 把压缩可能丢掉的关键状态以**清单与指针**放回上下文（不含文件正文）：
+ * - todo 快照（分支上最近一条 `ama.todo`）；
+ * - 当前计划（最近一条未被拒绝 / 取代的 `ama.plan`：编号、状态、文件路径与步骤标题）；
+ * - 已加载的 Skill（用 `read` 读过的索引路径，或 `skill` 工具的调用）；
+ * - 最近修改 / 读取的文件路径（按最近使用排序，各至多 20 个）；
+ * - 完整转录与 `outputs/` 路径（模型需要细节时自己 `read`）；
+ * - 续接说明。
+ *
+ * 放在哪：作为 `<post-compact-state>` 块接在 compaction 条目的 `summary` 末尾（与已有的
+ * `<read-files>` / `<modified-files>` 同一做法），模型看到的顺序就是「摘要 → 回注 → 保留区」。
+ * 不另写 `custom_message`：投影把 compaction 之后的条目放在保留区之后，溢出恢复时保留区以用户刚发
+ * 的提示结尾，追加在末尾的回注会排在那条提示后面、让模型先回应回注。压缩后本来就是新前缀，
+ * 回注不额外打断缓存。下一次增量摘要前先剥掉这个块（`stripPostCompact`），每次重新生成。
+ */
+import { resolve } from "node:path";
+import { TODO_CUSTOM_TYPE } from "../tools/todo.js";
+export const POST_COMPACT_TAG = "post-compact-state";
+export const PLAN_CUSTOM_TYPE = "ama.plan";
+export const MAX_RECENT_FILES = 20;
+const MAX_PLAN_STEPS = 20;
+const MAX_LINE = 160;
+const READ_TOOLS = new Set(["read"]);
+const WRITE_TOOLS = new Set(["write", "edit"]);
+function clip(text) {
+    const line = text.replace(/\s+/g, " ").trim();
+    return line.length > MAX_LINE ? `${line.slice(0, MAX_LINE - 1)}…` : line;
+}
+function lastCustom(branch, type, accept) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry?.type === "custom" && entry.customType === type) {
+            if (accept === undefined || accept(entry.data))
+                return entry.data;
+        }
+    }
+    return undefined;
+}
+const TODO_MARK = { pending: "[ ]", in_progress: "[~]", done: "[x]" };
+function todoLines(branch) {
+    const data = lastCustom(branch, TODO_CUSTOM_TYPE);
+    const items = Array.isArray(data?.items) ? data.items : [];
+    const lines = [];
+    for (const item of items) {
+        if (typeof item?.["text"] !== "string")
+            continue;
+        const mark = TODO_MARK[String(item["status"])] ?? "[ ]";
+        lines.push(`${mark} ${String(item["id"] ?? "")}. ${clip(item["text"])}`);
+    }
+    return lines;
+}
+function planBlock(branch) {
+    const plan = lastCustom(branch, PLAN_CUSTOM_TYPE);
+    if (plan === undefined || typeof plan !== "object" || plan === null)
+        return undefined;
+    if (plan.status === "rejected" || plan.status === "superseded")
+        return undefined;
+    const attrs = [`id="${String(plan.id ?? "")}"`];
+    if (plan.version !== undefined)
+        attrs.push(`version="${String(plan.version)}"`);
+    if (plan.status !== undefined)
+        attrs.push(`status="${String(plan.status)}"`);
+    if (typeof plan.filePath === "string")
+        attrs.push(`file="${plan.filePath}"`);
+    const steps = Array.isArray(plan.steps) ? plan.steps : [];
+    const lines = steps
+        .slice(0, MAX_PLAN_STEPS)
+        .map((step) => `${String(step?.["id"] ?? "")} ${clip(String(step?.["text"] ?? ""))}`);
+    if (steps.length > MAX_PLAN_STEPS)
+        lines.push(`(+${steps.length - MAX_PLAN_STEPS} more steps)`);
+    return [`<plan ${attrs.join(" ")}>`, ...lines, "</plan>"].join("\n");
+}
+/** 按最近使用排序（最近的在前）的文件与 Skill。 */
+function fileActivity(input) {
+    const skillSet = new Set((input.skillPaths ?? []).map((path) => resolve(input.cwd, path)));
+    const read = new Map();
+    const modified = new Map();
+    const skills = new Map();
+    let order = 0;
+    for (const entry of input.branch) {
+        if (entry.type !== "message" || entry.message.role !== "assistant")
+            continue;
+        for (const block of entry.message.content) {
+            if (block.type !== "toolCall")
+                continue;
+            order++;
+            if (block.name === "skill") {
+                const name = block.arguments["name"];
+                if (typeof name === "string")
+                    skills.set(name, order);
+                continue;
+            }
+            const path = block.arguments["path"];
+            if (typeof path !== "string" || path === "")
+                continue;
+            const abs = resolve(input.cwd, path);
+            if (WRITE_TOOLS.has(block.name))
+                modified.set(path, order);
+            else if (READ_TOOLS.has(block.name)) {
+                if (skillSet.has(abs))
+                    skills.set(abs, order);
+                else
+                    read.set(path, order);
+            }
+        }
+    }
+    for (const path of modified.keys())
+        read.delete(path);
+    const recent = (map) => [...map.entries()].sort((a, b) => b[1] - a[1]).map(([key]) => key);
+    return { read: recent(read), modified: recent(modified), skills: recent(skills) };
+}
+function capped(paths) {
+    const shown = paths.slice(0, MAX_RECENT_FILES);
+    const more = paths.length - shown.length;
+    return more > 0 ? `${shown.join("\n")}\n(+${more} more)` : shown.join("\n");
+}
+const BLOCK_PATTERN = new RegExp(`\\s*<${POST_COMPACT_TAG}>[\\s\\S]*?</${POST_COMPACT_TAG}>`, "g");
+/** 去掉摘要里的回注块（上一份摘要作增量合并的输入前、模型照抄进新摘要时）。 */
+export function stripPostCompact(summary) {
+    return summary.replace(BLOCK_PATTERN, "").trimEnd();
+}
+/** 回注块（`<post-compact-state>…</post-compact-state>`）；无任何可回注的状态时仍给出续接说明。 */
+export function buildPostCompactBlock(input) {
+    return `<${POST_COMPACT_TAG}>\n${buildPostCompactContent(input)}\n</${POST_COMPACT_TAG}>`;
+}
+/** 回注正文。 */
+export function buildPostCompactContent(input) {
+    const parts = [
+        "State to continue from after compaction (pointers only; read a file again only when you need its content):",
+    ];
+    const todo = todoLines(input.branch);
+    if (todo.length > 0)
+        parts.push(`<todo>\n${todo.join("\n")}\n</todo>`);
+    const plan = planBlock(input.branch);
+    if (plan !== undefined)
+        parts.push(plan);
+    const files = fileActivity(input);
+    if (files.skills.length > 0)
+        parts.push(`<loaded-skills>\n${capped(files.skills)}\n</loaded-skills>`);
+    if (files.modified.length > 0)
+        parts.push(`<recently-modified-files>\n${capped(files.modified)}\n</recently-modified-files>`);
+    if (files.read.length > 0)
+        parts.push(`<recently-read-files>\n${capped(files.read)}\n</recently-read-files>`);
+    if (input.transcriptPath !== undefined)
+        parts.push(`<transcript>${input.transcriptPath}</transcript> (full history before compaction, JSONL; read it only if the summary lacks a detail you need)`);
+    if (input.outputDir !== undefined)
+        parts.push(`<outputs>${input.outputDir}</outputs> (full text of pruned and truncated tool results)`);
+    parts.push("Continue from the summary's Next Steps and the todo list; do not redo finished work.");
+    return parts.join("\n\n");
+}

package/dist/compaction/protect.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 档一保护集（wave5 §8.2 C4）。[W5-H1]
+ *
+ * 不被档一换成占位的工具结果：
+ * - `todo`、`skill` 工具的结果（任务清单与 Skill 正文是长任务的骨架）；
+ * - `read` 读入的 Skill 文件（系统提示 skills 节 `<location>` 里列出的路径）与 `AGENTS.md` / `CLAUDE.md`；
+ * - 声明了 `annotations.keepInContext` 的工具（宿主工具可用）；
+ * - `compaction.pruneExclude` 列出的工具名。
+ */
+import type { ContextItem } from "../session/projection.js";
+import type { PruneCandidate } from "./prune-tier.js";
+export declare const PROTECTED_TOOLS: readonly string[];
+export declare const PROTECTED_FILE_NAMES: readonly string[];
+export interface ProtectionInput {
+    cwd: string;
+    /** Skill 文件的绝对路径（见 `skillLocations`）。 */
+    skillPaths?: readonly string[];
+    /** `compaction.pruneExclude`。 */
+    exclude?: readonly string[];
+    /** 工具是否声明了 `annotations.keepInContext`。 */
+    keepInContext?(toolName: string): boolean;
+}
+/** 投影里最近一次给出 skills 节的 system 消息中的 `<location>`（索引里列出的 Skill 文件）。 */
+export declare function skillLocations(items: readonly ContextItem[]): string[];
+/** `read` 调用读的文件（绝对路径）；不是 read 或缺 path 时 undefined。 */
+export declare function readPathOf(candidate: Pick<PruneCandidate, "toolName" | "args">, cwd: string): string | undefined;
+export declare function createProtection(input: ProtectionInput): (candidate: PruneCandidate) => boolean;

package/dist/compaction/protect.js

@@ -0,0 +1,56 @@
+/**
+ * 档一保护集（wave5 §8.2 C4）。[W5-H1]
+ *
+ * 不被档一换成占位的工具结果：
+ * - `todo`、`skill` 工具的结果（任务清单与 Skill 正文是长任务的骨架）；
+ * - `read` 读入的 Skill 文件（系统提示 skills 节 `<location>` 里列出的路径）与 `AGENTS.md` / `CLAUDE.md`；
+ * - 声明了 `annotations.keepInContext` 的工具（宿主工具可用）；
+ * - `compaction.pruneExclude` 列出的工具名。
+ */
+import { basename, resolve } from "node:path";
+export const PROTECTED_TOOLS = ["todo", "skill"];
+export const PROTECTED_FILE_NAMES = ["AGENTS.md", "CLAUDE.md"];
+function unescapeXml(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/** 投影里最近一次给出 skills 节的 system 消息中的 `<location>`（索引里列出的 Skill 文件）。 */
+export function skillLocations(items) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const message = items[i]?.message;
+        if (message?.role !== "system")
+            continue;
+        const section = message.sections["skills"];
+        if (section === undefined)
+            continue; // 补丁里没改这一节，往前找
+        if (section === null)
+            return []; // 这一节被移除
+        return [...section.matchAll(/<location>([^<]*)<\/location>/g)].map((m) => unescapeXml(m[1] ?? "").trim());
+    }
+    return [];
+}
+/** `read` 调用读的文件（绝对路径）；不是 read 或缺 path 时 undefined。 */
+export function readPathOf(candidate, cwd) {
+    if (candidate.toolName !== "read")
+        return undefined;
+    const path = candidate.args?.["path"];
+    return typeof path === "string" && path !== "" ? resolve(cwd, path) : undefined;
+}
+export function createProtection(input) {
+    const tools = new Set([...PROTECTED_TOOLS, ...(input.exclude ?? [])]);
+    const skills = new Set((input.skillPaths ?? []).map((path) => resolve(input.cwd, path)));
+    return (candidate) => {
+        if (tools.has(candidate.toolName))
+            return true;
+        if (input.keepInContext?.(candidate.toolName) === true)
+            return true;
+        const path = readPathOf(candidate, input.cwd);
+        if (path === undefined)
+            return false;
+        return skills.has(path) || PROTECTED_FILE_NAMES.includes(basename(path));
+    };
+}

package/dist/compaction/prune-tier.d.ts

@@ -1,31 +1,77 @@
 /**
- * 档一裁剪（设计 §9「档一」）：无模型调用。[B2]
+ * 档一裁剪（设计 §9「档一」，wave5 §8.2 C1 / C2 / C4 / C10）：无模型调用。[B2][W5-H1]
  *
- * 触发：`contextTokens > 0.7 × (contextWindow − reserveTokens)`。
- * 范围：最近两个用户回合之前、内容 > 2 KiB 的 toolResult。
+ * 边界按**工具结果新旧**计（C1，修 G1：只有一条 user 消息的长任务以前永不触发）：从最新往回数，
+ * 最近 `keepResults` 个结果与累计不超过 `protectTokens` 的结果不动；更早、估算 > 512 token、
+ * 不在保护集里的结果是候选。
+ * 门槛与回差（C2）：候选合计可省 < `clearAtLeast` 不动；动就一次清到目标（调用方给 `need` =
+ * 当前 − 0.5×预算，且至少 `clearAtLeast`），从最旧的开始换，避免过线后每回合推进一点、每回合
+ * 打断一次缓存。缓存已冷时（C3，调用方判断）`need` 为 undefined：全部候选一次换掉。
+ * 保护集（C4）：调用方给 `isProtected`（Skill 文件、AGENTS.md、todo、`keepInContext` 工具、
+ * `compaction.pruneExclude`），见 `protect.ts`。
  * 动作：返回 `context_edit{reason:"prune", replacement:"[已裁剪 …全文 path]"}` 计划；有 outputDir 时
  * 把全文写到 `<outputDir>/<toolCallId>.txt`（已存在则不覆盖），模型可用 read 取回。
  */
 import type { ContentBlock } from "../ai/types.js";
+import type { PruneConfig } from "../config/types.js";
 import type { ContextItem } from "../session/projection.js";
-export declare const PRUNE_THRESHOLD_RATIO = 0.7;
-export declare const PRUNE_MIN_BYTES = 2048;
-export declare const PRUNE_KEEP_USER_TURNS = 2;
+export declare const PRUNE_TRIGGER_RATIO = 0.7;
+export declare const PRUNE_TARGET_RATIO = 0.5;
+export declare const PRUNE_KEEP_RESULTS = 5;
+/** 保护最近 min(40k, 0.2×预算) token 的工具输出。 */
+export declare const PRUNE_PROTECT_TOKENS = 40000;
+export declare const PRUNE_PROTECT_RATIO = 0.2;
+/**
+ * `clearAtLeast: "auto"` = max(20k, 0.1×预算)，但不超过 0.2×预算（= 触发线与目标之差；小窗口
+ * 模型上 20k 比这段差还大，档一就永远不会动）。
+ */
+export declare const PRUNE_CLEAR_AT_LEAST = 20000;
+export declare const PRUNE_CLEAR_AT_LEAST_RATIO = 0.1;
+export declare const PRUNE_CLEAR_AT_LEAST_CAP_RATIO = 0.2;
+/** 小于等于此估算 token 的结果不裁（占位本身也要几十 token）。 */
+export declare const PRUNE_MIN_TOKENS = 512;
+/** 由预算（窗口 − 预留）与配置得出的档一参数；只有 keepResults / clearAtLeast 进配置面（D27）。 */
+export interface PrunePolicy {
+    keepResults: number;
+    protectTokens: number;
+    clearAtLeast: number;
+    minTokens: number;
+    /** 超过才按阈值裁（0.7×预算）。 */
+    triggerTokens: number;
+    /** 一次清到（0.5×预算）。 */
+    targetTokens: number;
+}
+export declare function prunePolicy(budget: number, config?: PruneConfig): PrunePolicy;
 export interface PrunePlanItem {
     targetId: string;
     replacement: string;
     toolCallId: string;
     originalBytes: number;
+    /** 估算可省的 token。 */
+    savedTokens: number;
     fullTextPath?: string;
 }
+export interface PrunePlan {
+    items: PrunePlanItem[];
+    /** 本计划省下的 token（估算）。 */
+    savedTokens: number;
+    /** 全部候选合计可省（不足 clearAtLeast 时计划为空）。 */
+    availableTokens: number;
+}
+/** 保护集判断的输入：结果所属工具与调用参数（从同一投影里的助手消息找）。 */
+export interface PruneCandidate {
+    toolName: string;
+    args: Record<string, unknown> | undefined;
+}
 export interface PruneOptions {
-    keepUserTurns?: number;
-    minBytes?: number;
+    policy: Pick<PrunePolicy, "keepResults" | "protectTokens" | "clearAtLeast" | "minTokens">;
+    /** 至少要省多少才到目标；undefined = 全部候选（缓存已冷）。实际至少 clearAtLeast。 */
+    need?: number | undefined;
     /** 全文落盘目录；undefined 时不落盘（内存会话）。 */
     outputDir?: string | undefined;
+    /** 保护集（C4）：返回 true 的结果不裁。 */
+    isProtected?(candidate: PruneCandidate): boolean;
 }
-export declare function pruneThreshold(contextWindow: number, reserveTokens: number): number;
-export declare function shouldPrune(tokens: number, contextWindow: number, reserveTokens: number): boolean;
 export declare function contentToText(content: string | readonly ContentBlock[]): string;
-/** 计算裁剪计划（并按需落盘全文）；返回空数组表示无可裁剪项。 */
-export declare function planPrune(items: readonly ContextItem[], options?: PruneOptions): PrunePlanItem[];
+/** 计算裁剪计划（并为选中项落盘全文）；`items` 为空表示不裁。 */
+export declare function planPrune(items: readonly ContextItem[], options: PruneOptions): PrunePlan;