compressed-context 0.0.0-stage → 0.1.0

package/src/compression/events.ts

@@ -0,0 +1,275 @@
+import type { Plugin } from "@opencode/plugin"
+
+import { cacheHistoryKey } from "../shared/cache.ts"
+import { forEachScannedEntry } from "../shared/scan.ts"
+import { clearActiveSummary } from "./active-summary-cache.ts"
+import { recordCacheHistory } from "./cache-history.ts"
+import { deleteSessionTempFiles } from "./decompress.ts"
+import { markSessionDeleted } from "./deleted-sessions.ts"
+import { blockMarker } from "./render.ts"
+import { deleteTranscriptsForSession } from "./transcript-store.ts"
+import {
+  STATE_PREFIX,
+  commitPending,
+  dropPending,
+  loadState,
+  parseState,
+  retryPending,
+  saveState,
+  stateKey,
+  type State,
+} from "./state.ts"
+
+/** 输入：服务端上下文 + sessionID + 块 id；输出：最新 compaction 是否包含该块。 */
+export async function hasBlockInLatestCompaction(
+  ctx: Plugin.Context,
+  sessionID: string,
+  blockId: string,
+): Promise<boolean> {
+  try {
+    const messages = await ctx.session.context({ sessionID })
+    const latest = messages.find((message) => message.type === "compaction" && message.status === "completed")
+    if (latest === undefined) return false
+    return latest.summary.includes(blockMarker(blockId))
+  } catch {
+    return false
+  }
+}
+
+/** 输入：状态；输出：pending 对账后的状态。 */
+async function reconcile(ctx: Plugin.Context, sessionID: string, state: State): Promise<State> {
+  if (!state.pending) return state
+  const found = await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)
+  return found ? commitPending(state) : dropPending(state, "pending compaction not found after restart")
+}
+
+export type CompactionEventType = "ended" | "failed"
+
+/** 摘要链仍超预算且没有任何合法合并候选时的终止提示。 */
+export const TERMINAL_MESSAGE =
+  "compression cannot reduce this context further: start a new session or use native compaction"
+
+/**
+ * 输入：服务端上下文 + 事件类型 + sessionID + 事件自带错误（仅 failed 有）。
+ * 输出：无。
+ * 预期：只有最新 checkpoint 包含 pending marker 才转正；失败时保留 phase 让下一次请求重试，
+ *       达到 MAX_COMPRESSION_ATTEMPTS 后清除 phase，记录真实原因。
+ *       事件 error 优先于 state.lastError——钩子没跑过的失败（如 OpenCode 在钩子前判定
+ *       「无可压缩内容」）state 里没有任何错误记录，只能从事件拿真实原因。
+ */
+export async function handleCompactionEvent(
+  ctx: Plugin.Context,
+  type: CompactionEventType,
+  sessionID: string,
+  eventError?: string,
+): Promise<void> {
+  const state = await loadState(ctx.storage, sessionID)
+  if (type === "ended") {
+    if (!state.pending) {
+      await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
+      return
+    }
+    // 事件可能晚到：只有最新 checkpoint 确实包含这个 pending 才转正，
+    // 否则它属于下一层 compaction，留给下一次 ended。
+    if (await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)) {
+      await saveState(ctx.storage, sessionID, commitPending(state))
+    }
+    return
+  }
+
+  const detail = eventError ?? state.lastError ?? "compaction failed"
+  // 钩子从未运行的失败（state 里没有任何本层错误记录）且已排下一层 phase：
+  // 典型是历史里只剩 checkpoint，OpenCode 在钩子前就判定无可压缩内容。
+  // 这不是本层失败，保留 phase 等下一次带真实消息的压缩，不计 attempts。
+  if (eventError !== undefined && state.lastError === undefined && state.phase !== undefined) {
+    await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
+    return
+  }
+  // 本层失败：保留 phase，下一次请求由 auto 重新入队；达到上限后 retryPending 会清掉 phase。
+  if (state.phase !== undefined) {
+    await saveState(ctx.storage, sessionID, retryPending(state, detail))
+    return
+  }
+  // T1 没有下一层可重试：丢弃 pending，记录真实原因。
+  await saveState(ctx.storage, sessionID, dropPending(state, detail))
+}
+
+export interface SessionEventOptions {
+  readonly onSessionIdle?: (sessionID: string) => void
+  readonly onSessionDeleted?: (sessionID: string) => void
+  readonly onStepEnded?: (input: {
+    readonly sessionID: string
+    readonly messageID: string
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+  }) => void | Promise<void>
+}
+
+/**
+ * 输入：插件上下文 + sessionID。
+ * 输出：无。
+ * 预期：先打墓碑阻止迟到写入，再删 state、cache history、transcript 与临时文件。
+ */
+export async function forgetSession(ctx: Plugin.Context, sessionID: string): Promise<void> {
+  markSessionDeleted(sessionID)
+  clearActiveSummary(sessionID)
+  deleteSessionTempFiles(sessionID)
+  try {
+    await Promise.all([
+      ctx.storage.remove(stateKey(sessionID)),
+      ctx.storage.remove(cacheHistoryKey(sessionID)),
+      deleteTranscriptsForSession(ctx.storage, sessionID),
+    ])
+  } catch {
+    // best effort：删不掉也不影响当前进程
+  }
+}
+
+/** 输入：事件里未校验的 tokens 字段；输出：规范化后的 usage，形状不对时 undefined。 */
+function readStepTokens(raw: unknown): {
+  input: number
+  output: number
+  reasoning: number
+  cache: { read: number; write: number }
+} | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  const input = record["input"]
+  if (typeof input !== "number" || !Number.isFinite(input)) return undefined
+  const finite = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0)
+  const cache =
+    typeof record["cache"] === "object" && record["cache"] !== null
+      ? (record["cache"] as Record<string, unknown>)
+      : {}
+  return {
+    input,
+    output: finite(record["output"]),
+    reasoning: finite(record["reasoning"]),
+    cache: { read: finite(cache["read"]), write: finite(cache["write"]) },
+  }
+}
+
+/**
+ * 输入：插件上下文 + 可选清理回调。
+ * 输出：订阅会话事件并返回取消函数。
+ * 预期：compaction 成功/失败对账 pending；usage.updated/idle 补写缓存历史；
+ *       idle 清理内存；deleted 清理内存与 storage。
+ */
+export function startSessionEvents(
+  ctx: Plugin.Context,
+  options: SessionEventOptions = {},
+): () => void {
+  const controller = new AbortController()
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        switch (event.type) {
+          case "session.step.ended": {
+            const data = event.data as {
+              sessionID: string
+              assistantMessageID?: string
+              tokens?: unknown
+            }
+            const tokens = readStepTokens(data.tokens)
+            if (tokens !== undefined && options.onStepEnded !== undefined) {
+              await options.onStepEnded({
+                sessionID: data.sessionID,
+                messageID: data.assistantMessageID ?? "",
+                tokens,
+              })
+            }
+            break
+          }
+          case "session.compaction.ended":
+          case "session.compaction.failed": {
+            const type: CompactionEventType =
+              event.type === "session.compaction.ended" ? "ended" : "failed"
+            const failure =
+              event.type === "session.compaction.failed"
+                ? ((event.data as { error?: { message?: string } }).error?.message ?? "compaction failed")
+                : undefined
+            await handleCompactionEvent(ctx, type, event.data.sessionID, failure)
+            break
+          }
+          case "session.usage.updated":
+          case "session.idle":
+            // session.idle 在新版本里已标记 deprecated，usage.updated 每个 step 都会发；
+            // 两个都接，谁先到都能补写（按 messageID 去重）。
+            await recordCacheHistory(ctx, event.data.sessionID)
+            if (event.type === "session.idle") options.onSessionIdle?.(event.data.sessionID)
+            break
+          case "session.deleted":
+            await forgetSession(ctx, event.data.sessionID)
+            options.onSessionDeleted?.(event.data.sessionID)
+            break
+        }
+      }
+    } catch {
+      // aborted or disconnected；下一次事件或启动对账会补上
+    }
+  })()
+  return () => {
+    controller.abort()
+  }
+}
+
+/** 输入：任意错误；输出：是否明确的“会话不存在”。 */
+function isSessionMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) {
+    return /not found|404/i.test(String(error))
+  }
+  const record = error as Record<string, unknown>
+  const status = record["status"] ?? record["statusCode"] ?? record["code"]
+  if (status === 404 || status === "404" || status === "not_found") return true
+  const message = typeof record["message"] === "string" ? record["message"] : ""
+  return /not found|404/i.test(message)
+}
+
+/**
+ * 输入：服务端上下文 + 每个 state 条目的处理函数。
+ * 输出：无。
+ * 预期：按 100 条一页顺序遍历所有 state key；空 sessionID 跳过，处理函数串行 await。
+ */
+async function forEachStateEntry(
+  ctx: Plugin.Context,
+  visit: (sessionID: string, value: unknown) => Promise<void>,
+): Promise<void> {
+  await forEachScannedEntry(ctx.storage, STATE_PREFIX, async (entry) => {
+    const sessionID = entry.key.slice(STATE_PREFIX.length)
+    if (sessionID.length === 0) return
+    await visit(sessionID, entry.value)
+  })
+}
+
+/**
+ * 输入：服务端上下文。
+ * 输出：无。
+ * 预期：启动时只清理“明确不存在”会话的孤儿 state；瞬时错误不删数据。
+ */
+async function cleanupOrphanStates(ctx: Plugin.Context): Promise<void> {
+  await forEachStateEntry(ctx, async (sessionID) => {
+    try {
+      await ctx.session.get({ sessionID })
+    } catch (error) {
+      if (isSessionMissing(error)) await forgetSession(ctx, sessionID)
+    }
+  })
+}
+
+/** 输入：服务端上下文；输出：无；预期：启动时对账所有 pending 状态并清理孤儿。 */
+export async function reconcileAll(ctx: Plugin.Context): Promise<void> {
+  try {
+    await cleanupOrphanStates(ctx)
+    await forEachStateEntry(ctx, async (sessionID, value) => {
+      const state = parseState(value)
+      if (!state.pending) return
+      await saveState(ctx.storage, sessionID, await reconcile(ctx, sessionID, state))
+    })
+  } catch {
+    // best effort
+  }
+}

