第7章：上下文压缩 —— 五层防线

messagesForQuery = getMessagesAfterCompactBoundary(messages)
        ↓
① applyToolResultBudget      单条消息里工具结果的总量上限（内容替换）
        ↓
② snipCompact                掐掉历史片段              [HISTORY_SNIP]
        ↓
③ microcompact               清空/删除老工具结果
        ↓
④ applyCollapsesIfNeeded     折叠视图投影              [CONTEXT_COLLAPSE]
        ↓
⑤ autoCompactIfNeeded        整段摘要
        ↓
   blocking-limit 检查        还是超了 → return
        ↓
   发请求 →  413  →  ⑥ context-collapse 排空 → ⑦ reactive compact

// Enforce per-message budget on aggregate tool result size. Runs BEFORE
// microcompact — cached MC operates purely by tool_use_id (never inspects
// content), so content replacement is invisible to it and the two compose
// cleanly.

// Runs BEFORE autocompact so that if collapse gets us under the
// autocompact threshold, autocompact is a no-op and we keep granular
// context instead of a single summary.

/**
 * Maximum size in characters for tool result before it gets persisted to disk.
 * When exceeded, the result is saved to a file and Claude receives a preview
 * with the file path instead of the full content.
 *
 * Set to Infinity for tools whose output must never be persisted (e.g. Read,
 * where persisting creates a circular Read→file→Read loop and the tool
 * already self-bounds via its own limits).
 */
maxResultSizeChars: number

messagesForQuery = await applyToolResultBudget(
  messagesForQuery,
  toolUseContext.contentReplacementState,
  persistReplacements ? records => void recordContentReplacement(records, toolUseContext.agentId).catch(logError) : undefined,
  new Set(toolUseContext.options.tools.filter(t => !Number.isFinite(t.maxResultSizeChars)).map(t => t.name)),
)

// Persist only for querySources that read records back on resume: agentId
// routes to sidechain file (AgentTool resume) or session file (/resume).
// Ephemeral runForkedAgent callers (agent_summary etc.) don't persist.
const persistReplacements =
  querySource.startsWith('agent:') || querySource.startsWith('repl_main_thread')

const COMPACTABLE_TOOLS = new Set<string>([
  FILE_READ_TOOL_NAME,
  ...SHELL_TOOL_NAMES,
  GREP_TOOL_NAME,
  GLOB_TOOL_NAME,
  WEB_SEARCH_TOOL_NAME,
  WEB_FETCH_TOOL_NAME,
  FILE_EDIT_TOOL_NAME,
  FILE_WRITE_TOOL_NAME,
])

export const TIME_BASED_MC_CLEARED_MESSAGE = '[Old tool result content cleared]'

/**
 * Triggers content-clearing microcompact when the gap since the last main-loop
 * assistant message exceeds a threshold — the server-side prompt cache has
 * almost certainly expired, so the full prefix will be rewritten anyway.
 * Clearing old tool results before the request shrinks what gets rewritten.
 *
 * Runs BEFORE the API call (in microcompactMessages, upstream of callModel)
 * so the shrunk prompt is what actually gets sent. Running after the first
 * miss would only help subsequent turns.
 *
 * Main thread only — subagents have short lifetimes where gap-based eviction
 * doesn't apply.
 */
export type TimeBasedMCConfig = {
  enabled: boolean
  /** Trigger when (now − last assistant timestamp) exceeds this many minutes.
   *  60 is the safe choice: the server's 1h cache TTL is guaranteed expired
   *  for all users, so we never force a miss that wouldn't have happened. */
  gapThresholdMinutes: number
  /** Keep this many most-recent compactable tool results. */
  keepRecent: number
}

const TIME_BASED_MC_CONFIG_DEFAULTS: TimeBasedMCConfig = {
  enabled: false,
  gapThresholdMinutes: 60,
  keepRecent: 5,
}

// Time-based trigger runs first and short-circuits. … Cached MC (cache-editing)
// is skipped when this fires: editing assumes a warm cache, and we just
// established it's cold.
const timeBasedResult = maybeTimeBasedMicrocompact(messages, querySource)
if (timeBasedResult) return timeBasedResult

export type PendingCacheEdits = {
  trigger: 'auto'
  deletedToolIds: string[]
  // Baseline cumulative cache_deleted_input_tokens from the previous API response,
  // used to compute the per-operation delta (the API value is sticky/cumulative)
  baselineCacheDeletedTokens: number
}

