@armadra/agent 0.4.0 → 0.5.1

package/dist/compaction/breaker.js

@@ -1,17 +1,27 @@
 /**
- * 压缩熔断（设计 §9「熔断」）。[B2]
+ * 压缩熔断（设计 §9「熔断」，wave5 §8.2 C5）。[B2][W5-H1]
  *
  * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
- * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
- * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 不再限制「每 run 档二 ≤ 1 次」（单提示长任务需要多次摘要）；改为两种跳闸：
+ *   - 连续 3 次摘要失败；
+ *   - 快速回填：连续 3 次摘要都在上一次摘要后不到 3 回合就又需要摘要（压缩不动、越压越满）。
+ *   跳闸后关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 固定前缀（system + 工具表）已超过预算：摘要无济于事，直接告警、不再尝试（`prefix_overflow`，
+ *   由调用方每次检查时更新）。
+ * - 「nothing to compact」不计失败（调用方不调 `recordSummary`）。
  * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
  */
-export const MAX_SUMMARIES_PER_RUN = 1;
-export const MAX_CONSECUTIVE_FAILURES = 2;
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/** 上一次摘要后不到这么多回合又需要摘要，记一次快速回填。 */
+export const RAPID_REFILL_TURNS = 3;
+export const MAX_RAPID_REFILLS = 3;
 export const RETRY_AFTER_COMPACTION_RATIO = 0.8;
 export class CompactionBreaker {
-    summariesThisRun = 0;
     consecutiveFailures = 0;
+    rapidRefills = 0;
+    turn = 0;
+    lastSummaryTurn;
+    prefixOverflow = false;
     enabled;
     contextWindow;
     constructor(enabled, contextWindow) {
@@ -22,15 +32,23 @@ export class CompactionBreaker {
         this.enabled = enabled;
         this.contextWindow = contextWindow;
     }
+    /** 连续失败或快速回填跳闸（溢出恢复也不再尝试）。 */
     get tripped() {
-        return this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+        return (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES || this.rapidRefills >= MAX_RAPID_REFILLS);
     }
-    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    /** 自动压缩整体是否开启。 */
     get autoEnabled() {
         return this.enabled && this.contextWindow !== undefined && !this.tripped;
     }
-    startRun() {
-        this.summariesThisRun = 0;
+    /** 新 run 开始（会话在 agent_start 时调用）；不再重置任何计数，保留以兼容调用点。 */
+    startRun() { }
+    /** 每次请求前的阈值检查调用一次：回合计数（快速回填按它判断）。 */
+    tick() {
+        this.turn++;
+    }
+    /** 固定前缀是否已超预算（调用方每次准备摘要前更新）。 */
+    setPrefixOverflow(overflow) {
+        this.prefixOverflow = overflow;
     }
     /** 自动档二能否执行；不能则给出原因。 */
     blockReason() {
@@ -38,23 +56,35 @@ export class CompactionBreaker {
             return "disabled";
         if (this.contextWindow === undefined)
             return "no_window";
-        if (this.tripped)
+        if (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES)
             return "tripped";
-        if (this.summariesThisRun >= MAX_SUMMARIES_PER_RUN)
-            return "run_limit";
+        if (this.rapidRefills >= MAX_RAPID_REFILLS)
+            return "rapid_refill";
+        if (this.prefixOverflow)
+            return "prefix_overflow";
         return undefined;
     }
     canSummarize() {
         return this.blockReason() === undefined;
     }
     recordSummary(success) {
-        this.summariesThisRun++;
-        this.consecutiveFailures = success ? 0 : this.consecutiveFailures + 1;
+        if (!success) {
+            this.consecutiveFailures++;
+            return;
+        }
+        this.consecutiveFailures = 0;
+        const last = this.lastSummaryTurn;
+        if (last !== undefined && this.turn - last < RAPID_REFILL_TURNS)
+            this.rapidRefills++;
+        else
+            this.rapidRefills = 0;
+        this.lastSummaryTurn = this.turn;
     }
-    /** 手动压缩成功等场景：清零失败计数。 */
+    /** 手动压缩成功等场景：清零全部计数。 */
     reset() {
         this.consecutiveFailures = 0;
-        this.summariesThisRun = 0;
+        this.rapidRefills = 0;
+        this.lastSummaryTurn = undefined;
     }
     /** 溢出恢复后是否值得重试。 */
     shouldRetryAfterCompaction(tokensAfter) {

package/dist/compaction/estimate.d.ts

@@ -2,15 +2,23 @@
  * 上下文 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 倍，
+ * 中文会话会晚触发直至溢出；所有阈值（档一、档二、保留区）都用这个口径。
  */
-import type { Usage } from "../ai/types.js";
+import type { ContentBlock, Usage } from "../ai/types.js";
 import type { ContextItem } from "../session/projection.js";
 import type { AgentMessage, SessionEntry } from "../session/types.js";
 export declare const IMAGE_TOKENS = 1600;
+/** 文本的 token 估算：CJK / 假名 / 谚文每字 1，其余字符 / 4（向上取整）。 */
+export declare function estimateTextTokens(text: string): number;
 export declare function calculateContextTokens(usage: Usage): number;
-/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+/** 内容的估算（文本按脚本，图片每张 1 600）。 */
+export declare function estimateContentTokens(content: string | readonly ContentBlock[]): number;
+/** 单条消息的估算（文本按脚本区分，图片每张 1 600）。 */
 export declare function estimateMessageTokens(message: AgentMessage): number;
 export declare function estimateMessagesTokens(messages: readonly AgentMessage[]): number;
 export interface ContextEstimate {

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;