package/src/compression/markdown.ts

@@ -0,0 +1,53 @@
+import type { MarkdownSummary } from "./schema.ts"
+
+const HEADING_RE = /^#{1,6}\s+(.+)$/m
+const BULLET_RE = /^[\u2022\-*]\s+/
+
+/** 输入：文本 + 上限；输出：截断后的文本。 */
+function clamp(text: string, max: number): string {
+  return text.length <= max ? text : text.slice(0, max).trimEnd()
+}
+
+/**
+ * 输入：Markdown 正文。
+ * 输出：块标题；预期：第一个标题 > 第一个非空行 > untitled，去 bullet，最多 60 字符。
+ */
+export function deriveMarkdownTitle(text: string): string {
+  const heading = HEADING_RE.exec(text)
+  const source = heading !== null ? heading[1] ?? "" : (text.split("\n").find((line) => line.trim().length > 0) ?? "")
+  const cleaned = source.trim().replace(BULLET_RE, "")
+  return cleaned.length === 0 ? "untitled" : clamp(cleaned, 60)
+}
+
+/**
+ * 输入：Markdown 正文。
+ * 输出：用于候选描述的短目标；预期：标题后的第一个非空非标题行，最多 160 字符。
+ */
+export function markdownGoal(text: string): string {
+  const lines = text.split("\n").map((line) => line.trim())
+  const headingIndex = lines.findIndex((line) => HEADING_RE.test(line))
+  const start = headingIndex >= 0 ? headingIndex + 1 : 0
+  const first = lines.slice(start).find((line) => line.length > 0 && !HEADING_RE.test(line))
+  const cleaned = (first ?? deriveMarkdownTitle(text)).replace(BULLET_RE, "")
+  return clamp(cleaned, 160)
+}
+
+/** 输入：文本；输出：去掉 markdown 代码围栏后的正文。 */
+function cleanMarkdown(text: string): string {
+  return text
+    .trim()
+    .replace(/^```(?:markdown|md)?\s*/i, "")
+    .replace(/\s*```$/, "")
+    .trim()
+}
+
+/** 输入：Markdown 正文 + 可选标题；输出：规范 Markdown 摘要。 */
+export function toMarkdownSummary(text: string, title?: string): MarkdownSummary {
+  const body = cleanMarkdown(text)
+  const explicit = title?.trim() ?? ""
+  return {
+    format: "markdown",
+    title: explicit.length > 0 ? clamp(explicit, 80) : deriveMarkdownTitle(body),
+    text: body,
+  }
+}

