@lingxiao-office/sdk 1.0.0

package/dist/core/checkpoint/CheckpointWriter.js

@@ -0,0 +1,193 @@
+/**
+ * CheckpointWriter — Lightweight LLM call that produces the 11-section checkpoint.
+ *
+ * NOT a full sub-agent process. It:
+ * 1. Reads existing checkpoint.md (if any) and notes.md
+ * 2. Analyzes messages since last watermark
+ * 3. Produces updated 11-section markdown via a single LLM call
+ * 4. Writes to .lingxiao/memory/sessions/<sessionId>/checkpoint.md
+ * 5. Clears notes.md (resets to empty template)
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { contentToPlainText } from '../../llm/types.js';
+import { config as runtimeConfig } from '../../config.js';
+import { coreLogger } from '../Log.js';
+import { countTokens } from '../../llm/token_counter.js';
+import { CHECKPOINT_SECTIONS } from './types.js';
+import { buildCheckpointSystemPrompt, buildCheckpointUserPrompt } from './CheckpointPrompt.js';
+/** Max characters of conversation text to feed to the writer LLM. */
+const MAX_CONVERSATION_CHARS = 80_000;
+/** Max tokens for the writer LLM response. */
+const WRITER_MAX_TOKENS = 4_000;
+/**
+ * Per-section token budgets. If a section exceeds its budget by >50%, a warning is logged.
+ */
+export const SECTION_BUDGETS = {
+    'S1 Active intent': 500,
+    'S2 Next concrete action': 1000,
+    'S3 Directives (session)': 800,
+    'S4 Task tree': 1000,
+    'S5 Current work': 2000,
+    'S6 Files and code sections': 1500,
+    'S7 Discovered knowledge': 2000,
+    'S8 Errors and fixes': 1500,
+    'S9 Live resources': 1000,
+    'S10 Design decisions': 3000,
+    'S11 Open notes': 800,
+};
+/**
+ * Validate per-section token budgets in a checkpoint document.
+ * Logs warnings for sections exceeding their budget by >50%.
+ * Does NOT fail the write.
+ */
+export function validateSectionBudgets(checkpointContent) {
+    for (const section of CHECKPOINT_SECTIONS) {
+        const budget = SECTION_BUDGETS[section];
+        if (!budget)
+            continue;
+        // Extract section content between its header and the next section header (or EOF)
+        const headerPattern = new RegExp(`^## ${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
+        const headerMatch = headerPattern.exec(checkpointContent);
+        if (!headerMatch)
+            continue;
+        const startPos = headerMatch.index + headerMatch[0].length;
+        // Find the start of the next ## S<N> header
+        const nextHeaderMatch = /^## S\d+/m.exec(checkpointContent.slice(startPos));
+        const endPos = nextHeaderMatch ? startPos + nextHeaderMatch.index : checkpointContent.length;
+        const sectionText = checkpointContent.slice(startPos, endPos).trim();
+        if (!sectionText || sectionText === '(none)')
+            continue;
+        const tokenCount = countTokens(sectionText);
+        const threshold = budget * 1.5;
+        if (tokenCount > threshold) {
+            coreLogger.warn(`[CheckpointWriter] Section "${section}" exceeds budget: ${tokenCount} tokens (budget=${budget}, threshold=${Math.round(threshold)})`);
+        }
+    }
+}
+/**
+ * Resolve the checkpoint file path for a session.
+ */
+export function resolveCheckpointPath(workspace, sessionId) {
+    return join(workspace, '.lingxiao', 'memory', 'sessions', sessionId, 'checkpoint.md');
+}
+/**
+ * Resolve the notes file path for a session.
+ */
+export function resolveNotesPath(workspace, sessionId) {
+    return join(workspace, '.lingxiao', 'memory', 'sessions', sessionId, 'notes.md');
+}
+/**
+ * Convert messages to a plain text representation for the LLM.
+ */
+function messagesToText(messages, maxChars) {
+    const lines = [];
+    let totalChars = 0;
+    for (const msg of messages) {
+        const text = contentToPlainText(msg.content).trim();
+        if (!text)
+            continue;
+        const roleLabel = msg.role === 'assistant' ? 'A' : msg.role === 'user' ? 'U' : msg.role.charAt(0).toUpperCase();
+        const line = `[${roleLabel}] ${text}`;
+        if (totalChars + line.length > maxChars) {
+            lines.push(`... (truncated, ${messages.length} messages total)`);
+            break;
+        }
+        lines.push(line);
+        totalChars += line.length;
+    }
+    return lines.join('\n\n');
+}
+/**
+ * Read an existing file or return null.
+ */
+function readFileOrNull(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            return readFileSync(filePath, 'utf-8');
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return null;
+}
+/**
+ * Execute the checkpoint writer.
+ *
+ * Makes a single LLM call to produce the checkpoint document,
+ * then writes it to disk and clears notes.md.
+ */
+export async function writeCheckpoint(input, llmClient, workspace) {
+    const checkpointPath = resolveCheckpointPath(workspace, input.sessionId);
+    const notesPath = resolveNotesPath(workspace, input.sessionId);
+    try {
+        // 1. Read existing checkpoint and notes
+        const existingCheckpoint = input.existingCheckpoint ?? readFileOrNull(checkpointPath);
+        const existingNotes = input.existingNotes ?? readFileOrNull(notesPath);
+        // 2. Convert messages to text
+        const conversationText = messagesToText(input.messages, MAX_CONVERSATION_CHARS);
+        if (!conversationText.trim()) {
+            return {
+                success: false,
+                checkpointPath,
+                watermarkMessageId: input.watermarkMessageId,
+                error: 'No conversation content to checkpoint',
+            };
+        }
+        // 3. Build prompts and call LLM
+        const systemPrompt = buildCheckpointSystemPrompt();
+        const userPrompt = buildCheckpointUserPrompt(existingCheckpoint, existingNotes, conversationText);
+        const model = runtimeConfig.llm?.agent_model || runtimeConfig.llm?.leader_model || 'default';
+        const response = await llmClient.generateContent({
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userPrompt },
+            ],
+            model,
+            maxTokens: WRITER_MAX_TOKENS,
+            sampling: { temperature: 0.2 },
+        });
+        const checkpointContent = contentToPlainText(response.content).trim();
+        if (!checkpointContent) {
+            return {
+                success: false,
+                checkpointPath,
+                watermarkMessageId: input.watermarkMessageId,
+                error: 'LLM returned empty checkpoint content',
+            };
+        }
+        // 3.5. Validate per-section token budgets (warn only, don't fail)
+        validateSectionBudgets(checkpointContent);
+        // 4. 原子写 checkpoint：先写 .tmp 再 rename（同文件系统上 rename 原子），
+        //    崩溃在写中途不会原地损毁 checkpoint.md、丢失压缩前恢复态。
+        const dir = dirname(checkpointPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const checkpointTmp = `${checkpointPath}.tmp`;
+        writeFileSync(checkpointTmp, checkpointContent, 'utf-8');
+        renameSync(checkpointTmp, checkpointPath);
+        // 5. 原子清空 notes.md（同样 tmp+rename）
+        const notesTmp = `${notesPath}.tmp`;
+        writeFileSync(notesTmp, '# Session Notes\n\n(cleared after checkpoint)\n', 'utf-8');
+        renameSync(notesTmp, notesPath);
+        coreLogger.info(`[CheckpointWriter] Wrote checkpoint for session ${input.sessionId}, watermark=${input.watermarkMessageId}`);
+        return {
+            success: true,
+            checkpointPath,
+            watermarkMessageId: input.watermarkMessageId,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        coreLogger.warn(`[CheckpointWriter] Failed to write checkpoint: ${msg}`);
+        return {
+            success: false,
+            checkpointPath,
+            watermarkMessageId: input.watermarkMessageId,
+            error: msg,
+        };
+    }
+}
+//# sourceMappingURL=CheckpointWriter.js.map

package/dist/core/checkpoint/CheckpointWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointWriter.js","sourceRoot":"","sources":["../../../src/core/checkpoint/CheckpointWriter.ts"],"names":[],"mappings":"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"}

package/dist/core/checkpoint/ContextRebuild.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ContextRebuilder — Assembles structured recovery context after checkpoint overflow.
+ *
+ * When context overflows after a checkpoint has been written, this module reads
+ * persisted knowledge sources and builds a single recovery system message with
+ * token-budgeted sections, preserving continuity across context resets.
+ */
+import type { DatabaseManager } from '../Database.js';
+/** Token budget per section for recovery context rebuild. */
+export declare const REBUILD_SECTION_BUDGETS: {
+    readonly tasks_ledger: 2000;
+    readonly session_checkpoint: 11000;
+    readonly active_actors: 500;
+    readonly project_memory: 10000;
+    readonly global_memory: 6000;
+    readonly session_notes: 6000;
+    readonly memory_keys_index: 500;
+};
+export type SectionName = keyof typeof REBUILD_SECTION_BUDGETS;
+/** Options for building recovery context. */
+export interface ContextRebuildOptions {
+    workspace: string;
+    sessionId: string;
+    db?: DatabaseManager;
+}
+/**
+ * Smart-truncate text to a token budget.
+ * Respects ## headers: won't cut mid-section; trims from the end.
+ */
+export declare function smartTruncate(text: string, tokenBudget: number): string;
+/**
+ * ContextRebuilder — builds recovery context from persisted sources.
+ */
+export declare class ContextRebuilder {
+    private workspace;
+    private sessionId;
+    private db?;
+    constructor(options: ContextRebuildOptions);
+    /**
+     * Assemble structured recovery context from all available sources.
+     * Each section is read and truncated to its token budget.
+     */
+    buildRecoveryContext(): string;
+    private readTasksLedger;
+    private readSessionCheckpoint;
+    private readActiveActors;
+    private readProjectMemory;
+    private readGlobalMemory;
+    private readSessionNotes;
+    private readMemoryKeysIndex;
+}
+//# sourceMappingURL=ContextRebuild.d.ts.map

package/dist/core/checkpoint/ContextRebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextRebuild.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/ContextRebuild.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,gBAAgB,CAAC;AAElE,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB;;;;;;;;CAQ1B,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,uBAAuB,CAAC;AAK/D,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,eAAe,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA2BvE;AAwBD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,EAAE,CAAC,CAAkB;gBAEjB,OAAO,EAAE,qBAAqB;IAM1C;;;OAGG;IACH,oBAAoB,IAAI,MAAM;IA2C9B,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,mBAAmB;CAwB5B"}

package/dist/core/checkpoint/ContextRebuild.js

@@ -0,0 +1,213 @@
+/**
+ * ContextRebuilder — Assembles structured recovery context after checkpoint overflow.
+ *
+ * When context overflows after a checkpoint has been written, this module reads
+ * persisted knowledge sources and builds a single recovery system message with
+ * token-budgeted sections, preserving continuity across context resets.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { countTokens } from '../../llm/token_counter.js';
+import { resolveCheckpointPath, resolveNotesPath } from './CheckpointWriter.js';
+/** Token budget per section for recovery context rebuild. */
+export const REBUILD_SECTION_BUDGETS = {
+    tasks_ledger: 2_000,
+    session_checkpoint: 11_000,
+    active_actors: 500,
+    project_memory: 10_000,
+    global_memory: 6_000,
+    session_notes: 6_000,
+    memory_keys_index: 500,
+};
+const CONTINUITY_FRAMING = 'This session is being continued from a checkpoint. Key context has been preserved below.';
+/**
+ * Smart-truncate text to a token budget.
+ * Respects ## headers: won't cut mid-section; trims from the end.
+ */
+export function smartTruncate(text, tokenBudget) {
+    if (!text)
+        return '';
+    const currentTokens = countTokens(text);
+    if (currentTokens <= tokenBudget)
+        return text;
+    // Split on ## headers to preserve section boundaries
+    const sections = text.split(/(?=^## )/m);
+    let result = '';
+    let usedTokens = 0;
+    for (const section of sections) {
+        const sectionTokens = countTokens(section);
+        if (usedTokens + sectionTokens > tokenBudget) {
+            // If this is the first section and it alone exceeds budget, hard-truncate it
+            if (!result) {
+                const chars = Math.max(1, Math.floor(tokenBudget * 3.5));
+                return section.slice(0, chars) + '\n... (truncated to fit token budget)';
+            }
+            result += '\n... (remaining sections truncated to fit token budget)';
+            break;
+        }
+        result += section;
+        usedTokens += sectionTokens;
+    }
+    return result;
+}
+/**
+ * Wrap a section's content in rebuild markers.
+ */
+function wrapSection(name, content) {
+    if (!content.trim())
+        return '';
+    return `<!-- REBUILD: ${name} -->\n${content.trim()}\n<!-- /REBUILD: ${name} -->\n`;
+}
+/**
+ * Read a file safely, returning empty string on failure.
+ */
+function readFileSafe(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            return readFileSync(filePath, 'utf-8');
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return '';
+}
+/**
+ * ContextRebuilder — builds recovery context from persisted sources.
+ */
+export class ContextRebuilder {
+    workspace;
+    sessionId;
+    db;
+    constructor(options) {
+        this.workspace = options.workspace;
+        this.sessionId = options.sessionId;
+        this.db = options.db;
+    }
+    /**
+     * Assemble structured recovery context from all available sources.
+     * Each section is read and truncated to its token budget.
+     */
+    buildRecoveryContext() {
+        const sections = [CONTINUITY_FRAMING, ''];
+        // 1. Tasks ledger
+        const tasksContent = this.readTasksLedger();
+        const tasksSection = wrapSection('tasks_ledger', smartTruncate(tasksContent, REBUILD_SECTION_BUDGETS.tasks_ledger));
+        if (tasksSection)
+            sections.push(tasksSection);
+        // 2. Session checkpoint
+        const checkpointContent = this.readSessionCheckpoint();
+        const checkpointSection = wrapSection('session_checkpoint', smartTruncate(checkpointContent, REBUILD_SECTION_BUDGETS.session_checkpoint));
+        if (checkpointSection)
+            sections.push(checkpointSection);
+        // 3. Active actors
+        const actorsContent = this.readActiveActors();
+        const actorsSection = wrapSection('active_actors', smartTruncate(actorsContent, REBUILD_SECTION_BUDGETS.active_actors));
+        if (actorsSection)
+            sections.push(actorsSection);
+        // 4. Project memory
+        const projectMemContent = this.readProjectMemory();
+        const projectMemSection = wrapSection('project_memory', smartTruncate(projectMemContent, REBUILD_SECTION_BUDGETS.project_memory));
+        if (projectMemSection)
+            sections.push(projectMemSection);
+        // 5. Global memory
+        const globalMemContent = this.readGlobalMemory();
+        const globalMemSection = wrapSection('global_memory', smartTruncate(globalMemContent, REBUILD_SECTION_BUDGETS.global_memory));
+        if (globalMemSection)
+            sections.push(globalMemSection);
+        // 6. Session notes
+        const notesContent = this.readSessionNotes();
+        const notesSection = wrapSection('session_notes', smartTruncate(notesContent, REBUILD_SECTION_BUDGETS.session_notes));
+        if (notesSection)
+            sections.push(notesSection);
+        // 7. Memory keys index
+        const keysContent = this.readMemoryKeysIndex();
+        const keysSection = wrapSection('memory_keys_index', smartTruncate(keysContent, REBUILD_SECTION_BUDGETS.memory_keys_index));
+        if (keysSection)
+            sections.push(keysSection);
+        return sections.join('\n');
+    }
+    // ─── Source readers ───────────────────────────────────────────────────
+    readTasksLedger() {
+        if (!this.db)
+            return '';
+        try {
+            if (typeof this.db.getAgentStates !== 'function')
+                return '';
+            const agents = this.db.getAgentStates(this.sessionId);
+            const running = agents.filter(a => a.status === 'running' || !a.stopped);
+            if (running.length === 0)
+                return '';
+            const lines = ['## Active Tasks', ''];
+            for (const agent of running) {
+                lines.push(`- [${agent.status}] ${agent.agent_name}: task=${agent.task_id || '(none)'}`);
+            }
+            return lines.join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+    readSessionCheckpoint() {
+        const checkpointPath = resolveCheckpointPath(this.workspace, this.sessionId);
+        return readFileSafe(checkpointPath);
+    }
+    readActiveActors() {
+        if (!this.db)
+            return '';
+        try {
+            if (typeof this.db.getAgentStates !== 'function')
+                return '';
+            const agents = this.db.getAgentStates(this.sessionId);
+            const running = agents.filter(a => !a.stopped);
+            if (running.length === 0)
+                return '';
+            const lines = ['## Running Subagents', ''];
+            for (const agent of running) {
+                lines.push(`- ${agent.agent_name} (${agent.agent_role}) [iter=${agent.iteration}]`);
+            }
+            return lines.join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+    readProjectMemory() {
+        const memoryPath = join(this.workspace, '.lingxiao', 'memory', 'MEMORY.md');
+        return readFileSafe(memoryPath);
+    }
+    readGlobalMemory() {
+        const globalPath = join(homedir(), '.lingxiao', 'memory', 'MEMORY.md');
+        return readFileSafe(globalPath);
+    }
+    readSessionNotes() {
+        const notesPath = resolveNotesPath(this.workspace, this.sessionId);
+        return readFileSafe(notesPath);
+    }
+    readMemoryKeysIndex() {
+        const memoryDir = join(this.workspace, '.lingxiao', 'memory');
+        try {
+            if (!existsSync(memoryDir))
+                return '';
+            const files = readdirSync(memoryDir).filter(f => f.endsWith('.md') && f !== 'MEMORY.md');
+            if (files.length === 0)
+                return '';
+            const lines = ['## Memory Files', ''];
+            for (const file of files) {
+                const name = basename(file, '.md');
+                // Try to extract first line as title
+                const filePath = join(memoryDir, file);
+                const content = readFileSafe(filePath);
+                const firstLine = content.split('\n').find(l => l.trim().startsWith('#'));
+                const title = firstLine ? firstLine.replace(/^#+\s*/, '').trim() : name;
+                lines.push(`- ${name}: ${title}`);
+            }
+            return lines.join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=ContextRebuild.js.map

package/dist/core/checkpoint/ContextRebuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextRebuild.js","sourceRoot":"","sources":["../../../src/core/checkpoint/ContextRebuild.ts"],"names":[],"mappings":"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"}

package/dist/core/checkpoint/MicroCompact.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MicroCompact — Clears tool_result content for large-output tools in preserved tail messages.
+ *
+ * When rebuilding context after overflow, the preserved message tail still carries
+ * potentially massive tool results (file reads, bash output, web fetches). This module
+ * replaces those results with a compact placeholder, drastically reducing token usage
+ * while preserving the conversation structure.
+ */
+import { type ChatMessage } from '../../llm/types.js';
+/** Tools whose results should be compacted (large-output tools). */
+declare const COMPACTABLE_TOOLS: Set<string>;
+/** Placeholder text for compacted tool results. */
+declare const COMPACT_PLACEHOLDER = "[output compacted - see checkpoint for context]";
+/**
+ * 微压缩的字节下限：工具结果字节数低于此值时**原样保留**，不替换为占位符。
+ *
+ * 动机：占位符本身 ~46 字节。对短结果（exit code、文件路径、grep 计数、小文件片段）做压缩，
+ * 既丢信号又可能反而变大。只有达到此量级的结果才值得用占位符换 token。这是一个明确的
+ * 字节工程参数（与 BYTE_THRESHOLD_RATIO / largeOutputBytes 同类），非分类启发式。
+ */
+declare const MICROCOMPACT_MIN_BYTES = 256;
+/**
+ * Compact tool results in preserved tail messages.
+ *
+ * - Keeps user messages and assistant text untouched.
+ * - For tool messages from compactable tools: replaces content with placeholder.
+ * - For assistant messages with tool_calls: keeps the tool_call structure,
+ *   only clears the result content in corresponding tool messages.
+ */
+export declare function microCompact(messages: ChatMessage[]): ChatMessage[];
+export { COMPACTABLE_TOOLS, COMPACT_PLACEHOLDER, MICROCOMPACT_MIN_BYTES };
+//# sourceMappingURL=MicroCompact.d.ts.map

package/dist/core/checkpoint/MicroCompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicroCompact.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/MicroCompact.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,oEAAoE;AACpE,QAAA,MAAM,iBAAiB,aAUrB,CAAC;AAEH,mDAAmD;AACnD,QAAA,MAAM,mBAAmB,oDAAoD,CAAC;AAE9E;;;;;;GAMG;AACH,QAAA,MAAM,sBAAsB,MAAM,CAAC;AAmCnC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CA2CnE;AAED,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/core/checkpoint/MicroCompact.js

@@ -0,0 +1,109 @@
+/**
+ * MicroCompact — Clears tool_result content for large-output tools in preserved tail messages.
+ *
+ * When rebuilding context after overflow, the preserved message tail still carries
+ * potentially massive tool results (file reads, bash output, web fetches). This module
+ * replaces those results with a compact placeholder, drastically reducing token usage
+ * while preserving the conversation structure.
+ */
+/** Tools whose results should be compacted (large-output tools). */
+const COMPACTABLE_TOOLS = new Set([
+    'read',
+    'bash',
+    'grep',
+    'glob',
+    'webfetch',
+    'websearch',
+    'edit',
+    'write',
+    'apply_patch',
+]);
+/** Placeholder text for compacted tool results. */
+const COMPACT_PLACEHOLDER = '[output compacted - see checkpoint for context]';
+/**
+ * 微压缩的字节下限：工具结果字节数低于此值时**原样保留**，不替换为占位符。
+ *
+ * 动机：占位符本身 ~46 字节。对短结果（exit code、文件路径、grep 计数、小文件片段）做压缩，
+ * 既丢信号又可能反而变大。只有达到此量级的结果才值得用占位符换 token。这是一个明确的
+ * 字节工程参数（与 BYTE_THRESHOLD_RATIO / largeOutputBytes 同类），非分类启发式。
+ */
+const MICROCOMPACT_MIN_BYTES = 256;
+/** 计算消息 content 的 UTF-8 字节数（覆盖 string / 数组 / 对象）。 */
+function contentByteLength(content) {
+    if (typeof content === 'string')
+        return Buffer.byteLength(content, 'utf8');
+    if (content == null)
+        return 0;
+    return Buffer.byteLength(JSON.stringify(content), 'utf8');
+}
+/**
+ * Determine if a tool message is from one of the compactable tools.
+ *
+ * Matches only on the exact tool name carried in the message's `name` field.
+ * The tool→message linkage by id is handled in microCompact via the
+ * compactableCallIds set (exact id equality); we deliberately avoid substring
+ * scanning of tool_call_id here, which could mis-classify ids that merely
+ * contain a tool name as a substring.
+ */
+function isCompactableTool(message) {
+    if (message.role !== 'tool')
+        return false;
+    if (message.name && COMPACTABLE_TOOLS.has(message.name.toLowerCase())) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if a tool_call references a compactable tool.
+ */
+function isCompactableToolCall(toolCallName) {
+    return COMPACTABLE_TOOLS.has(toolCallName.toLowerCase());
+}
+/**
+ * Compact tool results in preserved tail messages.
+ *
+ * - Keeps user messages and assistant text untouched.
+ * - For tool messages from compactable tools: replaces content with placeholder.
+ * - For assistant messages with tool_calls: keeps the tool_call structure,
+ *   only clears the result content in corresponding tool messages.
+ */
+export function microCompact(messages) {
+    // Build a set of tool_call IDs that reference compactable tools
+    const compactableCallIds = new Set();
+    for (const msg of messages) {
+        if (msg.role === 'assistant' && msg.tool_calls) {
+            for (const tc of msg.tool_calls) {
+                if (isCompactableToolCall(tc.function.name)) {
+                    compactableCallIds.add(tc.id);
+                }
+            }
+        }
+    }
+    return messages.map((msg) => {
+        // Keep user and system messages untouched
+        if (msg.role === 'user' || msg.role === 'system') {
+            return msg;
+        }
+        // Keep assistant messages untouched (including tool_calls)
+        if (msg.role === 'assistant') {
+            return msg;
+        }
+        // For tool messages: compact if it matches a compactable tool AND exceeds the size floor.
+        // 小结果（exit code / 路径 / 计数 / 小文件片段）低于 MICROCOMPACT_MIN_BYTES 时原样保留——
+        // 既不丢信号，也避免占位符反而比原文更大。
+        if (msg.role === 'tool') {
+            const shouldCompact = ((msg.tool_call_id && compactableCallIds.has(msg.tool_call_id)) ||
+                isCompactableTool(msg)) &&
+                contentByteLength(msg.content) >= MICROCOMPACT_MIN_BYTES;
+            if (shouldCompact) {
+                return {
+                    ...msg,
+                    content: COMPACT_PLACEHOLDER,
+                };
+            }
+        }
+        return msg;
+    });
+}
+export { COMPACTABLE_TOOLS, COMPACT_PLACEHOLDER, MICROCOMPACT_MIN_BYTES };
+//# sourceMappingURL=MicroCompact.js.map

package/dist/core/checkpoint/MicroCompact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicroCompact.js","sourceRoot":"","sources":["../../../src/core/checkpoint/MicroCompact.ts"],"names":[],"mappings":"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"}

package/dist/core/checkpoint/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Checkpoint module — structured knowledge persistence across context compactions.
+ */
+export { CheckpointService } from './CheckpointService.js';
+export { writeCheckpoint, resolveCheckpointPath, resolveNotesPath, validateSectionBudgets, SECTION_BUDGETS } from './CheckpointWriter.js';
+export { evaluateBoundary, computeThresholds, messageId } from './CheckpointBoundary.js';
+export { buildCheckpointSystemPrompt, buildCheckpointUserPrompt } from './CheckpointPrompt.js';
+export { ContextRebuilder, smartTruncate, REBUILD_SECTION_BUDGETS } from './ContextRebuild.js';
+export { microCompact, COMPACTABLE_TOOLS, COMPACT_PLACEHOLDER } from './MicroCompact.js';
+export { CHECKPOINT_SECTIONS, type CheckpointSectionKey, type CheckpointWriterInput, type CheckpointWriteResult, type CheckpointServiceOptions, type CheckpointBoundaryResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/checkpoint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC1I,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,GAC9B,MAAM,YAAY,CAAC"}