1

async compact(customInstructions?: string): Promise<CompactionResult>

1
2
3
4

this._disconnectFromAgent();
await this.abort();
this._compactionAbortController = new AbortController();
this._emit({ type: "compaction_start", reason: "manual" });

1
2

if (!this.model) throw new Error(formatNoModelSelectedMessage());
const { apiKey, headers, env } = await this._getCompactionRequestAuth(this.model);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const pathEntries = this.sessionManager.getBranch();
const settings = this.settingsManager.getCompactionSettings();
const preparation = prepareCompaction(pathEntries, settings);
if (!preparation) {
    const lastEntry = pathEntries[pathEntries.length - 1];
    if (lastEntry?.type === "compaction") {
        throw new Error("Already compacted");
    }
    throw new Error("Nothing to compact (session too small)");
}

1
2

let extensionCompaction: CompactionResult | undefined;
let fromExtension = false;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

if (this._extensionRunner.hasHandlers("session_before_compact")) {
    const result = (await this._extensionRunner.emit({
        type: "session_before_compact",
        preparation,
        branchEntries: pathEntries,
        customInstructions,
        reason: "manual",
        willRetry: false,
        signal: this._compactionAbortController.signal,
    })) as SessionBeforeCompactResult | undefined;

    if (result?.cancel) {
        throw new Error("Compaction cancelled");
    }

    if (result?.compaction) {
        extensionCompaction = result.compaction;
        fromExtension = true;
    }
}

1
2
3
4

let summary: string;
let firstKeptEntryId: string;
let tokensBefore: number;
let details: unknown;

1
2
3
4
5

if (extensionCompaction) {
    // 使用扩展提供的压缩结果
} else {
    const result = await compact(preparation, this.model, apiKey, headers, ...);
}

1
2
3
4

this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
const newEntries = this.sessionManager.getEntries();
const sessionContext = this.sessionManager.buildSessionContext();
this.agent.state.messages = sessionContext.messages;

1
2

this._emit({ type: "compaction_end", reason: "manual", result: compactionResult, ... });
return compactionResult;

1
2
3
4
5

// 手动压缩
await session.compact();

// 带自定义指令的压缩
await session.compact("Focus on summarizing the API design decisions");

1

abortCompaction(): void

1
2

setAutoCompactionEnabled(enabled: boolean): void
get autoCompactionEnabled(): boolean

1
2
3
4
5
6
7
8

// 完整实现仅两行
setAutoCompactionEnabled(enabled: boolean): void {
    this.settingsManager.setCompactionEnabled(enabled);
}

get autoCompactionEnabled(): boolean {
    return this.settingsManager.getCompactionEnabled();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// settings-manager.ts 第 754-760 行
getCompactionEnabled(): boolean {
    return this.settings.compaction?.enabled ?? true;  // 默认 true
}

setCompactionEnabled(enabled: boolean): void {
    if (!this.globalSettings.compaction) {
        this.globalSettings.compaction = {};
    }
    this.globalSettings.compaction.enabled = enabled;
    this.markModified("compaction", "enabled");
    this.save();
}

1
2
3

// footer.ts 第 150 行
const autoIndicator = this.autoCompactEnabled ? " (auto)" : "";
// 显示为 "Compact" 或 "Compact (auto)"

1

private async _checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck = true): Promise<boolean>

1
2
3

if (!settings.enabled) return false;                          // 自动压缩未开启
if (aborted && skipAbortedCheck) return false;                // 跳过用户取消的消息
if (assistant来自压缩前) return false;                         // 防止刚压缩完又触发

1
2
3
4
5
6
7
8

if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
    const willRetry = assistantMessage.stopReason !== "stop";
    if (!willRetry) return await this._runAutoCompaction("overflow", false);
    if (this._overflowRecoveryAttempted) { /* 已尝试过一次恢复，放弃 */ return false; }
    this._overflowRecoveryAttempted = true;
    this.agent.state.messages = messages.slice(0, -1);  // 移除错误消息
    return await this._runAutoCompaction("overflow", willRetry);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

let contextTokens: number;
// 对于 error 消息或 usage 全部为零的消息，从最后有效的 assistant 估计
if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
    const estimate = estimateContextTokens(messages);
    if (estimate.lastUsageIndex === null) return false;
    contextTokens = estimate.tokens;
} else {
    contextTokens = directContextTokens;
}
if (shouldCompact(contextTokens, contextWindow, settings)) {
    return await this._runAutoCompaction("threshold", false);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// compaction/compaction.ts
export function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {
    const usageInfo = getLastAssistantUsageInfo(messages);
    if (!usageInfo) return { tokens: 全量估算, lastUsageIndex: null };
    // 有真实 usage 数据: usageTokens + 后续消息的估算
    const usageTokens = calculateContextTokens(usageInfo.usage);
    let trailingTokens = 0;
    for (let i = usageInfo.index + 1; i < messages.length; i++) {
        trailingTokens += estimateTokens(messages[i]);
    }
    return { tokens: usageTokens + trailingTokens, ... };
}

1

private async _runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean): Promise<boolean>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const settings = this.settingsManager.getCompactionSettings();

