@bolloon/bolloon-agent 0.1.35 → 0.1.36

package/dist/bootstrap/context-hierarchy.js

@@ -0,0 +1,218 @@
+/**
+ * Context Hierarchy — 4 级 Bolloon.md 查找 + 合并优先级
+ *
+ * 设计: 严格对齐 Claude Code 论文 4 级层次
+ *   1. Managed  — /etc/bolloon/Bolloon.md        (企业 IT 部署, 系统级)
+ *   2. User     — ~/.bolloon/Bolloon.md          (用户级, 跨项目)
+ *   3. Project  — <cwd>/Bolloon.md 或 .claude/rules/*.md
+ *   4. Local    — <cwd>/CLAUDE.local.md         (个人覆盖, .gitignore)
+ *
+ * 注入约定 (论文):
+ * - 拼到 system prompt 顶部 (作为 user context, 概率性遵守)
+ * - 不混入 user 消息 (避免 prompt injection)
+ * - 截断时反向砍 local → project → user → managed (优先保 managed, 因为是 bolloon 自身约束)
+ *
+ * 兼容:
+ * - 同时识别 Bolloon.md 和 Bolloon.md (论文用前者, bolloon 历史用后者)
+ * - 文件名按优先级: Bolloon.md > Bolloon.md
+ *
+ * 失败静默: 任何 IO 错误 → 返回 null, 不阻塞主流程.
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+export const DEFAULT_PATHS = {
+    managed: '/etc/bolloon/Bolloon.md',
+    user: '', // 用 resolveUserPath 填
+    project: '', // 用 resolveProjectPaths 填
+    projectRulesDir: '',
+    local: '',
+};
+/**
+ * 单层字符上限 (P-Action 4 收紧, 阶段 0 把 4 级层次控制在 ≤ 2KB).
+ * 反向截断策略保证 managed 优先, 单层超限由 truncate() 截断.
+ */
+export const DEFAULT_MAX_CHARS = {
+    managed: 700, // 1500 → 700, 保 bolloon 自身约束
+    user: 500, // 1500 → 500, 跨项目偏好
+    project: 500, // 2500 → 500, 项目规则
+    local: 300, // 1500 → 300, 个人覆盖
+};
+// ============================================================
+// 路径解析
+// ============================================================
+export function resolveUserPath(home) {
+    const h = home ?? process.env.HOME ?? os.homedir() ?? '/tmp';
+    return path.join(h, '.bolloon', 'Bolloon.md');
+}
+export function resolveProjectPaths(cwd) {
+    return {
+        project: path.join(cwd, 'Bolloon.md'),
+        projectRulesDir: path.join(cwd, '.claude', 'rules'),
+        local: path.join(cwd, 'CLAUDE.local.md'),
+    };
+}
+// ============================================================
+// 单层读取 (优先 Bolloon.md, fallback Bolloon.md)
+// ============================================================
+/**
+ * 读 1 个文件路径, 失败/缺失返回 null.
+ * 字符上限由调用方截断 (这里只负责读全文).
+ */
+async function readRuleFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return content.length > 0 ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 读 project 层: 优先 Bolloon.md, fallback Bolloon.md, 最后尝试 .claude/rules/*.md
+ */
+async function readProjectLayer(projectPath, projectRulesDir, maxChars) {
+    // 1. Bolloon.md
+    let content = await readRuleFile(projectPath);
+    if (content)
+        return truncate(content, maxChars);
+    // 2. Bolloon.md (向后兼容)
+    const bolloonMdPath = path.join(path.dirname(projectPath), 'Bolloon.md');
+    content = await readRuleFile(bolloonMdPath);
+    if (content)
+        return truncate(content, maxChars);
+    // 3. .claude/rules/*.md (合并所有)
+    try {
+        const entries = await fs.readdir(projectRulesDir, { withFileTypes: true });
+        const ruleFiles = entries
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => path.join(projectRulesDir, e.name))
+            .sort();
+        if (ruleFiles.length > 0) {
+            const parts = [];
+            let total = 0;
+            for (const f of ruleFiles) {
+                const c = await readRuleFile(f);
+                if (c) {
+                    parts.push(`### ${path.basename(f, '.md')}\n${c}`);
+                    total += c.length;
+                    if (total >= maxChars)
+                        break;
+                }
+            }
+            if (parts.length > 0)
+                return truncate(parts.join('\n\n'), maxChars);
+        }
+    }
+    catch { /* dir 不存在 */ }
+    return null;
+}
+/**
+ * 并行读 4 层, 任何一层失败 = null (不阻塞其他).
+ */
+export async function collectHierarchyLayers(opts) {
+    const limits = { ...DEFAULT_MAX_CHARS, ...(opts.limits?.maxChars ?? {}) };
+    const home = opts.home ?? process.env.HOME ?? os.homedir() ?? '/tmp';
+    const managedPath = opts.limits?.paths?.managed ?? DEFAULT_PATHS.managed;
+    const userPath = opts.limits?.paths?.user ?? resolveUserPath(home);
+    const projectPath = opts.limits?.paths?.project ?? path.join(opts.cwd, 'Bolloon.md');
+    const projectRulesDir = opts.limits?.paths?.projectRulesDir ?? path.join(opts.cwd, '.claude', 'rules');
+    const localPath = opts.limits?.paths?.local ?? path.join(opts.cwd, 'CLAUDE.local.md');
+    const [managed, user, project, local] = await Promise.all([
+        readRuleFile(managedPath).then((c) => c ? truncate(c, limits.managed) : null),
+        readRuleFile(userPath).then((c) => c ? truncate(c, limits.user) : null),
+        readProjectLayer(projectPath, projectRulesDir, limits.project),
+        readRuleFile(localPath).then((c) => c ? truncate(c, limits.local) : null),
+    ]);
+    return { managed, user, project, local };
+}
+/**
+ * 4 级合并总字符上限 (P-Action 4 收紧, ≤ 2KB ≈ 500 tokens).
+ * 反向截断 (local → project → user → managed) 保证 managed 不丢.
+ */
+export const DEFAULT_MERGE_MAX_CHARS = 2000;
+/**
+ * 按 4 级顺序 (managed → user → project → local) 拼接为 markdown 片段.
+ *
+ * 截断策略: 反向砍 (local → project → user → managed), 优先保 managed.
+ * - 总长 < maxChars: 不截断
+ * - 总长 ≥ maxChars: 按 (local, project, user) 顺序逐步砍到 firstParagraphs=1
+ * - 最后只保 managed (bolloon 自身约束不能丢)
+ */
+export function mergeHierarchyLayers(layers, opts = {}) {
+    const maxChars = opts.maxChars ?? DEFAULT_MERGE_MAX_CHARS;
+    const parts = [];
+    const labels = [
+        ['managed', '管理规则 (Managed)'],
+        ['user', '用户规则 (User)'],
+        ['project', '项目规则 (Project)'],
+        ['local', '本地规则 (Local)'],
+    ];
+    for (const [key, label] of labels) {
+        const content = layers[key];
+        if (content) {
+            parts.push(`## ${label}\n\n${content}`);
+        }
+    }
+    if (parts.length === 0)
+        return '';
+    let result = parts.join('\n\n---\n\n');
+    if (result.length <= maxChars)
+        return result;
+    // 超限: 反向砍 (local → project → user), 二级回退到 firstParagraphs=1
+    return truncateMerged(layers, maxChars);
+}
+function truncateMerged(layers, maxChars) {
+    const order = [
+        ['local', '本地规则 (Local)'],
+        ['project', '项目规则 (Project)'],
+        ['user', '用户规则 (User)'],
+        ['managed', '管理规则 (Managed)'],
+    ];
+    const capped = { ...layers };
+    // 反复压缩, 直到总长 ≤ maxChars
+    let depth = 0; // 0=原始, 1=firstParagraphs=1, 2=砍半
+    while (depth < 3) {
+        const parts = [];
+        for (const [key, label] of order) {
+            const c = capped[key];
+            if (!c)
+                continue;
+            let text = c;
+            if (depth === 1)
+                text = firstParagraphs(c, 1);
+            if (depth === 2)
+                text = firstParagraphs(c, 1, Math.floor(maxChars / 4));
+            parts.push(`## ${label}\n\n${text}`);
+        }
+        const joined = parts.reverse().join('\n\n---\n\n'); // 恢复 managed → user → project → local
+        if (joined.length <= maxChars)
+            return joined;
+        depth++;
+    }
+    // 最后保 managed 一行
+    return `## 管理规则 (Managed)\n\n${firstParagraphs(layers.managed ?? '(无)', 1, maxChars - 50)}`;
+}
+// ============================================================
+// 工具
+// ============================================================
+function truncate(s, maxChars) {
+    if (s.length <= maxChars)
+        return s;
+    return s.substring(0, maxChars) + '\n... (truncated)';
+}
+function firstParagraphs(text, count, maxLen) {
+    const paragraphs = text.split(/\n\s*\n/).filter((p) => p.trim().length > 0);
+    let result = paragraphs.slice(0, count).join('\n\n');
+    if (maxLen && result.length > maxLen) {
+        result = result.substring(0, maxLen) + '...';
+    }
+    return result;
+}
+// ============================================================
+// 测试钩子
+// ============================================================
+/** 重置模块级状态 (供测试). 当前无状态, 保留为占位. */
+export function _resetHierarchyForTest() {
+    // no-op (collect 是纯函数, 但保留 API 一致)
+}

