compressed-context 0.0.0-stage → 0.1.0

package/src/compression/babel.ts

@@ -0,0 +1,85 @@
+import type { BabelSummary } from "./schema.ts"
+
+/** Babel 首行：`T=标题|G=目标`；允许两侧空格。 */
+const HEADER_RE = /^\s*T\s*=\s*(.*?)\s*\|\s*G\s*=\s*(.*?)\s*$/i
+/** 兼容模型把 T/G 写成两行的情况。 */
+const TITLE_RE = /^\s*T\s*=\s*(.*?)\s*$/i
+const GOAL_RE = /^\s*G\s*=\s*(.*?)\s*$/i
+/** T2/T3 候选行：优先 `c=N`，兼容 `candidate: N`。 */
+const CANDIDATE_RE = /^\s*(?:c|candidate)\s*[:=]\s*(\d+)\s*$/i
+
+/** 输入：候选字符串；输出：第一个非空值，全部为空时返回空串。 */
+function firstNonEmpty(...values: readonly (string | undefined)[]): string {
+  for (const value of values) {
+    const trimmed = value?.trim()
+    if (trimmed !== undefined && trimmed.length > 0) return trimmed
+  }
+  return ""
+}
+
+/** 输入：模型原始文本；输出：去掉代码围栏和首尾空白的文本。 */
+export function cleanBabel(text: string): string {
+  return text
+    .trim()
+    .replace(/^```(?:babel|babeltele|text|md|markdown)?\s*/i, "")
+    .replace(/\s*```$/, "")
+    .trim()
+}
+
+/**
+ * 输入：文本 + 可选显式 title/goal。
+ * 输出：规范 Babel 摘要；缺少标题/目标/正文时返回 undefined。
+ * 预期：首行优先解析 `T=...|G=...`，也接受两行 T/G；text 保留规范化首行。
+ */
+export function toBabelSummary(value: unknown, title?: string, goal?: string): BabelSummary | undefined {
+  if (typeof value !== "string") return undefined
+  const clean = cleanBabel(value)
+  if (clean.length === 0) return undefined
+
+  const lines = clean.split(/\r?\n/)
+  const first = lines[0]?.trim() ?? ""
+  const header = HEADER_RE.exec(first)
+  let parsedTitle = header?.[1]?.trim()
+  let parsedGoal = header?.[2]?.trim()
+  let bodyLines = lines
+
+  if (header !== null) {
+    bodyLines = lines.slice(1)
+  } else {
+    const second = lines[1]?.trim() ?? ""
+    const titleLine = TITLE_RE.exec(first)
+    const goalLine = GOAL_RE.exec(second)
+    if (titleLine !== null && goalLine !== null) {
+      parsedTitle = titleLine[1]?.trim()
+      parsedGoal = goalLine[1]?.trim()
+      bodyLines = lines.slice(2)
+    }
+  }
+
+  const resolvedTitle = firstNonEmpty(title, parsedTitle)
+  const resolvedGoal = firstNonEmpty(goal, parsedGoal)
+  if (resolvedTitle.length === 0 || resolvedGoal.length === 0) return undefined
+
+  // 有首行时正文从首行之后开始；无首行但显式给了 title/goal 时保留整段正文。
+  const body = bodyLines.join("\n").trim()
+  if (body.length === 0) return undefined
+
+  return {
+    format: "babel",
+    title: resolvedTitle,
+    goal: resolvedGoal,
+    text: `T=${resolvedTitle}|G=${resolvedGoal}\n${body}`,
+  }
+}
+
+/** 输入：模型返回的文本；输出：首个非空行是否为 `c=N`，以及去掉该行后的正文。 */
+export function splitBabelCandidate(text: string): { readonly candidate: number; readonly summary: string } | undefined {
+  const clean = cleanBabel(text)
+  const lines = clean.split(/\r?\n/)
+  const first = lines[0]?.trim() ?? ""
+  const match = CANDIDATE_RE.exec(first)
+  if (match === null) return undefined
+  const candidate = Number(match[1])
+  if (!Number.isInteger(candidate)) return undefined
+  return { candidate, summary: lines.slice(1).join("\n").trim() }
+}

package/src/compression/block.ts

@@ -0,0 +1,25 @@
+import type { Summary } from "./schema.ts"
+import { summaryChars } from "./summary.ts"
+import { nextBlockId, nextOrder, type Block } from "./state.ts"
+
+/** 输入：已有块 + 摘要 + 覆盖范围 + 原文字符数；输出：新的 T1 块。 */
+export function createT1Block(input: {
+  readonly blocks: readonly Block[]
+  readonly summary: Summary
+  readonly fromId: string
+  readonly toId: string
+  readonly sourceChars: number
+  readonly at?: number
+}): Block {
+  return {
+    id: nextBlockId(input.blocks),
+    tier: 1,
+    summary: input.summary,
+    fromId: input.fromId,
+    toId: input.toId,
+    tokensBefore: Math.ceil(input.sourceChars / 4),
+    tokensAfter: Math.ceil(summaryChars(input.summary) / 4),
+    at: input.at ?? Date.now(),
+    order: nextOrder(input.blocks),
+  }
+}