/**
 * Cached microcompact path - uses cache editing API to remove tool results
 * without invalidating the cached prefix.
 *
 * Key differences from regular microcompact:
 * - Does NOT modify local message content (cache_reference and cache_edits are
 *   added at API layer)
 */

if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) {
  const usage = assistantMessages.at(-1)?.message.usage
  // The API field is cumulative/sticky across requests, so we
  // subtract the baseline captured before this request to get the delta.
  const cumulativeDeleted = usage?.cache_deleted_input_tokens ?? 0
  const deletedTokens = Math.max(0, cumulativeDeleted - pendingCacheEdits.baselineCacheDeletedTokens)
  if (deletedTokens > 0) {
    yield createMicrocompactBoundaryMessage(pendingCacheEdits.trigger, 0, deletedTokens, pendingCacheEdits.deletedToolIds, [])
  }
}

// Prefix-match because promptCategory.ts sets the querySource to
// 'repl_main_thread:outputStyle:<style>' when a non-default output style
// is active. … the pre-existing cached-MC `=== 'repl_main_thread'` check
// was a latent bug — users with a non-default output style were silently
// excluded from cached MC.
function isMainThreadSource(querySource: QuerySource | undefined): boolean {
  return !querySource || querySource.startsWith('repl_main_thread')
}

// Reserve this many tokens for output during compaction
// Based on p99.99 of compact summary output being 17,387 tokens.
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000

export function getEffectiveContextWindowSize(model: string): number {
  const reservedTokensForSummary = Math.min(getMaxOutputTokensForModel(model), MAX_OUTPUT_TOKENS_FOR_SUMMARY)
  let contextWindow = getContextWindowForModel(model, getSdkBetas())
  …
  return contextWindow - reservedTokensForSummary
}

export const AUTOCOMPACT_BUFFER_TOKENS = 13_000
export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000
export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000
export const MANUAL_COMPACT_BUFFER_TOKENS = 3_000

export function getAutoCompactThreshold(model: string): number {
  return getEffectiveContextWindowSize(model) - AUTOCOMPACT_BUFFER_TOKENS
}

上下文窗口
  −20000  ← 给摘要输出留的空间（p99.99 是 17387 token）
= 有效窗口
  −13000  ← autocompact 触发线
  −20000  ← 警告线 / 错误线
  −3000   ← blocking limit（关掉自动压缩时的硬墙，留空间给手动 /compact）

// Recursion guards. session_memory and compact are forked agents that would deadlock.
if (querySource === 'session_memory' || querySource === 'compact') return false

// marble_origami is the ctx-agent — if ITS context blows up and
// autocompact fires, runPostCompactCleanup calls resetContextCollapse()
// which destroys the MAIN thread's committed log (module-level state
// shared across forks).
if (feature('CONTEXT_COLLAPSE')) { if (querySource === 'marble_origami') return false }

if (!isAutoCompactEnabled()) return false

// Reactive-only mode: suppress proactive autocompact, let reactive compact
// catch the API's prompt-too-long.
if (feature('REACTIVE_COMPACT')) {
  if (getFeatureValue_CACHED_MAY_BE_STALE('tengu_cobalt_raccoon', false)) return false
}

// Stop trying autocompact after this many consecutive failures.
// BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272)
// in a single session, wasting ~250K API calls/day globally.
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

// Without this, sessions where context is irrecoverably over the limit
// hammer the API with doomed compaction attempts on every turn.
if (tracking?.consecutiveFailures !== undefined
    && tracking.consecutiveFailures >= MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES) {
  return { wasCompacted: false }
}

if (nextFailures >= MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES) {
  logForDebugging(
    `autocompact: circuit breaker tripped after ${nextFailures} consecutive failures — skipping future attempts this session`,
    { level: 'warn' },
  )
}

// CC-1180: compact request itself hit prompt-too-long. Truncate the
// oldest API-round groups and retry rather than leaving the user stuck.

// groupMessagesByApiRound puts the preamble in group 0 and starts every
// subsequent group with an assistant message. Dropping group 0 leaves an
// assistant-first sequence which the API rejects (first message must be
// role=user). Prepend a synthetic user marker — ensureToolResultPairing
// already handles any orphaned tool_results this creates.

// Strip our own synthetic marker from a previous retry before grouping.
// Otherwise it becomes its own group 0 and the 20% fallback stalls
// (drops only the marker, re-adds it, zero progress on retry 2+).

// 3P default: true — forked-agent path reuses main conversation's prompt cache.
// Experiment (Jan 2026) confirmed: false path is 98% cache miss, costs ~0.76% of
// fleet cache_creation (~38B tok/day), concentrated in ephemeral envs (CCR/GHA/SDK)
// with cold GB cache and 3P providers where GB is disabled. GB gate kept as kill-switch.