package/src/compression/normalize.ts

@@ -0,0 +1,114 @@
+import { Schema } from "effect"
+
+import type { SummaryFormat } from "../shared/settings.ts"
+import { toBabelSummary } from "./babel.ts"
+import { toMarkdownSummary } from "./markdown.ts"
+import { SummaryFields, type Summary } from "./schema.ts"
+
+/** 输入：任意模型字段；输出：字符串数组；预期：字符串包成单元素数组，其他丢弃。 */
+export function stringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+  }
+  if (typeof value === "string" && value.trim().length > 0) return [value]
+  return []
+}
+
+/**
+ * 输入：模型返回的原始 JSON 对象。
+ * 输出：补齐缺失可选字段后的对象。
+ * 预期：真实模型常漏 progress/files 或把数组写成字符串；只补空值，不编造内容。
+ */
+export function normalizeSummary(value: unknown): unknown {
+  if (typeof value !== "object" || value === null) return value
+  const record = value as Record<string, unknown>
+  const goal = typeof record["goal"] === "string" ? record["goal"] : ""
+  const title = (
+    typeof record["title"] === "string" && record["title"].trim().length > 0
+      ? record["title"]
+      : goal.trim() || "untitled"
+  ).slice(0, 80)
+  const progress =
+    typeof record["progress"] === "object" && record["progress"] !== null
+      ? (record["progress"] as Record<string, unknown>)
+      : {}
+  return {
+    ...record,
+    title,
+    goal,
+    constraints: stringArray(record["constraints"]),
+    decisions: stringArray(record["decisions"]),
+    progress: {
+      completed: stringArray(progress["completed"]),
+      active: stringArray(progress["active"]),
+      blocked: stringArray(progress["blocked"]),
+    },
+    open_items: stringArray(record["open_items"]),
+    files: stringArray(record["files"]),
+    facts: stringArray(record["facts"]),
+  }
+}
+
+/** 输入：模型返回的 Markdown 载体；输出：正文；预期：支持 string / markdown / text / summary。 */
+function markdownText(value: unknown): string | undefined {
+  if (typeof value === "string") return value
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ["markdown", "text", "summary", "content"]) {
+    const text = record[key]
+    if (typeof text === "string") return text
+  }
+  return undefined
+}
+
+/** 输入：模型返回的 Markdown 载体；输出：可选标题。 */
+function markdownTitle(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  const title = record["title"] ?? record["topic"]
+  return typeof title === "string" ? title : undefined
+}
+
+/** 输入：Babel 载体；输出：正文文本和可选 title/goal。 */
+function babelParts(
+  value: unknown,
+): { readonly text: string; readonly title?: string; readonly goal?: string } | undefined {
+  if (typeof value === "string") return { text: value }
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ["babel", "markdown", "text", "summary", "content"]) {
+    const text = record[key]
+    if (typeof text !== "string") continue
+    const title = typeof record["title"] === "string" ? record["title"] : undefined
+    const goal = typeof record["goal"] === "string" ? record["goal"] : undefined
+    return {
+      text,
+      ...(title === undefined ? {} : { title }),
+      ...(goal === undefined ? {} : { goal }),
+    }
+  }
+  return undefined
+}
+
+/**
+ * 输入：模型返回的原始值 + 摘要格式。
+ * 输出：规范摘要；形状不合法时返回 undefined。
+ * 预期：Markdown 直接保留原文；JSON 先补齐可选字段再由 SummaryFields 解码。
+ */
+export function toSummary(value: unknown, format: SummaryFormat = "markdown"): Summary | undefined {
+  if (format === "babel") {
+    const parts = babelParts(value)
+    if (parts === undefined) return undefined
+    return toBabelSummary(parts.text, parts.title, parts.goal)
+  }
+  if (format === "markdown") {
+    const text = markdownText(value)
+    if (text !== undefined) return toMarkdownSummary(text, markdownTitle(value))
+    // Markdown 模式下仍收到 JSON 字段时回退到结构化解析，避免工具调用直接失败。
+  }
+  try {
+    return Schema.decodeUnknownSync(SummaryFields)(normalizeSummary(value))
+  } catch {
+    return undefined
+  }
+}