if (!this.model) {
    return false;  // 无模型 → 静默跳过，不报错
}

// 获取 API Key
if (this.agent.streamFn === streamSimple) {
    const authResult = await this._modelRegistry.getApiKeyAndHeaders(this.model);
    if (!authResult.ok || !authResult.apiKey) {
        return false;  // 认证失败 → 静默跳过
    }
}

1
2
3
4
5

const pathEntries = this.sessionManager.getBranch();
const preparation = prepareCompaction(pathEntries, settings);
if (!preparation) {
    return false;  // 无内容可压缩 → 静默跳过
}

1
2
3

this._emit({ type: "compaction_start", reason });
this._autoCompactionAbortController = new AbortController();
started = true;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

if (this._extensionRunner.hasHandlers("session_before_compact")) {
    const extensionResult = (await this._extensionRunner.emit({
        type: "session_before_compact",
        preparation,
        branchEntries: pathEntries,
        customInstructions: undefined,  // 自动压缩无自定义指令
        reason,
        willRetry,
        signal: this._autoCompactionAbortController.signal,
    })) as SessionBeforeCompactResult | undefined;

    if (extensionResult?.cancel) {
        this._emit({ type: "compaction_end", reason, result: undefined, aborted: true, willRetry: false });
        return false;
    }

    if (extensionResult?.compaction) {
        extensionCompaction = extensionResult.compaction;
        fromExtension = true;
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

if (extensionCompaction) {
    summary = extensionCompaction.summary;
    firstKeptEntryId = extensionCompaction.firstKeptEntryId;
    tokensBefore = extensionCompaction.tokensBefore;
    details = extensionCompaction.details;
} else {
    const compactResult = await compact(
        preparation,
        this.model,
        apiKey,
        headers,
        undefined,  // customInstructions = undefined
        this._autoCompactionAbortController.signal,
        this.thinkingLevel,
        this.agent.streamFn,
        env,
    );
    // ... 解构结果
}

1
2
3
4

if (this._autoCompactionAbortController.signal.aborted) {
    this._emit({ type: "compaction_end", reason, result: undefined, aborted: true, willRetry: false });
    return false;
}

1
2
3
4
5

this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
const newEntries = this.sessionManager.getEntries();
const sessionContext = this.sessionManager.buildSessionContext();
this.agent.state.messages = sessionContext.messages;
const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const savedCompactionEntry = newEntries.find(
    (e) => e.type === "compaction" && e.summary === summary
) as CompactionEntry | undefined;

if (this._extensionRunner && savedCompactionEntry) {
    await this._extensionRunner.emit({
        type: "session_compact",
        compactionEntry: savedCompactionEntry,
        fromExtension,
        reason,
        willRetry,
    });
}

1
2

const result: CompactionResult = { summary, firstKeptEntryId, tokensBefore, estimatedTokensAfter, details };
this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

if (willRetry) {
    const messages = this.agent.state.messages;
    const lastMsg = messages[messages.length - 1];
    if (lastMsg?.role === "assistant" && (lastMsg as AssistantMessage).stopReason === "error") {
        this.agent.state.messages = messages.slice(0, -1);  // 移除 overflow 错误消息
    }
    return true;  // 告诉 _handlePostAgentRun: 需要 agent.continue()
}

return this.agent.hasQueuedMessages();  // 检查是否有排队消息需要处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

catch (error) {
    const errorMessage = error instanceof Error ? error.message : "compaction failed";
    if (started) {
        this._emit({
            type: "compaction_end",
            reason,
            result: undefined,
            aborted: false,
            willRetry: false,
            errorMessage:
                reason === "overflow"
                    ? `Context overflow recovery failed: ${errorMessage}`
                    : `Auto-compaction failed: ${errorMessage}`,
        });
    }
    return false;
} finally {
    this._autoCompactionAbortController = undefined;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Overflow recovery chain
// agent-session.ts line 1075-1080
_handlePostAgentRun() -> _checkCompaction(msg)
  -> case "overflow" (stopReason !== "stop")
    -> _runAutoCompaction("overflow", willRetry: true)
      -> compact() 在内部生成摘要
      -> appendCompaction() 持久化
      -> buildSessionContext() 重建上下文
      -> return true
    -> _handlePostAgentRun() 返回 true
  -> throw new Error("..."); // 如果 willRetry=false 且 overflow 未恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Threshold compression chain
// agent-session.ts line 1092
_handlePostAgentRun() -> _checkCompaction(msg)
  -> case "threshold" (contextTokens > contextWindow - reserveTokens)
    -> _runAutoCompaction("threshold", willRetry: false)
      -> compact() 在内部生成摘要
      -> appendCompaction() 持久化
      -> buildSessionContext() 重建上下文
      -> return this.agent.hasQueuedMessages()
    -> _handlePostAgentRun() 返回 false
  -> _runAgentPrompt() 的 while 循环终止


---

## 四、Compaction 模块（`compaction/compaction.ts`）

### 4.1 `prepareCompaction()` — 压缩准备

```typescript
export function prepareCompaction(
    pathEntries: SessionEntry[],
    settings: CompactionSettings,
): CompactionPreparation | undefined

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

export interface CompactionPreparation {
    firstKeptEntryId: string;          // 第一条保留的 entry 的 UUID
    messagesToSummarize: AgentMessage[]; // 需要摘要后丢弃的消息
    turnPrefixMessages: AgentMessage[];  // 切分 turn 时前缀中的消息
    isSplitTurn: boolean;              // 是否切分了某个 turn
    tokensBefore: number;              // 压缩前的 token 数
    previousSummary?: string;          // 上次压缩的摘要（用于增量更新）
    fileOps: FileOperations;           // 从消息中提取的文件操作
    settings: CompactionSettings;      // 压缩设置
}

1
2
3
4
5
6

let prevCompactionIndex = -1;
for (let i = pathEntries.length - 1; i >= 0; i--) {
    if (pathEntries[i].type === "compaction") {
        prevCompactionIndex = i; break;
    }
}

1

const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, settings.keepRecentTokens);

1
2
3

const historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;
// messagesToSummarize: boundaryStart ~ historyEnd 的消息
// turnPrefixMessages: 如果切分 turn，turn 前缀中的消息

1

const fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);

1
2
3

if (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0) {
    return undefined; // 没有需要压缩的内容
}

1
2
3
4
5
6

export function findCutPoint(
    entries: SessionEntry[],
    startIndex: number,
    endIndex: number,
    keepRecentTokens: number,
): CutPointResult

1
2
3
4
5
6

function findValidCutPoints(entries, startIndex, endIndex): number[] {
    // 只保留: user, assistant, bashExecution, custom,
    //          branchSummary, compactionSummary
    // 排除: toolResult（必须跟在对应的 toolCall 后面）
    // 排除: thinking_level_change, model_change 等元数据 entry
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

export async function compact(
    preparation: CompactionPreparation,
    model: Model<any>,
    apiKey: string | undefined,
    headers?: Record<string, string>,
    customInstructions?: string,
    signal?: AbortSignal,
    thinkingLevel?: ThinkingLevel,
    streamFn?: StreamFn,
    env?: Record<string, string>,
): Promise<CompactionResult>

1

summary = await generateSummary(messagesToSummarize, model, ...);

1
2
3
4
5
6

// 并行生成两个摘要
const [historyResult, turnPrefixResult] = await Promise.all([
    generateSummary(messagesToSummarize, model, ...),
    generateTurnPrefixSummary(turnPrefixMessages, model, ...),
]);
summary = `${historyResult}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult}`;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const { readFiles, modifiedFiles } = computeFileLists(fileOps);
summary += formatFileOperations(readFiles, modifiedFiles);
// 生成格式如:
// <read-files>
// src/index.ts
// src/utils.ts
// </read-files>
// <modified-files>
// src/app.ts
// </modified-files>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

export async function generateSummary(
    currentMessages: AgentMessage[],
    model: Model<any>,
    reserveTokens: number,
    apiKey?: string,
    headers?: Record<string, string>,
    signal?: AbortSignal,
    customInstructions?: string,
    previousSummary?: string,
    thinkingLevel?: ThinkingLevel,
    streamFn?: StreamFn,
    env?: Record<string, string>,
): Promise<string>

1
2
3
4

const maxTokens = Math.min(
    Math.floor(0.8 * reserveTokens),
    model.maxTokens > 0 ? model.maxTokens : Infinity,
);

1

let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;

1
2

const llmMessages = convertToLlm(currentMessages);  // 转换自定义消息类型
const conversationText = serializeConversation(llmMessages);  // 序列化为纯文本

1

const response = await completeSummarization(model, context, options, streamFn);

1
2
3
4
5
6
7
8

// 首次压缩
const summary = await generateSummary(historyMessages, model, 16384, apiKey);

// 增量压缩（已有前次摘要）
const updatedSummary = await generateSummary(
    newMessages, model, 16384, apiKey,
    undefined, undefined, undefined, previousSummary
);

1
2
3
4
5
6
7

export interface FileOperations {
    read: Set<string>;
    written: Set<string>;
    edited: Set<string>;
}

export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void

1

export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[] }

1

export function serializeConversation(messages: Message[]): string

1

export function estimateTokens(message: AgentMessage): number

1
2
3
4
5
6
7
8
9

// session-manager.ts
export interface CompactionEntry<T = unknown> extends SessionEntryBase {
    type: "compaction";
    summary: string;           // LLM 生成的结构化摘要
    firstKeptEntryId: string;  // 第一条保留 entry 的 UUID
    tokensBefore: number;      // 压缩前总 token 数
    details?: T;               // 扩展数据（如文件操作列表）
    fromHook?: boolean;        // 是否由扩展生成
}

1
2
3
4
5
6
7

export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
    type: "branch_summary";
    fromId: string;         // 来源 entry ID
    summary: string;        // 分支摘要
    details?: T;            // 扩展数据
    fromHook?: boolean;     // 是否由扩展生成
}

1
2
3
4
5
6
7
8

// compaction/compaction.ts
export interface CompactionResult<T = unknown> {
    summary: string;
    firstKeptEntryId: string;
    tokensBefore: number;
    estimatedTokensAfter?: number;     // 压缩后估算 token 数
    details?: T;                       // 扩展数据
}

1
2
3
4
5
6
7
8

export function shouldCompact(
    contextTokens: number,
    contextWindow: number,
    settings: CompactionSettings,
): boolean {
    if (!settings.enabled) return false;
    return contextTokens > contextWindow - settings.reserveTokens;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// AgentSession 发出的事件类型
| { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
| {
    type: "compaction_end";
    reason: "manual" | "threshold" | "overflow";
    result: CompactionResult | undefined;
    aborted: boolean;
    willRetry: boolean;
    errorMessage?: string;
}

1
2
3
4
5
6
7
8
9

// Extension 系统发出的事件
type: "session_before_compact";
// 扩展可返回 SessionBeforeCompactResult:
// - cancel: 取消压缩
// - compaction: 扩展自定义压缩结果

type: "session_compact";
// 压缩完成后通知扩展
// 包含压缩结果、是否来自扩展、触发原因

1
2
3
4
5
6

// compaction/compaction.ts
export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
    enabled: true,           // 自动压缩默认开启
    reserveTokens: 16384,    // 保留的 token 余量（16K）
    keepRecentTokens: 20000, // 保留最近的 token 数（20K）
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/**
 * Temporarily disconnect from agent events.
 * User listeners are preserved and will receive events again after resubscribe().
 * Used internally during operations that need to pause event processing.
 */
private _disconnectFromAgent(): void {
    if (this._unsubscribeAgent) {
        this._unsubscribeAgent();
        this._unsubscribeAgent = undefined;
    }
}

1
2
3
4

private _reconnectToAgent(): void {
    if (this._unsubscribeAgent) return;  // 已连接，跳过
    this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
}

1
2

// 构造函数中
this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// 在 _bindExtensionCore 的第二个参数（runtimeContext）中
{
    getContextUsage: () => this.getContextUsage(),
    compact: (options) => {
        void (async () => {
            try {
                const result = await this.compact(options?.customInstructions);
                options?.onComplete?.(result);
            } catch (error) {
                const err = error instanceof Error ? error : new Error(String(error));
                options?.onError?.(err);
            }
        })();
    },
    // ...
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 扩展代码中
ctx.compact({
    customInstructions: "Focus on summarizing API changes",
    onComplete: (result) => {
        console.log(`Compacted: ${result.tokensBefore} -> ${result.estimatedTokensAfter} tokens`);
    },
    onError: (err) => {
        console.error(`Compaction failed: ${err.message}`);
    },
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

getContextUsage(): ContextUsage | undefined {
    const model = this.model;
    if (!model) return undefined;

    const contextWindow = model.contextWindow ?? 0;
    if (contextWindow <= 0) return undefined;

    const branchEntries = this.sessionManager.getBranch();
    const latestCompaction = getLatestCompactionEntry(branchEntries);

    if (latestCompaction) {
        // Check if there's a valid assistant usage after the compaction boundary
        const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
        let hasPostCompactionUsage = false;
        for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
            const entry = branchEntries[i];
            if (entry.type === "message" && entry.message.role === "assistant") {
                const assistant = entry.message;
                if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
                    const contextTokens = calculateContextTokens(assistant.usage);
                    if (contextTokens > 0) {
                        hasPostCompactionUsage = true;
                        break;
                    }
                }
            }
        }

        if (!hasPostCompactionUsage) {
            return { tokens: null, contextWindow, percent: null };
        }
    }

    const estimate = estimateContextTokens(this.messages);
    const percent = (estimate.tokens / contextWindow) * 100;

    return { tokens: estimate.tokens, contextWindow, percent };
}