package/src/compression/cache-history.ts

@@ -0,0 +1,75 @@
+import type { Plugin } from "@opencode/plugin"
+import type { Schema } from "effect"
+
+import {
+  appendCacheSampleFromStep,
+  appendCacheSamples,
+  cacheHistoryEquals,
+  cacheHistoryKey,
+  parseCacheHistory,
+  type CacheHistory,
+  type CacheSample,
+} from "../shared/cache.ts"
+import type { StorageLike } from "./state.ts"
+
+/** 输入：storage + sessionID；输出：该会话的历史；缺失或损坏时为空历史。 */
+export async function loadCacheHistory(storage: StorageLike, sessionID: string): Promise<CacheHistory> {
+  return parseCacheHistory(await storage.get(cacheHistoryKey(sessionID)))
+}
+
+/** 输入：storage + sessionID + 样本；输出：无；预期：写入 JSON，最多 10 条。 */
+export async function saveCacheHistory(
+  storage: StorageLike,
+  sessionID: string,
+  samples: readonly CacheSample[],
+): Promise<void> {
+  await storage.set(cacheHistoryKey(sessionID), { v: 1, samples } as unknown as Schema.Json)
+}
+
+/**
+ * 输入：插件上下文 + sessionID + 单 step 的 assistant usage。
+ * 输出：无。
+ * 预期：tool loop 的后续 step 不触发 context/usage.updated 的完整读取，
+ *       用 `session.step.ended` 事件里的 tokens 直接落一条缓存样本。
+ */
+export async function recordCacheHistoryStep(
+  ctx: Plugin.Context,
+  sessionID: string,
+  input: {
+    readonly messageID: string
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+  },
+): Promise<void> {
+  try {
+    const history = await loadCacheHistory(ctx.storage, sessionID)
+    const samples = appendCacheSampleFromStep(history.samples, input.messageID, input.tokens)
+    if (!cacheHistoryEquals(history.samples, samples)) {
+      await saveCacheHistory(ctx.storage, sessionID, samples)
+    }
+  } catch {
+    // best effort：历史缺失不影响主流程
+  }
+}
+
+/**
+ * 输入：插件上下文 + sessionID。
+ * 输出：无；预期：把当前上下文里未记录过的 assistant usage 追加进该会话的历史。
+ *       失败只影响历史，不影响压缩与主流程。
+ */
+export async function recordCacheHistory(ctx: Plugin.Context, sessionID: string): Promise<void> {
+  try {
+    const messages = await ctx.session.context({ sessionID })
+    const history = await loadCacheHistory(ctx.storage, sessionID)
+    const samples = appendCacheSamples(history.samples, messages)
+    if (!cacheHistoryEquals(history.samples, samples)) {
+      await saveCacheHistory(ctx.storage, sessionID, samples)
+    }
+  } catch {
+    // best effort：历史缺失不影响主界面
+  }
+}

package/src/compression/compaction.ts

