pi-web-ui 0.94.1 → 0.96.0

package/dist/server/client-state.js

@@ -259,6 +259,16 @@ export function normalizeWorkspaceRoots(v) {
     }
     return out;
 }
+/** 跨平台（尤其是 Windows）路径归一化键：统一转绝对路径，并在 Windows 下转小写以消除大小写与正反斜杠差异。 */
+export function normalizePathKey(p) {
+    try {
+        const resolved = resolve(p);
+        return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    }
+    catch {
+        return process.platform === "win32" ? p.toLowerCase() : p;
+    }
+}
 /**
  * Persists which workspace each browser client last used + which workspaces it
  * has opened, so a server restart / page reload restores the same project and
@@ -293,6 +303,26 @@ export class ClientStateStore {
         catch {
             this.cache = {};
         }
+        // 历史数据迁移：老版本将 removedProjects 仅记在各自临时 clientId 下，升级后新标签页无法继承。
+        // 启动/加载时自动将所有老 client 的墓碑合并到全局 __settings__，避免重启或新标签页后已删项目复活。
+        let migrated = false;
+        const globalState = (this.cache[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
+        const globalSet = new Set((globalState.removedProjects ?? []).map(normalizePathKey));
+        for (const [id, cState] of Object.entries(this.cache)) {
+            if (id !== ClientStateStore.GLOBAL_SETTINGS_KEY && cState.removedProjects?.length) {
+                for (const p of cState.removedProjects) {
+                    const key = normalizePathKey(p);
+                    if (!globalSet.has(key)) {
+                        globalSet.add(key);
+                        (globalState.removedProjects ??= []).push(p);
+                        migrated = true;
+                    }
+                }
+            }
+        }
+        if (migrated) {
+            this.save();
+        }
         return this.cache;
     }
     save() {
@@ -318,11 +348,15 @@ export class ClientStateStore {
         const state = (all[clientId] ??= { projects: [] });
         state.lastCwd = cwd;
         const now = Date.now();
-        state.projects = [{ path: cwd, lastUsed: now }, ...state.projects.filter((p) => p.path !== cwd)].slice(0, 30);
+        const targetKey = normalizePathKey(cwd);
+        state.projects = [
+            { path: cwd, lastUsed: now },
+            ...state.projects.filter((p) => normalizePathKey(p.path) !== targetKey),
+        ].slice(0, 30);
         // Opening the workspace again clears its removal tombstone across all clients and global settings.
         for (const cState of Object.values(all)) {
             if (cState.removedProjects?.length) {
-                cState.removedProjects = cState.removedProjects.filter((p) => p !== cwd);
+                cState.removedProjects = cState.removedProjects.filter((p) => normalizePathKey(p) !== targetKey);
             }
         }
         this.save();
@@ -335,20 +369,21 @@ export class ClientStateStore {
      *  explicitly opens that project again. */
     removeProject(clientId, cwd) {
         const all = this.load();
+        const targetKey = normalizePathKey(cwd);
         const state = (all[clientId] ??= { projects: [] });
-        state.projects = state.projects.filter((p) => p.path !== cwd);
-        if (state.lastCwd === cwd)
+        state.projects = state.projects.filter((p) => normalizePathKey(p.path) !== targetKey);
+        if (state.lastCwd && normalizePathKey(state.lastCwd) === targetKey)
             delete state.lastCwd;
-        const removed = new Set(state.removedProjects ?? []);
-        removed.add(cwd);
-        state.removedProjects = [...removed];
+        const removed = (state.removedProjects ?? []).filter((p) => normalizePathKey(p) !== targetKey);
+        removed.push(cwd);
+        state.removedProjects = removed;
         const globalState = (all[ClientStateStore.GLOBAL_SETTINGS_KEY] ??= { projects: [] });
-        const globalRemoved = new Set(globalState.removedProjects ?? []);
-        globalRemoved.add(cwd);
-        globalState.removedProjects = [...globalRemoved];
+        const globalRemoved = (globalState.removedProjects ?? []).filter((p) => normalizePathKey(p) !== targetKey);
+        globalRemoved.push(cwd);
+        globalState.removedProjects = globalRemoved;
         for (const [id, cState] of Object.entries(all)) {
             if (id !== ClientStateStore.GLOBAL_SETTINGS_KEY && cState.projects) {
-                cState.projects = cState.projects.filter((p) => p.path !== cwd);
+                cState.projects = cState.projects.filter((p) => normalizePathKey(p.path) !== targetKey);
             }
         }
         this.save();
@@ -363,7 +398,16 @@ export class ClientStateStore {
             return clientRemoved;
         if (clientRemoved.length === 0)
             return globalRemoved;
-        return [...new Set([...clientRemoved, ...globalRemoved])];
+        const seen = new Set();
+        const result = [];
+        for (const p of [...clientRemoved, ...globalRemoved]) {
+            const key = normalizePathKey(p);
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(p);
+            }
+        }
+        return result;
     }
     /** Last-used goal/review prefs for a client, or undefined if never set. */
     getGoalPrefs(clientId) {
@@ -474,8 +518,10 @@ export class ClientStateStore {
                 : (stored?.terminalToolsEnabled ?? false),
             terminalBash: stored?.terminalBash ?? false,
             terminalBashIdleMs: stored?.terminalBashIdleMs ?? 15_000,
+            terminalBashMaxForegroundMs: stored?.terminalBashMaxForegroundMs ?? 60_000,
             toolWatchdogTimeoutMs: normalizeToolWatchdogTimeoutMs(stored?.toolWatchdogTimeoutMs),
             readDirEnabled: stored?.readDirEnabled ?? true,
+            toolApprovalEnabled: stored?.toolApprovalEnabled ?? true,
             editSoftEnabled: stored?.disabledAgentTools !== undefined
                 ? deriveLegacy(legacyToDisabled(stored)).editSoftEnabled
                 : (stored?.editSoftEnabled ?? false),
@@ -531,8 +577,10 @@ export class ClientStateStore {
             terminalToolsEnabled: settings.terminalToolsEnabled ?? cur.terminalToolsEnabled ?? false,
             terminalBash: settings.terminalBash ?? cur.terminalBash ?? false,
             terminalBashIdleMs: settings.terminalBashIdleMs ?? cur.terminalBashIdleMs ?? 15_000,
+            terminalBashMaxForegroundMs: settings.terminalBashMaxForegroundMs ?? cur.terminalBashMaxForegroundMs ?? 60_000,
             toolWatchdogTimeoutMs: normalizeToolWatchdogTimeoutMs(settings.toolWatchdogTimeoutMs ?? cur.toolWatchdogTimeoutMs ?? DEFAULT_TOOL_WATCHDOG_TIMEOUT_MS),
             readDirEnabled: settings.readDirEnabled ?? cur.readDirEnabled ?? true,
+            toolApprovalEnabled: settings.toolApprovalEnabled ?? cur.toolApprovalEnabled ?? true,
             editSoftEnabled: settings.editSoftEnabled ?? cur.editSoftEnabled ?? false,
             questionnaireEnabled: settings.questionnaireEnabled ?? cur.questionnaireEnabled ?? true,
             goalModeEnabled: settings.goalModeEnabled ?? cur.goalModeEnabled ?? true,
@@ -544,8 +592,13 @@ export class ClientStateStore {
             toolImagesEnabled: settings.toolImagesEnabled ?? cur.toolImagesEnabled ?? true,
             skillsFullText: normalizeSkillList(settings.skillsFullText ?? cur.skillsFullText),
             visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
-            visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
-            subagentDefaultModel: settings.subagentDefaultModel ?? cur.subagentDefaultModel ?? null,
+            // 按键存在性合并：null 是合法值（清除语义），`null ?? cur` 会把旧值
+            // 复活到磁盘（设置面板清空后重启又回来）。settings-service 持久化
+            // 时传全量对象，键总在；其他调用方传 partial，键缺 = 保持旧值。
+            visionBridgeModel: "visionBridgeModel" in settings ? (settings.visionBridgeModel ?? null) : (cur.visionBridgeModel ?? null),
+            subagentDefaultModel: "subagentDefaultModel" in settings
+                ? (settings.subagentDefaultModel ?? null)
+                : (cur.subagentDefaultModel ?? null),
             retryMaxAttempts: normalizeRetryMaxAttempts(settings.retryMaxAttempts ?? cur.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS),
             softCapTokens: normalizeSoftCapTokens(settings.softCapTokens ?? cur.softCapTokens ?? 0),
             softCapByModel: normalizeSoftCapByModel(settings.softCapByModel ?? cur.softCapByModel ?? {}),

package/dist/server/compact-context-tool.js

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// compact-context-tool.ts — 主动压缩上下文工具（compact_context）
+// ---------------------------------------------------------------------------
+// 让 AI 可以根据当前问题主动触发上下文压缩，自主决定保留和当前问题相关的内容，
+// 去除或深度压缩与当前问题无关、弱相关的历史探索与冗余输出。
+//
+// 执行时机：当 AI 在当前回合调用本工具后，本工具记录 pending 压缩请求并返回成功；
+// 在当前回合结束后（agent_settled 时会话处于完全 idle 状态），系统自动应用 AI
+// 指定的保留范围（keepRecentTokens）与关注点（focus / summary），执行 SDK 的
+// context compaction，使精炼后的上下文在后续交互中持续生效。
+// ---------------------------------------------------------------------------
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { pick } from "./i18n.js";
+import { COMPACT_CONTEXT_TOOL_NAME } from "./tool-manager.js";
+/** 工具名（唯一登记在 tool-manager.ts，在此 re-export 供外部模块引用）。 */
+export { COMPACT_CONTEXT_TOOL_NAME };
+/** 最小允许保留近期 tokens 下限。 */
+export const MIN_KEEP_RECENT_TOKENS = 1000;
+/** 最大允许保留近期 tokens 上限。 */
+export const MAX_KEEP_RECENT_TOKENS = 100000;
+/** SDK 默认的常规保留 tokens。 */
+export const DEFAULT_KEEP_RECENT_TOKENS = 20000;
+/**
+ * 智能计算生效的 keepRecentTokens：
+ * - 若 AI 显式指定，钳制到合法区间 [MIN_KEEP_RECENT_TOKENS, MAX_KEEP_RECENT_TOKENS]；
+ * - 若未显式指定，根据当前会话估算 tokens 动态计算：
+ *   会话较大时（>= 30000）保留默认 20000 tokens；
+ *   会话中等或较小时（< 30000），保留最近约 35%（且不低于 1500 tokens），
+ *   确保即便会话只有数千 tokens 时，也能成功切出前半段历史进行压缩，避免报 session too small。
+ * 纯函数。
+ */
+export function calculateEffectiveKeepRecentTokens(requestedTokens, currentEstimatedTokens) {
+    if (typeof requestedTokens === "number" && Number.isFinite(requestedTokens)) {
+        return Math.min(MAX_KEEP_RECENT_TOKENS, Math.max(MIN_KEEP_RECENT_TOKENS, Math.floor(requestedTokens)));
+    }
+    const current = Math.max(0, currentEstimatedTokens ?? 0);
+    if (current >= 30000) {
+        return DEFAULT_KEEP_RECENT_TOKENS;
+    }
+    if (current > 0) {
+        // 动态保留约 35%，至少保留 1500 tokens，上限不超过 DEFAULT_KEEP_RECENT_TOKENS
+        const dynamicTokens = Math.max(1500, Math.floor(current * 0.35));
+        return Math.min(DEFAULT_KEEP_RECENT_TOKENS, dynamicTokens);
+    }
+    return DEFAULT_KEEP_RECENT_TOKENS;
+}
+/**
+ * 组装给 SDK compaction 的完整指示文本：
+ * 融入 focus 指示与 AI 自主提炼的 customSummary。纯函数。
+ */
+export function buildCompactionInstructions(focus, customSummary) {
+    const trimmedFocus = focus.trim();
+    const trimmedSummary = customSummary?.trim();
+    if (!trimmedSummary)
+        return trimmedFocus;
+    return `${trimmedFocus}\n\n[Key Points / Summary to Retain]\n${trimmedSummary}`;
+}
+export const CompactContextParams = Type.Object({
+    focus: Type.String({
+        description: "Compression focus and requirements for the current issue/task. State: 1) the active problem/goal; 2) context to PRESERVE (key decisions, code changes, conventions, user constraints); 3) what to REMOVE or condense (failed attempts, resolved debugging, off-topic history).",
+    }),
+    keepRecentTokens: Type.Optional(Type.Number({
+        description: "Recent tokens to keep uncompacted (1000-64000). Smaller values (e.g. 3000-8000) compact more aggressively. Omit = auto-calculated from session size.",
+    })),
+    summary: Type.Optional(Type.String({
+        description: "Custom structured summary written by you; used as the core basis for the compaction entry if provided.",
+    })),
+});
+export function makeCompactContextTool(host, lang) {
+    const getLang = lang ?? (() => "en");
+    return defineTool({
+        name: COMPACT_CONTEXT_TOOL_NAME,
+        label: "Compact conversation context based on current issue",
+        description: "Compress/compact the conversation context around the current task: specify what to preserve (key decisions, code structure, active requirements) and what to drop or heavily summarize (unrelated exploration, verbose outputs, resolved debugging). " +
+            "Optionally control how many recent tokens stay untouched. Compaction executes when the current turn settles, refreshing context for subsequent turns.",
+        promptSnippet: "proactively compact conversation context focusing on the current issue",
+        promptGuidelines: [
+            "Use compact_context when the conversation has grown long, or after extensive debugging/exploration, to focus context strictly on the current problem.",
+            "Clearly specify in 'focus' what to keep (decisions, specs, active changes) and what to drop (failed attempts, voluminous command outputs).",
+            "After calling compact_context, conclude your current turn with a brief wrap-up and next steps; the system executes compaction right after this turn finishes.",
+        ],
+        parameters: CompactContextParams,
+        execute: async (_id, p) => {
+            const l = getLang();
+            const params = p;
+            const focus = params.focus?.trim() || "";
+            if (!focus) {
+                const errMsg = pick(l, "调用 compact_context 必须提供 focus 参数，说明针对当前问题的压缩要求与保留重点。", "compact_context requires a 'focus' parameter explaining what to keep and what to drop for the current issue.");
+                return {
+                    content: [{ type: "text", text: errMsg }],
+                    details: { ok: false, error: errMsg },
+                    isError: true,
+                };
+            }
+            const stats = host.getContextStats();
+            // 如果整个会话消息条数太少（< 4 条）且 token 极少（< 1200），无需压缩
+            if (stats.messageCount < 4 && stats.estimatedTokens < 1200) {
+                const msg = pick(l, `当前会话历史较短（约 ${stats.estimatedTokens} tokens，${stats.messageCount} 条消息），无需压缩。建议在历史累积较长或切换任务焦点后再调用此工具。`, `Current conversation is very brief (~${stats.estimatedTokens} tokens, ${stats.messageCount} messages), no compaction needed yet. Call this tool when history grows longer or when switching task focus.`);
+                return {
+                    content: [{ type: "text", text: msg }],
+                    details: { ok: false, skipped: true, ...stats },
+                };
+            }
+            const effectiveKeepTokens = calculateEffectiveKeepRecentTokens(params.keepRecentTokens, stats.estimatedTokens);
+            const pending = {
+                focus,
+                keepRecentTokens: effectiveKeepTokens,
+                summary: params.summary?.trim() || undefined,
+                requestedAt: Date.now(),
+            };
+            host.scheduleCompaction(pending);
+            const successMsg = pick(l, `已成功登记上下文压缩请求。将在本轮回复结束后立即执行上下文压缩。\n- 压缩聚焦点：${focus}\n- 保留近期范围：~${effectiveKeepTokens.toLocaleString()} tokens${pending.summary ? "\n- 包含自主提炼的摘要正文" : ""}\n请在结束本轮回复后，在精炼后的上下文中继续后续工作。`, `Context compaction request scheduled. It will execute immediately after the current turn ends.\n- Focus: ${focus}\n- Retain scope: ~${effectiveKeepTokens.toLocaleString()} tokens${pending.summary ? "\n- Custom summary provided" : ""}\nPlease wrap up this turn, and continue work in the compacted context.`);
+            return {
+                content: [{ type: "text", text: successMsg }],
+                details: {
+                    ok: true,
+                    scheduled: true,
+                    focus,
+                    keepRecentTokens: effectiveKeepTokens,
+                    hasCustomSummary: !!pending.summary,
+                },
+            };
+        },
+    });
+}

package/dist/server/composer-drafts.js

@@ -62,6 +62,15 @@ export class ComposerDraftsStore {
             raw = JSON.parse(readFileSync(this.filePath, "utf8"));
         }
         catch {
+            // 坏文件改名留存而非直接覆盖：先有留存，后续 save 落盘的才是新数据
+            //（否则一次解析失败 → 空表 → 下次 save 把全部草稿的原始记录抹掉）。
+            try {
+                renameSync(this.filePath, `${this.filePath}.corrupt-${Date.now()}`);
+                console.warn(`[composer-drafts] 草稿文件解析失败，已改名留存：${this.filePath}（丢草稿可重打，不留坏副本）`);
+            }
+            catch {
+                // 改名失败（占用等）也无妨：空表继续，save 时照常覆盖
+            }
             raw = {};
         }
         const now = Date.now();

package/dist/server/context-budget.js

@@ -0,0 +1,317 @@
+/**
+ * context-budget.ts — 多级分层上下文预算裁剪（Hierarchical Context Budgeting）
+ *
+ * 借鉴 DeepSeek Harness (DSH) 的梯度裁剪策略：在触发昂贵的 LLM 全文摘要之前，
+ * 增加确定性梯度瘦身，大幅推迟全量压缩时间点，保留近期关键代码的完整细节记忆：
+ *
+ *   1. 第一级（远期工具输出裁剪）：当上下文达到预警水位（例如 70%）时，自动将历史中
+ *      较早的工具巨量输出（如几千行的命令输出、超长文件读取）替换为轻量占位摘要
+ *      （`[Tool output trimmed: N lines / M bytes]`），保留工具调用的元数据与首尾关键信息；
+ *   2. 第二级（已完成步骤折叠）：折叠已通过的目标轮次中间调试日志；
+ *   3. 第三级（语义全量压缩）：仅在前两级裁剪后依然超标时，才调用 LLM 执行深度语义压缩。
+ *
+ * 纯模块：纯函数与纯逻辑，无外部 I/O 副作用，易于单测与多端复用。
+ */
+/** 默认第一级触发预警水位（70%）。 */
+export const DEFAULT_PRUNE_WATERMARK = 0.7;
+/** 默认第二级触发预警水位（85%）。 */
+export const DEFAULT_STAGE2_WATERMARK = 0.85;
+/** 触发远期工具裁剪的最小行数（超过此行数视作巨量输出）。 */
+export const DEFAULT_MIN_TRIM_LINES = 20;
+/** 触发远期工具裁剪的最小字节数（超过此体积视作巨量输出）。 */
+export const DEFAULT_MIN_TRIM_BYTES = 1000;
+/** 裁剪时保留的头部行数。 */
+export const DEFAULT_HEAD_LINES = 3;
+/** 裁剪时保留的尾部行数。 */
+export const DEFAULT_TAIL_LINES = 3;
+/** 保留最近若干轮不裁剪（近期关键工作记忆保护）。1 轮通常包含 user + assistant + toolResult。 */
+export const DEFAULT_KEEP_RECENT_TURNS = 2;
+/**
+ * 粗略估算字符串的 token 数（chars / 4 保守估算）。
+ */
+export function estimateTextTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * 估算一条 AgentMessage 的 token 数。
+ */
+export function estimateMessageTokens(message) {
+    let total = 0;
+    const msg = message;
+    if (typeof msg.content === "string") {
+        total += estimateTextTokens(msg.content);
+    }
+    else if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string") {
+                total += estimateTextTokens(b.text);
+            }
+            else if (b.type === "thinking" && typeof b.thinking === "string") {
+                total += estimateTextTokens(b.thinking);
+            }
+            else if (b.type === "toolCall" && b.arguments) {
+                total += estimateTextTokens(JSON.stringify(b.arguments));
+            }
+            else if (b.type === "image") {
+                total += 800; // 图片估算基准
+            }
+        }
+    }
+    if (msg.role === "bashExecution" && typeof msg.output === "string") {
+        total += estimateTextTokens(msg.output);
+    }
+    return Math.max(1, total);
+}
+/**
+ * 估算消息数组的总 token 数。
+ */
+export function estimateMessagesTotalTokens(messages) {
+    let sum = 0;
+    for (const m of messages) {
+        sum += estimateMessageTokens(m);
+    }
+    return sum;
+}
+/**
+ * 查找属于“近期工作记忆”的消息起始索引。
+ * 从后往前数 keepRecentTurns 个 user 消息；在此之后的皆为近期交互，不参与第一级工具裁剪。
+ */
+export function findRecentCutoffIndex(messages, keepRecentTurns = DEFAULT_KEEP_RECENT_TURNS) {
+    if (messages.length === 0 || keepRecentTurns <= 0)
+        return 0;
+    let userTurnsSeen = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role === "user") {
+            userTurnsSeen++;
+            if (userTurnsSeen >= keepRecentTurns) {
+                return i;
+            }
+        }
+    }
+    return 0;
+}
+/**
+ * 第一级裁剪：远期工具输出裁剪（Distant Tool Output Trimming）
+ *
+ * 将历史中较早的工具巨量输出（几千行命令输出、超长文件读取）替换为轻量占位摘要，
+ * 保留工具调用的元数据与首尾关键信息。
+ */
+export function trimDistantToolOutputs(messages, options = {}) {
+    const minLines = options.minLines ?? DEFAULT_MIN_TRIM_LINES;
+    const minBytes = options.minBytes ?? DEFAULT_MIN_TRIM_BYTES;
+    const headLines = options.headLines ?? DEFAULT_HEAD_LINES;
+    const tailLines = options.tailLines ?? DEFAULT_TAIL_LINES;
+    const keepRecentTurns = options.keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS;
+    const cutoffIndex = findRecentCutoffIndex(messages, keepRecentTurns);
+    let trimmedCount = 0;
+    let savedBytes = 0;
+    let savedTokens = 0;
+    const newMessages = messages.map((m, index) => {
+        // 近期消息不裁剪，保护最近的关键工作上下文
+        if (index >= cutoffIndex) {
+            return m;
+        }
+        const msg = m;
+        // 1. 处理 toolResult 消息
+        if (msg.role === "toolResult" && Array.isArray(msg.content)) {
+            let modified = false;
+            const newContent = msg.content.map((block) => {
+                if (!block || typeof block !== "object")
+                    return block;
+                const b = block;
+                if (b.type === "text" && typeof b.text === "string") {
+                    const text = b.text;
+                    // 如果已经裁剪过，避免重复处理
+                    if (text.includes("[Tool output trimmed:")) {
+                        return block;
+                    }
+                    const byteLen = Buffer.byteLength(text, "utf8");
+                    const lines = text.split("\n");
+                    if (lines.length >= minLines || byteLen >= minBytes) {
+                        if (lines.length > headLines + tailLines) {
+                            const head = lines.slice(0, headLines).join("\n");
+                            const tail = lines.slice(lines.length - tailLines).join("\n");
+                            const trimmedLines = lines.length - headLines - tailLines;
+                            const middleText = lines.slice(headLines, lines.length - tailLines).join("\n");
+                            const trimmedBytes = Buffer.byteLength(middleText, "utf8");
+                            const placeholder = `[Tool output trimmed: ${trimmedLines} lines / ${trimmedBytes} bytes]`;
+                            const trimmedText = `${head}\n... ${placeholder} ...\n${tail}`;
+                            const diffBytes = byteLen - Buffer.byteLength(trimmedText, "utf8");
+                            if (diffBytes > 0) {
+                                savedBytes += diffBytes;
+                                savedTokens += estimateTextTokens(text) - estimateTextTokens(trimmedText);
+                                trimmedCount++;
+                                modified = true;
+                                return { ...b, text: trimmedText };
+                            }
+                        }
+                    }
+                }
+                return block;
+            });
+            if (modified) {
+                return { ...msg, content: newContent };
+            }
+        }
+        // 2. 处理 bashExecution 消息
+        if (msg.role === "bashExecution" && typeof msg.output === "string") {
+            const text = msg.output;
+            if (!text.includes("[Tool output trimmed:")) {
+                const byteLen = Buffer.byteLength(text, "utf8");
+                const lines = text.split("\n");
+                if (lines.length >= minLines || byteLen >= minBytes) {
+                    if (lines.length > headLines + tailLines) {
+                        const head = lines.slice(0, headLines).join("\n");
+                        const tail = lines.slice(lines.length - tailLines).join("\n");
+                        const trimmedLines = lines.length - headLines - tailLines;
+                        const middleText = lines.slice(headLines, lines.length - tailLines).join("\n");
+                        const trimmedBytes = Buffer.byteLength(middleText, "utf8");
+                        const placeholder = `[Tool output trimmed: ${trimmedLines} lines / ${trimmedBytes} bytes]`;
+                        const trimmedText = `${head}\n... ${placeholder} ...\n${tail}`;
+                        const diffBytes = byteLen - Buffer.byteLength(trimmedText, "utf8");
+                        if (diffBytes > 0) {
+                            savedBytes += diffBytes;
+                            savedTokens += estimateTextTokens(text) - estimateTextTokens(trimmedText);
+                            trimmedCount++;
+                            return { ...msg, output: trimmedText };
+                        }
+                    }
+                }
+            }
+        }
+        return m;
+    });
+    return {
+        messages: newMessages,
+        trimmedCount,
+        savedBytes,
+        savedTokens: Math.max(0, savedTokens),
+    };
+}
+/**
+ * 第二级裁剪：已完成步骤折叠（Completed Steps Folding）
+ *
+ * 折叠已通过的目标轮次中间调试日志或已确认步骤的重试调试过程。
+ * 将已解决步骤中冗余的反复排查、中间反思文本折叠为轻量占位，保留最终决策和产物。
+ */
+export function foldCompletedStepLogs(messages, options = {}) {
+    const keepRecentTurns = options.keepRecentTurns ?? 1;
+    const cutoffIndex = findRecentCutoffIndex(messages, keepRecentTurns);
+    let foldedCount = 0;
+    let savedBytes = 0;
+    let savedTokens = 0;
+    // 检查历史中是否存在已完成/通过的目标审查或成功修复标记
+    // 例如包含目标审查通过、已完成步骤标记等
+    const newMessages = messages.map((m, index) => {
+        if (index >= cutoffIndex) {
+            return m;
+        }
+        const msg = m;
+        // 对中间的 assistant 消息中的冗长调试日志/思考排查进行轻量折叠
+        // 若 assistant 消息包含明显的中间失败重试排查日志且不是最后结论
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            let modified = false;
+            const newContent = msg.content.map((block) => {
+                if (!block || typeof block !== "object")
+                    return block;
+                const b = block;
+                // 如果有长 thinking 块，且在已完成历史中
+                if (b.type === "thinking" && typeof b.thinking === "string") {
+                    const t = b.thinking;
+                    if (t.length > 500 && !t.includes("[Completed step debug logs folded:")) {
+                        const originalBytes = Buffer.byteLength(t, "utf8");
+                        const lines = t.split("\n").length;
+                        const foldedPlaceholder = `[Completed step debug logs folded: 1 entry / ${lines} lines]`;
+                        const diffBytes = originalBytes - Buffer.byteLength(foldedPlaceholder, "utf8");
+                        if (diffBytes > 0) {
+                            savedBytes += diffBytes;
+                            savedTokens += estimateTextTokens(t) - estimateTextTokens(foldedPlaceholder);
+                            foldedCount++;
+                            modified = true;
+                            return { ...b, thinking: foldedPlaceholder };
+                        }
+                    }
+                }
+                return block;
+            });
+            if (modified) {
+                return { ...msg, content: newContent };
+            }
+        }
+        return m;
+    });
+    return {
+        messages: newMessages,
+        foldedCount,
+        savedBytes,
+        savedTokens: Math.max(0, savedTokens),
+    };
+}
+/**
+ * 多级分层上下文预算裁剪总调度器（Hierarchical Pruning Orchestrator）
+ *
+ * 按照梯度策略执行：
+ * 1. 评估当前 token 占用与有效预算阈值；
+ * 2. 达到 70% 水位时，执行第一级（远期工具输出裁剪）；
+ * 3. 若仍超标或达到 85% 水位，执行第二级（已完成步骤折叠）；
+ * 4. 仅在前两级裁剪后依然超标时，才标记 needsCompaction = true 进入第三级。
+ */
+export function pruneContextHierarchically(messages, options) {
+    const contextWindow = options.contextWindow > 0 ? options.contextWindow : 128_000;
+    const reserveTokens = options.reserveTokens > 0 ? options.reserveTokens : 16_384;
+    const effectiveCap = options.softCap && options.softCap > 0
+        ? Math.min(options.softCap, contextWindow - reserveTokens)
+        : Math.max(1, contextWindow - reserveTokens);
+    const tier1Watermark = options.tier1Watermark ?? DEFAULT_PRUNE_WATERMARK;
+    const tier2Watermark = options.tier2Watermark ?? DEFAULT_STAGE2_WATERMARK;
+    const tier1Threshold = Math.floor(effectiveCap * tier1Watermark);
+    const tier2Threshold = Math.floor(effectiveCap * tier2Watermark);
+    const tokensBefore = estimateMessagesTotalTokens(messages);
+    let currentTokens = tokensBefore;
+    let currentMessages = messages;
+    const tier1Result = { trimmedCount: 0, savedBytes: 0, savedTokens: 0 };
+    const tier2Result = { foldedCount: 0, savedBytes: 0, savedTokens: 0 };
+    const reachedTier1 = options.force || currentTokens >= tier1Threshold;
+    let reachedTier2 = options.force || currentTokens >= tier2Threshold;
+    // 1. 第一级：远期工具输出裁剪
+    if (reachedTier1) {
+        const r1 = trimDistantToolOutputs(currentMessages);
+        if (r1.trimmedCount > 0) {
+            currentMessages = r1.messages;
+            tier1Result.trimmedCount = r1.trimmedCount;
+            tier1Result.savedBytes = r1.savedBytes;
+            tier1Result.savedTokens = r1.savedTokens;
+            currentTokens = estimateMessagesTotalTokens(currentMessages);
+        }
+    }
+    // 2. 第二级：已完成步骤折叠（如果仍达到第二级水位或仍超标）
+    reachedTier2 = reachedTier2 || currentTokens >= tier2Threshold;
+    if (reachedTier2 || (options.force && currentTokens >= effectiveCap)) {
+        const r2 = foldCompletedStepLogs(currentMessages);
+        if (r2.foldedCount > 0) {
+            currentMessages = r2.messages;
+            tier2Result.foldedCount = r2.foldedCount;
+            tier2Result.savedBytes = r2.savedBytes;
+            tier2Result.savedTokens = r2.savedTokens;
+            currentTokens = estimateMessagesTotalTokens(currentMessages);
+        }
+    }
+    // 3. 第三级判定：前两级瘦身后，是否依然超过有效预算上限
+    const needsCompaction = currentTokens >= effectiveCap;
+    return {
+        messages: currentMessages,
+        tokensBefore,
+        tokensAfter: currentTokens,
+        tier1: tier1Result,
+        tier2: tier2Result,
+        needsCompaction,
+        reachedTier1,
+        reachedTier2,
+    };
+}