// Compaction ate prior delta attachments. Re-announce from the current
// state so the model has tool/instruction context on the first
// post-compact turn. Empty message history → diff against nothing →
// announces the full set.

// Intentionally NOT resetting sentSkillNames: re-injecting the full
// skill_listing (~4K tokens) post-compact is pure cache_creation with
// marginal benefit. The model still has SkillTool in its schema and
// invoked_skills attachment (below) preserves used-skill content.

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
`

// Aggressive no-tools preamble. The cache-sharing fork path inherits the
// parent's full tool set (required for cache-key match), and on Sonnet 4.6+
// adaptive-thinking models the model sometimes attempts a tool call despite
// the weaker trailer instruction. With maxTurns: 1, a denied tool call means
// no text output → falls through to the streaming fallback (2.79% on 4.6 vs
// 0.01% on 4.5). Putting this FIRST and making it explicit about rejection
// consequences prevents the wasted turn.

const NO_TOOLS_TRAILER =
  '\n\nREMINDER: Do NOT call any tools. Respond with plain text only — ' +
  'an <analysis> block followed by a <summary> block. ' +
  'Tool calls will be rejected and you will fail the task.'

// Two variants: BASE scopes to "the conversation", PARTIAL scopes to "the
// recent messages". The <analysis> block is a drafting scratchpad that
// formatCompactSummary() strips before the summary reaches context.

export function formatCompactSummary(summary: string): string {
  // Strip analysis section — it's a drafting scratchpad that improves summary
  // quality but has no informational value once the summary is written.
  formattedSummary = formattedSummary.replace(/<analysis>[\s\S]*?<\/analysis>/, '')
  …
}

This session is being continued from a previous conversation that ran out of context.
The summary below covers the earlier portion of the conversation.

{摘要}

If you need specific details from before compaction (like exact code snippets, error
messages, or content you generated), read the full transcript at: {transcriptPath}

Recent messages are preserved verbatim.

const compacted = await reactiveCompact.tryReactiveCompact({
  hasAttempted: hasAttemptedReactiveCompact,
  querySource,
  aborted: toolUseContext.abortController.signal.aborted,
  messages: messagesForQuery,
  cacheSafeParams: { systemPrompt, userContext, systemContext, toolUseContext, forkContextMessages: messagesForQuery },
})

reactiveCompact.isWithheldPromptTooLong(message)     // 判断要不要扣住这条错误
reactiveCompact.isWithheldMediaSizeError(message)    // 媒体太大也归它管
reactiveCompact.isReactiveCompactEnabled()

/**
 * Estimate token count for messages by extracting text content
 * Used for rough token estimation when we don't have accurate API counts
 * Pads estimate by 4/3 to be conservative since we're approximating
 */
export function estimateMessageTokens(messages: Message[]): number

// Message-payload estimate of the resulting context. The next iteration's
// shouldAutoCompact will see this PLUS ~20-40K for system prompt + tools +
// userContext (via API usage.input_tokens). So `willRetriggerNextTurn: true`

import { trySessionMemoryCompaction } from './sessionMemoryCompact.js'

cd claude-code-deep-dive/extracted-source

# 1. 五层在主循环里的位置
sed -n '365,470p' src/query.ts

# 2. 完整可见的两层
cat src/services/compact/timeBasedMCConfig.ts
sed -n '29,110p' src/services/compact/autoCompact.ts

# 3. 可压缩工具白名单
sed -n '38,50p' src/services/compact/microCompact.ts

# 4. 断路器与那次事故
grep -n -B4 -A4 'BQ 2026-03-10' src/services/compact/autoCompact.ts
grep -n -A12 'circuit breaker tripped' src/services/compact/autoCompact.ts

# 5. 四层递归守卫
sed -n '159,200p' src/services/compact/autoCompact.ts

# 6. 压缩提示词全文（374 行，值得整读）
cat src/services/compact/prompt.ts

# 7. 验证「四层实现不在快照里」
for m in reactiveCompact snipCompact cachedMicrocompact cachedMCConfig; do
  ls src/services/compact/$m.ts 2>/dev/null || echo "缺失 $m"
done
ls src/services/contextCollapse/ 2>/dev/null || echo "缺失 contextCollapse/"

# 看当前上下文占用与各部分构成
# （在 Claude Code 里敲）
/context

# 手动压缩，观察摘要的九个段落
/compact