package/src/compression/render.ts

@@ -0,0 +1,70 @@
+import type { Block } from "./state.ts"
+import type { Summary } from "./schema.ts"
+import { summaryBody, summaryTitle } from "./summary.ts"
+import { formatTimestamp } from "../shared/format.ts"
+import { countText } from "../shared/tokens.ts"
+
+/** 输入：块 id；输出：块头标记；预期：用于渲染和对账。 */
+export function blockMarker(id: string): string {
+  return `[Compressed conversation section #${id}]`
+}
+
+/** 块头附加信息开关；默认都不显示，避免多占 token。 */
+export interface RenderOptions {
+  readonly showTimeline?: boolean
+  readonly showBlockTokens?: boolean
+}
+
+/** 输入：结构化字段；输出：Markdown 摘要正文。 */
+export function renderSummary(summary: Summary): string {
+  return summaryBody(summary)
+}
+
+/**
+ * 输入：一个块 + 可选渲染开关。
+ * 输出：带块头、层级/合并关系、可选时间与 token 估算的完整文本。
+ * 预期：marker 前缀保持原样，对账逻辑只依赖 `blockMarker(id)`。
+ */
+export function renderBlock(block: Block, options: RenderOptions = {}): string {
+  const body = renderSummary(block.summary)
+  const meta: string[] = [`T${block.tier.toString()}`]
+  if (block.sourceBlockIds !== undefined && block.sourceBlockIds.length > 0) {
+    meta.push(`merged ${block.sourceBlockIds.map((id) => `#${id}`).join(" + ")}`)
+  }
+  if (options.showBlockTokens === true) {
+    meta.push(`≈${countText(body).toString()} tok`)
+  }
+  if (options.showTimeline === true) {
+    meta.push(formatTimestamp(block.at))
+  }
+  const title = summaryTitle(block.summary).trim()
+  const header = `${blockMarker(block.id)} [${meta.join(" · ")}]${title ? ` ${title}` : ""}`
+  return `${header}\n\n${body}`
+}
+
+/**
+ * 输入：已落盘块 + 可选 pending 块 + 渲染开关。
+ * 输出：active 顶层块，按 order 排序。
+ * 预期：被任何块 sourceBlockIds 引用的块不显示；合并块占据第一个源块的位置。
+ */
+export function activeBlocks(blocks: readonly Block[], pending?: Block): readonly Block[] {
+  const all = pending === undefined ? blocks : [...blocks, pending]
+  const consumed = new Set<string>()
+  for (const block of all) {
+    for (const sourceId of block.sourceBlockIds ?? []) consumed.add(sourceId)
+  }
+  return all
+    .filter((block) => !consumed.has(block.id))
+    .sort((a, b) => a.order - b.order || a.at - b.at || a.id.localeCompare(b.id))
+}
+
+/** 输入：块 + 可选 pending + 渲染开关；输出：拼接后的 checkpoint 文本。 */
+export function renderAll(
+  blocks: readonly Block[],
+  pending?: Block,
+  options: RenderOptions = {},
+): string {
+  return activeBlocks(blocks, pending)
+    .map((block) => renderBlock(block, options))
+    .join("\n\n")
+}

package/src/compression/schema.ts

@@ -0,0 +1,84 @@
+import { Schema } from "effect"
+
+/**
+ * 摘要的规范 JSON 形状：写入存储、渲染、校验都用这一份，所有字段必填。
+ *
+ * 模型侧输入用 SummaryInput：JSON 模式只要求 goal，Markdown 模式要求 markdown；
+ * 进入内部前由 normalize 补齐，避免逼模型编造内容。
+ */
+export const SummaryFields = Schema.Struct({
+  title: Schema.String,
+  goal: Schema.String,
+  constraints: Schema.Array(Schema.String),
+  decisions: Schema.Array(Schema.String),
+  progress: Schema.Struct({
+    completed: Schema.Array(Schema.String),
+    active: Schema.Array(Schema.String),
+    blocked: Schema.Array(Schema.String),
+  }),
+  open_items: Schema.Array(Schema.String),
+  files: Schema.Array(Schema.String),
+  facts: Schema.Array(Schema.String),
+})
+
+export type SummaryFields = Schema.Schema.Type<typeof SummaryFields>
+
+/** Markdown 摘要：正文是唯一权威内容，title 只是派生元数据。 */
+export interface MarkdownSummary {
+  readonly format: "markdown"
+  readonly title: string
+  readonly text: string
+}
+
+/**
+ * Babel 摘要：正文是模型间高密度文本，title/goal 从首行 `T=...|G=...` 解析。
+ * text 保留首行，方便 T2/T3 合并时继续看到目标。
+ */
+export interface BabelSummary {
+  readonly format: "babel"
+  readonly title: string
+  readonly goal: string
+  readonly text: string
+}
+
+/** 块摘要：JSON 保持原形状，Markdown/Babel 用 format 标记；旧 JSON 块天然兼容。 */
+export type Summary = SummaryFields | MarkdownSummary | BabelSummary
+
+/** 输入：任意摘要；输出：是否 Markdown 摘要。 */
+export function isMarkdownSummary(summary: Summary): summary is MarkdownSummary {
+  return "format" in summary && summary.format === "markdown"
+}
+
+/** 输入：任意摘要；输出：是否 Babel 摘要。 */
+export function isBabelSummary(summary: Summary): summary is BabelSummary {
+  return "format" in summary && summary.format === "babel"
+}
+
+/**
+ * 模型侧摘要输入：JSON 字段都可选，Markdown 用 markdown 字段。
+ *
+ * 预期：JSON 模式在归一化时要求 goal；Markdown 模式要求 markdown。
+ */
+export const SummaryInput = Schema.Struct({
+  format: Schema.optional(
+    Schema.Union([Schema.Literal("json"), Schema.Literal("markdown"), Schema.Literal("babel")]),
+  ),
+  markdown: Schema.optional(Schema.String),
+  babel: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  goal: Schema.optional(Schema.String),
+  constraints: Schema.optional(Schema.Array(Schema.String)),
+  decisions: Schema.optional(Schema.Array(Schema.String)),
+  progress: Schema.optional(
+    Schema.Struct({
+      completed: Schema.optional(Schema.Array(Schema.String)),
+      active: Schema.optional(Schema.Array(Schema.String)),
+      blocked: Schema.optional(Schema.Array(Schema.String)),
+    }),
+  ),
+  open_items: Schema.optional(Schema.Array(Schema.String)),
+  files: Schema.optional(Schema.Array(Schema.String)),
+  facts: Schema.optional(Schema.Array(Schema.String)),
+})
+
+export type SummaryInput = Schema.Schema.Type<typeof SummaryInput>