compressed-context 0.1.0 → 0.2.0

package/src/compression/shape.ts

@@ -0,0 +1,75 @@
+import type { SummaryFormat } from "../shared/settings.ts"
+
+/**
+ * 本模块只放「摘要长什么样」的文案。
+ *
+ * 压缩提示词（summarize.ts）和 compress 工具描述（tool.ts）都从这里取，
+ * 避免两处各写一份、改一处忘另一处。
+ */
+
+const JSON_SHAPE = `{
+  "title": "optional short label for this block",
+  "goal": "required: the objective and any pivots it went through",
+  "constraints": ["optional: hard limits and user preferences"],
+  "decisions": ["optional: what was decided — why"],
+  "progress": {
+    "completed": ["optional: work actually finished"],
+    "active": ["optional: work in progress, including what the user still expects"],
+    "blocked": ["optional: what is blocked — why"]
+  },
+  "open_items": ["optional: unanswered questions, TODOs, next actions"],
+  "files": ["optional: real file paths only, full/path.ext:line — role in the work"],
+  "facts": ["optional: exact errors, signatures, versions, config keys, thresholds, measured values"]
+}`
+
+const MARKDOWN_SHAPE = `# Short title
+## Goal
+...
+## Constraints
+- ...
+## Decisions
+- ...
+## Progress
+### Completed
+- ...
+### Active
+- ...
+### Blocked
+- ...
+## Open Items
+- ...
+## Files
+- ...
+## Facts
+- ...`
+
+/** 输入：格式 + 是否要 candidate 行；输出：格式说明行。 */
+export function shapeLines(format: SummaryFormat | undefined, withCandidate: boolean): string[] {
+  if (format === "babel") {
+    return [
+      withCandidate
+        ? "Return ONLY Babel text. First line must be `c=N`, where N is the chosen candidate; second line must be `T=<short title>|G=<one-line goal>`."
+        : "Return ONLY Babel text. First line must be `T=<short title>|G=<one-line goal>`.",
+      "After the header, use adaptive Babel: only T/G is fixed; invent the shortest anchors/delimiters for this source. No fixed key schema, no Markdown headings, no JSON, no code fences, no commentary.",
+    ]
+  }
+  if (format === "markdown") {
+    return [
+      withCandidate
+        ? "Return ONLY markdown. First line must be `candidate: N`, then a self-contained markdown checkpoint."
+        : "Return ONLY markdown. Do not return JSON. Do not wrap in code fences.",
+      MARKDOWN_SHAPE,
+    ]
+  }
+  return [
+    withCandidate
+      ? "Return ONLY a JSON object with the normal summary shape PLUS a top-level `candidate` number:"
+      : "Return ONLY a JSON object with this exact shape (no markdown fences, no commentary):",
+    JSON_SHAPE,
+  ]
+}
+
+/** 输入：摘要格式；输出：该格式的写法说明，供压缩提示词和工具描述共用。 */
+export function summaryShape(format: SummaryFormat): string {
+  return shapeLines(format, false).join("\n")
+}

package/src/compression/state.ts