@@ -0,0 +1,189 @@
+import type { Plugin } from "@opencode/plugin"
+
+import { resolveSummaryLimits } from "../shared/settings.ts"
+import { mergeTerminalMetadata } from "../shared/stats.ts"
+import { renderActiveSummary } from "./active-summary-cache.ts"
+import { markCompactionInFlight, resolveLimit } from "./auto.ts"
+import { createT1Block } from "./block.ts"
+import { distillOnce, isTerminal, planT1Phase } from "./distill.ts"
+import { TERMINAL_MESSAGE } from "./events.ts"
+import { activeBlocks } from "./render.ts"
+import { messageRange, olderMessages, textChars, type MessageLike } from "./select.ts"
+import { loadServerSettings } from "./settings.ts"
+import { loadState, saveState, type Block, type CompactionPhase, type State } from "./state.ts"
+import { buildT1Instruction, sessionGenerator, summarizeInstruction } from "./summarize.ts"
+import type { ModelRefLike } from "./summarize.ts"
+import { buildTranscript } from "./transcript.ts"
+import { saveTranscript } from "./transcript-store.ts"
+import { MIN_SOURCE_CHARS, validateSummary } from "./validate.ts"
+
+/** compaction 钩子需要的最小事件形状。 */
+export interface CompactionEvent {
+  readonly sessionID: string
+  readonly messages: readonly MessageLike[]
+  readonly model: ModelRefLike
+  result?: { summary: string }
+}
+
+/**
+ * 输入：插件上下文 + compaction 事件。
+ * 输出：无；预期：T1 生成摘要或 T2/T3 合并块，把结果写回 event.result。
+ *       终止时记录 terminal；异常写入 lastError 后重新抛出，交给失败事件。
+ */
+export async function handleCompaction(ctx: Plugin.Context, event: CompactionEvent): Promise<void> {
+  markCompactionInFlight(event.sessionID, true)
+  try {
+    const state = await loadState(ctx.storage, event.sessionID)
+    if (state.terminal !== undefined) throw new Error(state.terminal)
+    const settings = await loadServerSettings(ctx.storage)
+    // auto 窗口在运行时解析后钳制摘要上限；数字窗口已在保存时校验，这里统一再钳一次。
+    const windowTokens = await resolveLimit(ctx, event.model, settings.contextLimit)
+    const limits = resolveSummaryLimits(settings, windowTokens)
+    const renderOptions = {
+      showTimeline: settings.showTimeline,
+      showBlockTokens: settings.showBlockTokens,
+    }
+
+    /** 保存这一层的结果；pending 可选，phase 由下一层决定。 */
+    const save = async (
+      blocks: readonly Block[],
+      pending: Block | undefined,
+      phase: CompactionPhase | undefined,
+      error: string | undefined,
+    ): Promise<void> => {
+      const base: State = {
+        blocks,
+        attempts: state.attempts,
+        ...(state.lastError === undefined ? {} : { lastError: state.lastError }),
+        ...(phase === undefined ? {} : { phase }),
+      }
+      const next: State = pending === undefined ? base : { ...base, pending }
+      await saveState(
+        ctx.storage,
+        event.sessionID,
+        error === undefined ? next : { ...next, lastError: error },
+      )
+    }
+
+    // 第二阶段：T2/T3。older 里没有真实消息，或新消息不足以单独做 T1 时合并块。
+    // 短消息仍由 OpenCode 原样保留在 recent 里，不会丢内容。
+    // 有足够新内容时走下面的 T1：先总结新内容，phase 留到下一次压缩再合并。
+    const older = olderMessages(event.messages)
+    const olderChars = textChars(older)
+    if (state.phase !== undefined && (older.length === 0 || olderChars < MIN_SOURCE_CHARS)) {
+      const result = await distillOnce({
+        ctx,
+        sessionID: event.sessionID,
+        state,
+        pending: state.pending,
+        budgetTokens: limits.budgetTokens,
+        summaryBlockChars: limits.blockChars,
+        summaryTotalChars: limits.totalChars,
+        summaryLanguage: settings.summaryLanguage,
+        summaryFormat: settings.summaryFormat,
+        phase: state.phase,
+        showTimeline: settings.showTimeline,
+        showBlockTokens: settings.showBlockTokens,
+      })
+      await save(result.blocks, result.pending, result.nextPhase, result.error)
+      event.result = { summary: result.summary }
+      // 摘要链仍超预算且没有合法候选：无法再压，记录终止原因并停止自动压缩。
+      if (
+        isTerminal(
+          result,
+          activeBlocks(result.blocks, result.pending),
+          limits.budgetTokens,
+          limits.totalChars,
+        )
+      ) {
+        await saveState(ctx.storage, event.sessionID, {
+          blocks: result.blocks,
+          attempts: 0,
+          lastError: TERMINAL_MESSAGE,
+          terminal: TERMINAL_MESSAGE,
+        })
+        // 让 TUI 面板能显示终止原因；写失败不影响压缩状态。
+        try {
+          const session = await ctx.session.get({ sessionID: event.sessionID })
+          await ctx.session.update({
+            sessionID: event.sessionID,
+            metadata: mergeTerminalMetadata(session.metadata, TERMINAL_MESSAGE),
+          })
+        } catch {
+          // best effort
+        }
+      }
+      return
+    }
+
+    // 第一阶段：T1。已有 pending（compress 工具）就直接用；
+    // 否则用 session 前缀 + 尾部指令生成，保持前缀缓存。
+    let pending = state.pending
+    if (pending === undefined) {
+      const eligible = older
+      const transcript = buildTranscript(eligible)
+      const sourceChars = transcript.length
+      if (eligible.length === 0 || sourceChars < MIN_SOURCE_CHARS) {
+        throw new Error("nothing to compress")
+      }
+      let failure = "unknown"
+      const summary = await summarizeInstruction({
+        prompt: buildT1Instruction({
+          maxChars: limits.blockChars,
+          totalChars: limits.totalChars,
+          language: settings.summaryLanguage,
+          format: settings.summaryFormat,
+        }),
+        sourceChars,
+        maxChars: limits.blockChars,
+        generate: sessionGenerator(ctx.session, event.sessionID),
+        format: settings.summaryFormat,
+        onFailure: (reason) => {
+          failure = reason
+        },
+      })
+      if (summary === undefined) throw new Error(`compression failed: ${failure}`)
+      const validation = validateSummary(summary, sourceChars, undefined, limits.blockChars)
+      if (!validation.ok) throw new Error(validation.message)
+
+      const range = messageRange(eligible)
+      if (range === undefined) throw new Error("messages are missing ids")
+
+      pending = createT1Block({
+        blocks: state.blocks,
+        summary,
+        fromId: range.fromId,
+        toId: range.toId,
+        sourceChars,
+      })
+
+      // 原文与摘要同生命周期；写盘失败时摘要仍然可用，解压降级为占位符。
+      try {
+        await saveTranscript(ctx.storage, event.sessionID, pending, eligible)
+      } catch {
+        // best effort
+      }
+    }
+
+    // T1 之后再检查预算；没超就不排 T2。
+    const active = activeBlocks(state.blocks, pending)
+    const summary = renderActiveSummary(
+      event.sessionID,
+      { ...state, pending },
+      renderOptions,
+    )
+    const nextPhase = planT1Phase(summary, active, limits.budgetTokens, limits.totalChars)
+    await save(state.blocks, pending, nextPhase, undefined)
+    event.result = { summary }
+  } catch (error) {
+    // 把钩子里的真实异常留给失败事件和 TUI；不要只留下“compaction failed”。
+    const current = await loadState(ctx.storage, event.sessionID)
+    await saveState(ctx.storage, event.sessionID, {
+      ...current,
+      lastError: error instanceof Error ? (error.stack ?? error.message) : String(error),
+    })
+    throw error
+  } finally {
+    markCompactionInFlight(event.sessionID, false)
+  }
+}