package/dist/bootstrap/lifecycle-hooks.js

@@ -69,36 +69,29 @@ function sanitizeChannelId(id) {
     // 防止路径穿越
     return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
 }
-// 黑名单: 高危 shell 命令模式
-const DANGEROUS_PATTERNS = [
-    { re: /\brm\s+(-[a-z]*f[a-z]*\s+)?-[a-z]*r[a-z]*\s+\//, reason: '禁止递归删除根目录' },
-    { re: /\bgit\s+push\s+.*--force\b/, reason: '禁止 force push' },
-    { re: /\brm\s+-rf\s+~\//, reason: '禁止递归删除 home' },
-    { re: /\bdd\s+if=.*\s+of=\/dev\//, reason: '禁止 dd 覆盖块设备' },
-    { re: /\bcurl\s+.*\|\s*(ba)?sh\b/, reason: '禁止 curl|sh 直执行' },
-    { re: />\s*\/dev\/sd[a-z]/, reason: '禁止写裸设备' },
-];
+// ============================================================
+// PreToolUse (P2: 4 步链式 validator + permission mode)
+// ============================================================
+import { resolvePermissionMode } from '../agents/permission-mode.js';
+import { validatePreToolUse } from '../agents/pre-tool-validator.js';
 /**
- * PreToolUse: 当前实现"危险命令拦截" (黑名单)
- * 白名单机制未启用 (默认放行所有非黑名单)
- * PreToolUse hook 接入 pi-sdk.ts 的 ReAct 循环是下个迭代
+ * PreToolUse: 4 步链式 validator
+ *   1. modeGate         (bypassPermissions + 非 shell 直接放行)
+ *   2. blacklistGate    (6 模式危险命令)
+ *   3. shellGuardGate   (路径黑名单, 绕过 mode 永远生效)
+ *   4. schemaGate       (第一版 stub: always allow)
+ *
+ * 向后兼容: 不传 permissionMode → 默认 'default' (env BOLLOON_PERM_MODE 仍生效)
+ * 失败静默: 任何异常 → allowed: true (与原行为一致)
  */
 export async function onPreToolUse(opts) {
     try {
-        // 仅检查 shell 类工具的命令字符串
-        if (opts.tool === 'shell' || opts.tool === 'shell_exec' || opts.tool === 'bash') {
-            const cmd = String(opts.args.command || opts.args.cmd || '');
-            for (const { re, reason } of DANGEROUS_PATTERNS) {
-                if (re.test(cmd)) {
-                    return { allowed: false, reason };
-                }
-            }
-        }
-        return { allowed: true };
+        const mode = resolvePermissionMode({ permissionMode: opts.permissionMode });
+        return validatePreToolUse(opts.tool, opts.args || {}, mode);
     }
     catch (err) {
-        console.warn('[lifecycle-hooks] onPreToolUse failed (silent):', err);
-        return { allowed: true }; // 失败放行 (不阻塞)
+        console.warn('[lifecycle-hooks] onPreToolUse failed (silent, allowing):', err);
+        return { allowed: true, mode: 'default' }; // 失败放行 (不阻塞)
     }
 }
 // ============================================================
@@ -107,3 +100,72 @@ export async function onPreToolUse(opts) {
 export function getStopLogPathForTest() {
     return STOP_LOG;
 }
+/**
+ * PostToolUse: 工具调用后审计
+ * 默认 always continue. 项目可挂 shell-guard audit log / judgment 注入门 / 监控门
+ * 失败静默: 任何异常 → continue: true (不阻塞主循环)
+ */
+export async function onPostToolUse(opts) {
+    try {
+        // 审计日志: 写 ~/.bolloon/sessions/post-tool-audit.jsonl
+        const fs = await import('fs/promises');
+        const os = await import('os');
+        const path = await import('path');
+        const file = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'sessions', 'post-tool-audit.jsonl');
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        const entry = {
+            ts: new Date().toISOString(),
+            tool: opts.tool,
+            success: opts.result.success,
+            durationMs: opts.durationMs ?? 0,
+            // 不写 args (可能含密钥), 只写 result 的 success/error
+            error: opts.result.error?.substring(0, 200) || null,
+        };
+        await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { });
+        return { continue: true };
+    }
+    catch (err) {
+        console.warn('[lifecycle-hooks] onPostToolUse failed (silent, allowing):', err);
+        return { continue: true };
+    }
+}
+export async function onJudgmentInjected(opts) {
+    try {
+        const fs = await import('fs/promises');
+        const os = await import('os');
+        const path = await import('path');
+        const file = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'sessions', 'judgment-injected.jsonl');
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        const entry = {
+            ts: new Date().toISOString(),
+            channelId: opts.channelId || 'unknown',
+            judgmentIds: opts.judgmentIds,
+            userInputSnippet: (opts.userInput || '').substring(0, 200),
+        };
+        await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { });
+    }
+    catch (err) {
+        console.warn('[lifecycle-hooks] onJudgmentInjected failed (silent):', err);
+    }
+}
+export async function onMonitorViolation(opts) {
+    try {
+        const fs = await import('fs/promises');
+        const os = await import('os');
+        const path = await import('path');
+        const file = path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'sessions', 'monitor-violation.jsonl');
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        const entry = {
+            ts: new Date().toISOString(),
+            channelId: opts.channelId || 'unknown',
+            judgmentId: opts.judgmentId,
+            rule: opts.rule.substring(0, 200),
+            actualBehavior: opts.actualBehavior.substring(0, 200),
+            severity: opts.severity,
+        };
+        await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { });
+    }
+    catch (err) {
+        console.warn('[lifecycle-hooks] onMonitorViolation failed (silent):', err);
+    }
+}