@@ -1,248 +1,248 @@
-import type { Schema } from "effect"
-
-import { toBabelSummary } from "./babel.ts"
-import { isSessionDeleted } from "./deleted-sessions.ts"
-import { type Summary, type SummaryFields } from "./schema.ts"
-
-/** 压缩层级：1 = 原文摘要，2/3 = 摘要再蒸馏。 */
-export type Tier = 1 | 2 | 3
-
-/** 下一次 compaction 的目的；缺省表示 T1。 */
-export type CompactionPhase = "t2" | "t3"
-
-/** 一个已落盘或待落盘的压缩块。 */
-export interface Block {
-  readonly id: string
-  readonly tier: Tier
-  readonly summary: Summary
-  readonly fromId: string
-  readonly toId: string
-  readonly tokensBefore: number
-  readonly tokensAfter: number
-  readonly at: number
-  /** active 链中的顺序；合并块占第一个源块的位置。 */
-  readonly order: number
-  /** 被本块合并的源块；空表示原始 T1 块。 */
-  readonly sourceBlockIds?: readonly string[]
-}
-
-/** 每个会话一份的压缩状态。 */
-export interface State {
-  readonly blocks: readonly Block[]
-  readonly pending?: Block
-  /** 下一次 compaction 是二级压缩；T1 时缺省。 */
-  readonly phase?: CompactionPhase
-  readonly attempts: number
-  readonly lastError?: string
-  /** 上一次主动压缩提醒时的上下文 token 数；缺省表示还没建立基线。 */
-  readonly nudgeBaselineTokens?: number
-  /** 已发出的主动压缩提醒次数。 */
-  readonly nudgeCount?: number
-  /** 全 T3 且无法继续压缩时的终止原因；存在时停止自动压缩。 */
-  readonly terminal?: string
-}
-
-/** 服务端 storage 的最小接口，便于测试替身。 */
-export interface StorageLike {
-  get(key: string): Promise<Schema.Json | undefined>
-  set(key: string, value: Schema.Json): Promise<void>
-  remove(key: string): Promise<void>
-}
-
-export const STATE_PREFIX = "compression:state:"
-
-/** 连续压缩失败达到这个次数后暂停自动压缩；同一层内还会做摘要重试。 */
-export const MAX_COMPRESSION_ATTEMPTS = 3
-
-export const EMPTY_STATE: State = { blocks: [], attempts: 0 }
-
-/** 输入：sessionID；输出：storage key。 */
-export function stateKey(sessionID: string): string {
-  return STATE_PREFIX + sessionID
-}
-
-/** 输入：块列表；输出：下一个可用的 order。 */
-export function nextOrder(blocks: readonly Block[]): number {
-  return blocks.reduce((max, block) => Math.max(max, block.order), 0) + 1
-}
-
-/** 输入：已落盘块 + 可选 pending；输出：下一个可用的 bN id。 */
-export function nextBlockId(blocks: readonly Block[], pending?: Block): string {
-  let max = 0
-  const all = pending === undefined ? blocks : [...blocks, pending]
-  for (const block of all) {
-    const numeric = Number(block.id.startsWith("b") ? block.id.slice(1) : "")
-    if (Number.isInteger(numeric) && numeric > max) max = numeric
-  }
-  return `b${(max + 1).toString()}`
-}
-
-function isStringArray(value: unknown): value is readonly string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string")
-}
-
-/** 输入：存储里的摘要；输出：JSON 摘要字段；形状不合法时 undefined。 */
-function parseFields(value: unknown): SummaryFields | undefined {
-  if (typeof value !== "object" || value === null) return undefined
-  const fields = value as Record<string, unknown>
-  if (typeof fields["title"] !== "string" || typeof fields["goal"] !== "string") return undefined
-  if (!isStringArray(fields["constraints"])) return undefined
-  if (!isStringArray(fields["decisions"])) return undefined
-  if (!isStringArray(fields["open_items"])) return undefined
-  if (!isStringArray(fields["files"])) return undefined
-  if (!isStringArray(fields["facts"])) return undefined
-  const progress = fields["progress"]
-  if (typeof progress !== "object" || progress === null) return undefined
-  const p = progress as Record<string, unknown>
-  if (!isStringArray(p["completed"]) || !isStringArray(p["active"]) || !isStringArray(p["blocked"])) {
-    return undefined
-  }
-  return {
-    title: fields["title"],
-    goal: fields["goal"],
-    constraints: fields["constraints"],
-    decisions: fields["decisions"],
-    progress: { completed: p["completed"], active: p["active"], blocked: p["blocked"] },
-    open_items: fields["open_items"],
-    files: fields["files"],
-    facts: fields["facts"],
-  }
-}
-
-/** 输入：存储里的摘要；输出：规范摘要；形状不合法时 undefined。 */
-function parseSummary(value: unknown): Summary | undefined {
-  if (typeof value !== "object" || value === null) return undefined
-  const record = value as Record<string, unknown>
-  if (record["format"] === "markdown") {
-    if (typeof record["title"] !== "string" || typeof record["text"] !== "string") return undefined
-    return { format: "markdown", title: record["title"], text: record["text"] }
-  }
-  if (record["format"] === "babel") {
-    if (typeof record["text"] !== "string") return undefined
-    return toBabelSummary(
-      record["text"],
-      typeof record["title"] === "string" ? record["title"] : undefined,
-      typeof record["goal"] === "string" ? record["goal"] : undefined,
-    )
-  }
-  if ("format" in record) return undefined
-  return parseFields(value)
-}
-
-/** 输入：存储里的块；输出：规范块；形状不合法时 undefined。 */
-function parseBlock(value: unknown): Block | undefined {
-  if (typeof value !== "object" || value === null) return undefined
-  const block = value as Record<string, unknown>
-  if (typeof block["id"] !== "string") return undefined
-  const tier = block["tier"]
-  if (tier !== 1 && tier !== 2 && tier !== 3) return undefined
-  if (typeof block["fromId"] !== "string" || typeof block["toId"] !== "string") return undefined
-  if (typeof block["tokensBefore"] !== "number" || typeof block["tokensAfter"] !== "number") return undefined
-  if (typeof block["at"] !== "number" || typeof block["order"] !== "number") return undefined
-  const sourceBlockIds = block["sourceBlockIds"]
-  if (sourceBlockIds !== undefined && !isStringArray(sourceBlockIds)) return undefined
-  const summary = parseSummary(block["summary"])
-  if (summary === undefined) return undefined
-  return {
-    id: block["id"],
-    tier,
-    summary,
-    fromId: block["fromId"],
-    toId: block["toId"],
-    tokensBefore: block["tokensBefore"],
-    tokensAfter: block["tokensAfter"],
-    at: block["at"],
-    order: block["order"],
-    ...(sourceBlockIds === undefined ? {} : { sourceBlockIds }),
-  }
-}
-
-/**
- * 输入：storage 里的原始值。
- * 输出：合法状态；损坏时返回空状态。
- * 预期：不读版本号、不做迁移；坏块直接丢弃。
- */
-export function parseState(value: unknown): State {
-  if (typeof value !== "object" || value === null) return EMPTY_STATE
-  const record = value as Record<string, unknown>
-  const blocks = Array.isArray(record["blocks"])
-    ? record["blocks"].map(parseBlock).filter((block): block is Block => block !== undefined)
-    : []
-  const pending = parseBlock(record["pending"])
-  const attempts = typeof record["attempts"] === "number" ? record["attempts"] : 0
-  const lastError = typeof record["lastError"] === "string" ? record["lastError"] : undefined
-  const nudgeBaselineTokens =
-    typeof record["nudgeBaselineTokens"] === "number" ? record["nudgeBaselineTokens"] : undefined
-  const nudgeCount = typeof record["nudgeCount"] === "number" ? record["nudgeCount"] : undefined
-  const terminal = typeof record["terminal"] === "string" ? record["terminal"] : undefined
-  const rawPhase = record["phase"]
-  const phase: CompactionPhase | undefined = rawPhase === "t2" || rawPhase === "t3" ? rawPhase : undefined
-  return {
-    blocks,
-    attempts,
-    ...(pending === undefined ? {} : { pending }),
-    ...(lastError === undefined ? {} : { lastError }),
-    ...(nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens }),
-    ...(nudgeCount === undefined ? {} : { nudgeCount }),
-    ...(terminal === undefined ? {} : { terminal }),
-    ...(phase === undefined ? {} : { phase }),
-  }
-}
-
-/** 输入：storage + sessionID；输出：状态。 */
-export async function loadState(storage: StorageLike, sessionID: string): Promise<State> {
-  return parseState(await storage.get(stateKey(sessionID)))
-}
-
-/** 输入：storage + sessionID + 状态；输出：无；预期：写入 JSON；已删会话直接跳过。 */
-export async function saveState(storage: StorageLike, sessionID: string, state: State): Promise<void> {
-  if (isSessionDeleted(sessionID)) return
-  await storage.set(stateKey(sessionID), state as unknown as Schema.Json)
-}
-
-/** 输入：状态；输出：pending 转正后的新状态；预期：成功时清 lastError/terminal，保留下一层 phase。 */
-export function commitPending(state: State): State {
-  if (!state.pending) return state
-  return {
-    blocks: [...state.blocks, state.pending],
-    attempts: 0,
-    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
-    ...(state.phase === undefined ? {} : { phase: state.phase }),
-  }
-}
-
-/** 输入：状态 + 错误；输出：丢弃 pending 后的新状态；预期：失败时清 pending/phase，保留 terminal。 */
-export function dropPending(state: State, error: string): State {
-  return {
-    blocks: state.blocks,
-    attempts: state.attempts + 1,
-    lastError: error,
-    ...(state.nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens: state.nudgeBaselineTokens }),
-    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
-    ...(state.terminal === undefined ? {} : { terminal: state.terminal }),
-  }
-}
-
-/**
- * 输入：失败后的状态 + 错误。
- * 输出：清 pending，但保留 phase 以便下一次请求重试。
- * 预期：attempts 达到上限后清掉 phase，避免无限重试。
- */
-export function retryPending(state: State, error: string): State {
-  const attempts = state.attempts + 1
-  const keepPhase = state.phase !== undefined && attempts < MAX_COMPRESSION_ATTEMPTS
-  return {
-    blocks: state.blocks,
-    attempts,
-    lastError: error,
-    ...(state.nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens: state.nudgeBaselineTokens }),
-    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
-    ...(keepPhase ? { phase: state.phase } : {}),
-    ...(state.terminal === undefined ? {} : { terminal: state.terminal }),
-  }
-}
-
-/** 输入：状态 + 新块；输出：挂上 pending 的新状态。 */
-export function withPending(state: State, block: Block): State {
-  return { ...state, pending: block }
-}
+import type { Schema } from "effect"
+
+import { toBabelSummary } from "./babel.ts"
+import { isSessionDeleted } from "./deleted-sessions.ts"
+import { type Summary, type SummaryFields } from "./schema.ts"
+
+/** 压缩层级：1 = 原文摘要，2/3 = 摘要再蒸馏。 */
+export type Tier = 1 | 2 | 3
+
+/** 下一次 compaction 的目的；缺省表示 T1。 */
+export type CompactionPhase = "t2" | "t3"
+
+/** 一个已落盘或待落盘的压缩块。 */
+export interface Block {
+  readonly id: string
+  readonly tier: Tier
+  readonly summary: Summary
+  readonly fromId: string
+  readonly toId: string
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  readonly at: number
+  /** active 链中的顺序；合并块占第一个源块的位置。 */
+  readonly order: number
+  /** 被本块合并的源块；空表示原始 T1 块。 */
+  readonly sourceBlockIds?: readonly string[]
+}
+
+/** 每个会话一份的压缩状态。 */
+export interface State {
+  readonly blocks: readonly Block[]
+  readonly pending?: Block
+  /** 下一次 compaction 是二级压缩；T1 时缺省。 */
+  readonly phase?: CompactionPhase
+  readonly attempts: number
+  readonly lastError?: string
+  /** 上一次主动压缩提醒时的上下文 token 数；缺省表示还没建立基线。 */
+  readonly nudgeBaselineTokens?: number
+  /** 已发出的主动压缩提醒次数。 */
+  readonly nudgeCount?: number
+  /** 全 T3 且无法继续压缩时的终止原因；存在时停止自动压缩。 */
+  readonly terminal?: string
+}
+
+/** 服务端 storage 的最小接口，便于测试替身。 */
+export interface StorageLike {
+  get(key: string): Promise<Schema.Json | undefined>
+  set(key: string, value: Schema.Json): Promise<void>
+  remove(key: string): Promise<void>
+}
+
+export const STATE_PREFIX = "compression:state:"
+
+/** 连续压缩失败达到这个次数后暂停自动压缩；同一层内还会做摘要重试。 */
+export const MAX_COMPRESSION_ATTEMPTS = 3
+
+export const EMPTY_STATE: State = { blocks: [], attempts: 0 }
+
+/** 输入：sessionID；输出：storage key。 */
+export function stateKey(sessionID: string): string {
+  return STATE_PREFIX + sessionID
+}
+
+/** 输入：块列表；输出：下一个可用的 order。 */
+export function nextOrder(blocks: readonly Block[]): number {
+  return blocks.reduce((max, block) => Math.max(max, block.order), 0) + 1
+}
+
+/** 输入：已落盘块 + 可选 pending；输出：下一个可用的 bN id。 */
+export function nextBlockId(blocks: readonly Block[], pending?: Block): string {
+  let max = 0
+  const all = pending === undefined ? blocks : [...blocks, pending]
+  for (const block of all) {
+    const numeric = Number(block.id.startsWith("b") ? block.id.slice(1) : "")
+    if (Number.isInteger(numeric) && numeric > max) max = numeric
+  }
+  return `b${(max + 1).toString()}`
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string")
+}
+
+/** 输入：存储里的摘要；输出：JSON 摘要字段；形状不合法时 undefined。 */
+function parseFields(value: unknown): SummaryFields | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const fields = value as Record<string, unknown>
+  if (typeof fields["title"] !== "string" || typeof fields["goal"] !== "string") return undefined
+  if (!isStringArray(fields["constraints"])) return undefined
+  if (!isStringArray(fields["decisions"])) return undefined
+  if (!isStringArray(fields["open_items"])) return undefined
+  if (!isStringArray(fields["files"])) return undefined
+  if (!isStringArray(fields["facts"])) return undefined
+  const progress = fields["progress"]
+  if (typeof progress !== "object" || progress === null) return undefined
+  const p = progress as Record<string, unknown>
+  if (!isStringArray(p["completed"]) || !isStringArray(p["active"]) || !isStringArray(p["blocked"])) {
+    return undefined
+  }
+  return {
+    title: fields["title"],
+    goal: fields["goal"],
+    constraints: fields["constraints"],
+    decisions: fields["decisions"],
+    progress: { completed: p["completed"], active: p["active"], blocked: p["blocked"] },
+    open_items: fields["open_items"],
+    files: fields["files"],
+    facts: fields["facts"],
+  }
+}
+
+/** 输入：存储里的摘要；输出：规范摘要；形状不合法时 undefined。 */
+function parseSummary(value: unknown): Summary | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  if (record["format"] === "markdown") {
+    if (typeof record["title"] !== "string" || typeof record["text"] !== "string") return undefined
+    return { format: "markdown", title: record["title"], text: record["text"] }
+  }
+  if (record["format"] === "babel") {
+    if (typeof record["text"] !== "string") return undefined
+    return toBabelSummary(
+      record["text"],
+      typeof record["title"] === "string" ? record["title"] : undefined,
+      typeof record["goal"] === "string" ? record["goal"] : undefined,
+    )
+  }
+  if ("format" in record) return undefined
+  return parseFields(value)
+}
+
+/** 输入：存储里的块；输出：规范块；形状不合法时 undefined。 */
+function parseBlock(value: unknown): Block | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const block = value as Record<string, unknown>
+  if (typeof block["id"] !== "string") return undefined
+  const tier = block["tier"]
+  if (tier !== 1 && tier !== 2 && tier !== 3) return undefined
+  if (typeof block["fromId"] !== "string" || typeof block["toId"] !== "string") return undefined
+  if (typeof block["tokensBefore"] !== "number" || typeof block["tokensAfter"] !== "number") return undefined
+  if (typeof block["at"] !== "number" || typeof block["order"] !== "number") return undefined
+  const sourceBlockIds = block["sourceBlockIds"]
+  if (sourceBlockIds !== undefined && !isStringArray(sourceBlockIds)) return undefined
+  const summary = parseSummary(block["summary"])
+  if (summary === undefined) return undefined
+  return {
+    id: block["id"],
+    tier,
+    summary,
+    fromId: block["fromId"],
+    toId: block["toId"],
+    tokensBefore: block["tokensBefore"],
+    tokensAfter: block["tokensAfter"],
+    at: block["at"],
+    order: block["order"],
+    ...(sourceBlockIds === undefined ? {} : { sourceBlockIds }),
+  }
+}
+
+/**
+ * 输入：storage 里的原始值。
+ * 输出：合法状态；损坏时返回空状态。
+ * 预期：不读版本号、不做迁移；坏块直接丢弃。
+ */
+export function parseState(value: unknown): State {
+  if (typeof value !== "object" || value === null) return EMPTY_STATE
+  const record = value as Record<string, unknown>
+  const blocks = Array.isArray(record["blocks"])
+    ? record["blocks"].map(parseBlock).filter((block): block is Block => block !== undefined)
+    : []
+  const pending = parseBlock(record["pending"])
+  const attempts = typeof record["attempts"] === "number" ? record["attempts"] : 0
+  const lastError = typeof record["lastError"] === "string" ? record["lastError"] : undefined
+  const nudgeBaselineTokens =
+    typeof record["nudgeBaselineTokens"] === "number" ? record["nudgeBaselineTokens"] : undefined
+  const nudgeCount = typeof record["nudgeCount"] === "number" ? record["nudgeCount"] : undefined
+  const terminal = typeof record["terminal"] === "string" ? record["terminal"] : undefined
+  const rawPhase = record["phase"]
+  const phase: CompactionPhase | undefined = rawPhase === "t2" || rawPhase === "t3" ? rawPhase : undefined
+  return {
+    blocks,
+    attempts,
+    ...(pending === undefined ? {} : { pending }),
+    ...(lastError === undefined ? {} : { lastError }),
+    ...(nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens }),
+    ...(nudgeCount === undefined ? {} : { nudgeCount }),
+    ...(terminal === undefined ? {} : { terminal }),
+    ...(phase === undefined ? {} : { phase }),
+  }
+}
+
+/** 输入：storage + sessionID；输出：状态。 */
+export async function loadState(storage: StorageLike, sessionID: string): Promise<State> {
+  return parseState(await storage.get(stateKey(sessionID)))
+}
+
+/** 输入：storage + sessionID + 状态；输出：无；预期：写入 JSON；已删会话直接跳过。 */
+export async function saveState(storage: StorageLike, sessionID: string, state: State): Promise<void> {
+  if (isSessionDeleted(sessionID)) return
+  await storage.set(stateKey(sessionID), state as unknown as Schema.Json)
+}
+
+/** 输入：状态；输出：pending 转正后的新状态；预期：成功时清 lastError/terminal，保留下一层 phase。 */
+export function commitPending(state: State): State {
+  if (!state.pending) return state
+  return {
+    blocks: [...state.blocks, state.pending],
+    attempts: 0,
+    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
+    ...(state.phase === undefined ? {} : { phase: state.phase }),
+  }
+}
+
+/** 输入：状态 + 错误；输出：丢弃 pending 后的新状态；预期：失败时清 pending/phase，保留 terminal。 */
+export function dropPending(state: State, error: string): State {
+  return {
+    blocks: state.blocks,
+    attempts: state.attempts + 1,
+    lastError: error,
+    ...(state.nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens: state.nudgeBaselineTokens }),
+    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
+    ...(state.terminal === undefined ? {} : { terminal: state.terminal }),
+  }
+}
+
+/**
+ * 输入：失败后的状态 + 错误。
+ * 输出：清 pending，但保留 phase 以便下一次请求重试。
+ * 预期：attempts 达到上限后清掉 phase，避免无限重试。
+ */
+export function retryPending(state: State, error: string): State {
+  const attempts = state.attempts + 1
+  const keepPhase = state.phase !== undefined && attempts < MAX_COMPRESSION_ATTEMPTS
+  return {
+    blocks: state.blocks,
+    attempts,
+    lastError: error,
+    ...(state.nudgeBaselineTokens === undefined ? {} : { nudgeBaselineTokens: state.nudgeBaselineTokens }),
+    ...(state.nudgeCount === undefined ? {} : { nudgeCount: state.nudgeCount }),
+    ...(keepPhase ? { phase: state.phase } : {}),
+    ...(state.terminal === undefined ? {} : { terminal: state.terminal }),
+  }
+}
+
+/** 输入：状态 + 新块；输出：挂上 pending 的新状态。 */
+export function withPending(state: State, block: Block): State {
+  return { ...state, pending: block }
+}