package/src/compression/decompress-tool.ts

@@ -0,0 +1,74 @@
+import type { Plugin } from "@opencode/plugin"
+import { Schema } from "effect"
+
+import { effectiveDecompressInlineMax, effectiveDecompressTempCap } from "../shared/settings.ts"
+import { loadServerSettings } from "./settings.ts"
+import type { Disposable } from "./settings-rpc.ts"
+
+const DESCRIPTION =
+  "Restores content from a compressed checkpoint block. Use when you need exact details that were " +
+  "compressed away (exact errors, code lines, file contents, tool outputs). Pass the block id you see " +
+  "in the checkpoint (e.g. b3). By default a merged block expands one level (its child summaries); " +
+  "pass full:true to recurse all the way to the original messages. Large content is written to a " +
+  "temporary file whose path is returned — open it with the read tool. This tool never changes the " +
+  "checkpoint; content returns only as this tool's result."
+
+const DecompressInput = Schema.Struct({
+  block: Schema.String,
+  full: Schema.Boolean,
+})
+
+const DecompressOutput = Schema.Struct({
+  inline: Schema.optional(Schema.String),
+  path: Schema.optional(Schema.String),
+  tokens: Schema.optional(Schema.Number),
+})
+
+/**
+ * 输入：服务端插件上下文。
+ * 输出：注册 decompress 工具，返回注销句柄。
+ * 预期：只读操作——不修改块状态；内容作为 tool result 返回。
+ */
+export async function registerDecompressTool(ctx: Plugin.Context): Promise<Disposable> {
+  const registration = await ctx.tool.transform((tools) => {
+    tools.add({
+      name: "decompress",
+      options: { codemode: false },
+      description: DESCRIPTION,
+      input: DecompressInput,
+      output: DecompressOutput,
+      execute: async (input, toolCtx) => {
+        const { resolveDecompress } = await import("./decompress.ts")
+        const settings = await loadServerSettings(ctx.storage)
+        if (!settings.enableDecompressTool) {
+          return {
+            output: {},
+            content: "ERROR: decompress tool is disabled in settings",
+            metadata: { error: true },
+          }
+        }
+        const result = await resolveDecompress(input, ctx, toolCtx.sessionID, {
+          inlineMax: effectiveDecompressInlineMax(settings),
+          tempCap: effectiveDecompressTempCap(settings),
+          showTokens: settings.decompressShowTokens,
+        })
+        if (result.status === "error") {
+          return {
+            output: {},
+            content: `ERROR: ${result.message}`,
+            metadata: { error: true },
+          }
+        }
+        const output: { inline?: string; path?: string; tokens?: number } = {
+          ...(result.path === undefined ? {} : { path: result.path }),
+          ...(result.tokens === undefined ? {} : { tokens: result.tokens }),
+        }
+        return {
+          output,
+          content: result.inline,
+        }
+      },
+    })
+  })
+  return registration
+}