package/dist/bootstrap/project-context.js

@@ -6,14 +6,21 @@
  * 字符上限默认 4000 (system prompt 不能太长).
  * 超限时按优先级砍: TODO 列表 → 压缩 Bolloon.md → 砍 judgments top values
  */
-const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_MAX_CHARS = 8000; // 从 4000 提到 8000, 给 4 级 Bolloon.md 留空间
 const BOLLOON_MD_KEEP = 500; // 砍到这么长
 export function formatContextForSystemPrompt(ctx, opts = {}) {
     const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
     const lines = [];
     lines.push(`# 你的项目上下文 (自动 bootstrap, 时间: ${ctx.collectedAt})`);
     lines.push('');
-    // 1. 项目名 + Bolloon.md 摘要
+    // 1. Bolloon.md 4 级层次 (Claude Code 论文, 严格 1:1)
+    //    managed → user → project → local, 已在 collector 层 merge
+    if (ctx.hierarchy && ctx.hierarchy.merged && ctx.hierarchy.merged.length > 0) {
+        lines.push('## 规则层次 (4 级, Claude Code 论文对齐)');
+        lines.push(ctx.hierarchy.merged);
+        lines.push('');
+    }
+    // 1b. 项目名 + Bolloon.md 摘要 (向后兼容, Bolloon.md 也算 project 层之一)
     lines.push(`## 项目: ${ctx.projectName}`);
     lines.push(`- 路径: ${ctx.projectRoot}`);
     if (ctx.bolloonMd) {
@@ -40,7 +47,7 @@ export function formatContextForSystemPrompt(ctx, opts = {}) {
     }
     // 3. Persona
     if (ctx.persona) {
-        lines.push(`## 主人身份 (persona)`);
+        lines.push(`## 用户身份 (persona)`);
         lines.push(`- 名字: ${ctx.persona.name}`);
         if (ctx.persona.description)
             lines.push(`- 描述: ${ctx.persona.description}`);

package/dist/context-compaction/auto-compact.js

@@ -0,0 +1,144 @@
+/**
+ * Auto-Compact — 第 5 层: LLM 摘要 (最后手段)
+ *
+ * 论文:
+ *   - 兜底层, budget > 100% 时才触发
+ *   - 用 LLM 生成完整摘要, 替代前 K 对 user/assistant
+ *   - 摘要 prompt 明确要求"必须保留出现过的 tool names"
+ *   - 缓存到 ~/.bolloon/sessions/<channel>/compaction-cache.json
+ *   - LLM 失败 → fallback 保留原文
+ *
+ * 关键不变量: 这是**破坏性**的 (折叠 N 对成 1 条), 调用方接受新 history
+ *
+ * 失败静默: LLM 失败 → 返回原 history (与现状一致)
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const DEFAULT_COLLAPSE_PAIRS = 5;
+const CACHE_DIR = () => path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'sessions', 'compaction-cache');
+function cacheKey(history, collapsePairs) {
+    const slice = history.slice(0, collapsePairs * 2);
+    const joined = slice.map((m) => `${m.role}:${m.content}`).join('|');
+    return crypto.createHash('sha1').update(joined).digest('hex').slice(0, 12);
+}
+async function readCache(scope, key) {
+    try {
+        const file = path.join(CACHE_DIR(), `${scope}_${key}.json`);
+        const raw = await fs.readFile(file, 'utf-8');
+        const obj = JSON.parse(raw);
+        if (typeof obj.summary === 'string' && Date.now() - obj.ts < 24 * 60 * 60 * 1000) {
+            return obj.summary;
+        }
+    }
+    catch { /* cache miss or parse err */ }
+    return null;
+}
+async function writeCache(scope, key, summary) {
+    try {
+        await fs.mkdir(CACHE_DIR(), { recursive: true });
+        const file = path.join(CACHE_DIR(), `${scope}_${key}.json`);
+        await fs.writeFile(file, JSON.stringify({ ts: Date.now(), summary, key }), 'utf-8');
+    }
+    catch (err) {
+        console.warn('[compactor] cache write failed (silent):', err);
+    }
+}
+const SUMMARIZE_SYSTEM = `你是一个对话历史压缩助手.
+你的任务: 把给定的对话历史压缩成 1-2 句话的摘要, 保留所有出现过的 tool names.
+要求:
+- 保留所有用户的关键需求
+- 保留所有调用过的 tool names (例如 read_file, shell_exec, use_skill 等)
+- 保留关键决策和发现
+- 不要添加原对话中没有的信息
+- 输出纯文本, 不要 JSON, 不要 markdown 标题`;
+export async function autoCompact(history, opts = {}) {
+    try {
+        if (opts.skip)
+            return { history, applied: false, detail: 'skipped' };
+        const collapsePairs = opts.autoCompactCollapsePairs ?? DEFAULT_COLLAPSE_PAIRS;
+        // 找前 K 对的边界
+        let pairsFound = 0;
+        let cutTo = -1;
+        for (let i = 0; i < history.length; i++) {
+            if (history[i].role === 'user') {
+                pairsFound++;
+                if (pairsPairsOver(pairsFound, collapsePairs)) {
+                    cutTo = i;
+                    break;
+                }
+            }
+        }
+        if (cutTo <= 0) {
+            return { history, applied: false, detail: 'history too short' };
+        }
+        const toCollapse = history.slice(0, cutTo);
+        const remaining = history.slice(cutTo);
+        const scope = opts.cacheScope || 'default';
+        // 1. 查缓存 (key 基于实际被切的消息, 不用理论 collapsePairs)
+        const key = crypto.createHash('sha1').update(toCollapse.map((m) => `${m.role}:${m.content}`).join('|')).digest('hex').slice(0, 12);
+        let summary = await readCache(scope, key);
+        // 2. 没缓存就调 LLM
+        if (!summary) {
+            if (!opts.llmChat) {
+                // 没有 LLM 就 fallback 保留原文
+                console.warn('[compactor] autoCompact: no llmChat injected, returning original');
+                return { history, applied: false, detail: 'no llmChat available' };
+            }
+            try {
+                const userPrompt = `以下是 ${cutTo} 条较早的对话历史, 请压缩为 1-2 句摘要:\n\n${formatForSummary(toCollapse)}`;
+                summary = await opts.llmChat(SUMMARIZE_SYSTEM, userPrompt);
+                if (!summary || summary.trim().length === 0) {
+                    return { history, applied: false, detail: 'llm returned empty' };
+                }
+                // 写缓存 (静默, 但 await 确保测试可重现)
+                try {
+                    await writeCache(scope, key, summary);
+                }
+                catch { /* ignored */ }
+            }
+            catch (err) {
+                console.warn('[compactor] autoCompact LLM call failed (silent, fallback):', err);
+                return { history, applied: false, detail: 'llm call failed' };
+            }
+        }
+        // 3. 折叠: 1 条 summary 消息替代 N 条原文
+        const summaryMsg = {
+            role: 'system',
+            content: `[Auto-Compact Summary] ${summary}`,
+        };
+        return {
+            history: [summaryMsg, ...remaining],
+            applied: true,
+            detail: `collapsed ${cutTo} messages into 1 summary (cache key: ${key})`,
+        };
+    }
+    catch (err) {
+        console.warn('[compactor] autoCompact failed (silent, returning original):', err);
+        return { history, applied: false, detail: 'error' };
+    }
+}
+function pairsPairsOver(found, target) {
+    return found > target;
+}
+function formatForSummary(messages) {
+    return messages.map((m) => {
+        if (m.role === 'user')
+            return `用户: ${m.content}`;
+        if (m.role === 'assistant')
+            return `助手: ${m.content.substring(0, 500)}`;
+        if (m.role === 'tool') {
+            const r = m.toolResult;
+            return `工具: ${typeof r === 'string' ? r : JSON.stringify(r).substring(0, 300)}`;
+        }
+        return m.content;
+    }).join('\n');
+}
+// ============================================================
+// 测试钩子
+// ============================================================
+export function _resetAutoCompactCacheForTest() {
+    // 实际缓存由 readCache/writeCache 管理, 这里只暴露接口
+    // 测试可以走 fs.rm CACHE_DIR() 清理
+}

package/dist/context-compaction/budget-gate.js

@@ -0,0 +1,28 @@
+/**
+ * Budget Gate — 预算判定 (不修改消息)
+ *
+ * 论文: 这是判定阶段, 不是压缩阶段. 触发条件:
+ *   - ratio < 0.8   → fit, 不压缩
+ *   - 0.8 ≤ ratio ≤ 1.0 → triggerNextLayer (跑下一层)
+ *   - ratio > 1.0   → triggerNextLayer, 全部层都跑
+ *
+ * 失败静默: 任何异常 → 视为 fit (与现状一致, 不冒险压缩)
+ */
+import { estimateTokens } from './token-estimator.js';
+const FIT_THRESHOLD = 0.8;
+export function budgetGate(history, maxTokens = 8000) {
+    try {
+        const estimatedTokens = estimateTokens(history);
+        const ratio = maxTokens > 0 ? estimatedTokens / maxTokens : 0;
+        return {
+            fit: ratio < FIT_THRESHOLD,
+            estimatedTokens,
+            ratio,
+            triggerNextLayer: ratio >= FIT_THRESHOLD,
+        };
+    }
+    catch (err) {
+        console.warn('[compactor] budgetGate failed (silent, treating as fit):', err);
+        return { fit: true, estimatedTokens: 0, ratio: 0, triggerNextLayer: false };
+    }
+}

package/dist/context-compaction/budget-reduce.js

@@ -0,0 +1,35 @@
+/**
+ * Budget Reduction — 第 1 层: 单条消息大小限制
+ *
+ * 论文: 总是跑. 截断 > 阈值的单条消息, 加 ... [truncated, original=N chars]
+ *
+ * 关键: 不破坏 messageHistory 内存结构, 只改 buildContext 输出
+ * 但因为 buildContext 需要最终字符串, 这里实际返回新 history
+ * (内容相同的引用 = 内存未真正变更)
+ *
+ * 失败静默: 异常 → 返回原 history
+ */
+const DEFAULT_MAX_CHARS = 4000;
+export function budgetReduce(history, opts = {}) {
+    try {
+        if (opts.skip)
+            return { history, applied: false, detail: 'skipped' };
+        const maxChars = opts.budgetReduceMaxChars ?? DEFAULT_MAX_CHARS;
+        let changed = false;
+        const out = history.map((m) => {
+            if (m.content && m.content.length > maxChars) {
+                changed = true;
+                return {
+                    ...m,
+                    content: m.content.substring(0, maxChars) + `\n... [truncated, original=${m.content.length} chars]`,
+                };
+            }
+            return m;
+        });
+        return { history: out, applied: changed, detail: changed ? `truncated >${maxChars} chars` : 'no oversized messages' };
+    }
+    catch (err) {
+        console.warn('[compactor] budgetReduce failed (silent, returning original):', err);
+        return { history, applied: false, detail: 'error' };
+    }
+}

package/dist/context-compaction/context-collapse.js

@@ -0,0 +1,66 @@
+/**
+ * Context Collapse — 第 4 层: 读时虚拟投影 (非破坏)
+ *
+ * 论文:
+ *   - 不修改 messageHistory
+ *   - 在 buildContext() 输出阶段, 前 K 对 user/assistant 替换为 [collapsed: <summary>]
+ *   - feature flag BOLLOON_CONTEXT_COLLAPSE 默认关闭
+ *
+ * 实现策略:
+ *   - 由于 buildContext 阶段才输出最终字符串, 这里"虚拟投影"实际意味着:
+ *     返回一个新 history, 前 K 对用一个虚拟的 "collapsed" summary 消息替代
+ *   - 但 memory 层的 messageHistory 不变 (由调用方负责回滚或仅在 buildContext 内用)
+ *
+ * 实践: 本 stage 返回一个标记 collapsed=true 的 history, 调用方可以选择:
+ *   (a) 仅在 buildContext 字符串拼接时替换 (理想)
+ *   (b) 临时替换 (本次 LLM call 结束后回滚)
+ *   (c) 永久替换 (但这违背"非破坏"原则)
+ *
+ * 本模块选 (b): 返回新 history, 标记 collapsedMeta 字段, 文档说明调用方应仅用于构建 LLM 输入
+ *
+ * 失败静默: 异常 → 返回原 history
+ */
+const DEFAULT_COLLAPSE_PAIRS = 5;
+const DEFAULT_SUMMARY = '[collapsed: N earlier rounds — summary not yet generated]';
+export function isContextCollapseEnabled() {
+    return process.env.BOLLOON_CONTEXT_COLLAPSE === '1';
+}
+export function contextCollapse(history, opts = {}) {
+    try {
+        if (opts.skip || !isContextCollapseEnabled()) {
+            return { history, applied: false, detail: isContextCollapseEnabled() ? 'skipped' : 'feature flag off' };
+        }
+        const collapsePairs = opts.contextCollapseCollapsePairs ?? DEFAULT_COLLAPSE_PAIRS;
+        // 找前 K 对 user/assistant 的边界
+        let pairsFound = 0;
+        let cutTo = -1;
+        for (let i = 0; i < history.length; i++) {
+            if (history[i].role === 'user') {
+                pairsFound++;
+                if (pairsFound > collapsePairs) {
+                    cutTo = i;
+                    break;
+                }
+            }
+        }
+        if (cutTo <= 0) {
+            return { history, applied: false, detail: 'history too short' };
+        }
+        // 把前 cutTo 条压成 1 条 virtual summary message
+        const collapsedCount = cutTo;
+        const summaryMsg = {
+            role: 'system',
+            content: `[collapsed: ${collapsedCount} earlier messages (${collapsePairs} pairs) — virtual projection, original history preserved]`,
+        };
+        const out = [summaryMsg, ...history.slice(cutTo)];
+        return {
+            history: out,
+            applied: true,
+            detail: `virtual-collapsed first ${collapsedCount} messages`,
+        };
+    }
+    catch (err) {
+        console.warn('[compactor] contextCollapse failed (silent, returning original):', err);
+        return { history, applied: false, detail: 'error' };
+    }
+}

package/dist/context-compaction/index.js

@@ -0,0 +1,21 @@
+/**
+ * Context Compaction — 公共导出 (barrel)
+ *
+ * 设计: 严格对齐 Claude Code 论文 5 层压缩流水线
+ *   1. Budget Reduction   (单条消息大小限制)
+ *   2. Snip               (裁掉老历史, feature flag 关闭)
+ *   3. Microcompact       (cache-aware 细粒度压缩)
+ *   4. Context Collapse   (读时虚拟投影, feature flag 关闭)
+ *   5. Auto-Compact       (LLM 摘要, 兜底)
+ *
+ * 主要入口: `compactPipeline(history, opts)`
+ * 失败静默: 任何 stage 抛错 → pipeline 返回原 history
+ */
+export { compactPipeline, _resetPipelineForTest } from './pipeline.js';
+export { budgetGate } from './budget-gate.js';
+export { budgetReduce } from './budget-reduce.js';
+export { snip, isSnipEnabled } from './snip.js';
+export { microcompact } from './microcompact.js';
+export { contextCollapse, isContextCollapseEnabled } from './context-collapse.js';
+export { autoCompact, _resetAutoCompactCacheForTest } from './auto-compact.js';
+export { estimateTokens, estimateStringTokens } from './token-estimator.js';