dsh-compaction-tower 0.0.0-stage → 0.1.39

package/lib/select.js

@@ -0,0 +1,248 @@
+/**
+ * 选段：纯函数，不碰 session。
+ *
+ * 所有决策都建立在宿主的 TokenSurfaceNode 上（seq / tokens / heuristicTokens），
+ * 这样触发判断与提交范围用的是同一把尺子。
+ *
+ * 两个消费者：
+ *   - 提交计划 planCommits：请求前决定「压哪几块」，按层级升序（保真优先）；
+ *   - 观察者材料 selectRawRun / selectMergeRun：回合尾决定「蒸什么」。
+ */
+
+/**
+ * 表层的「可压缩区」：跳过开头 system，止于第一个受保护节点。
+ *
+ * @param {ReadonlyArray<{seq:number}>} nodes
+ * @param {object} options
+ * @param {Set<number>} options.systemSeqs
+ * @param {Set<number>} options.protectedSeqs
+ * @returns {{seqs:number[], startIndex:number, endIndex:number}|null}
+ */
+export function headRun(nodes, { systemSeqs, protectedSeqs }) {
+  let start = 0;
+  while (start < nodes.length && systemSeqs.has(nodes[start].seq)) start += 1;
+  let end = start;
+  while (end < nodes.length && !protectedSeqs.has(nodes[end].seq)) end += 1;
+  if (end === start) return null;
+  const seqs = [];
+  for (let i = start; i < end; i += 1) seqs.push(nodes[i].seq);
+  return { seqs, startIndex: start, endIndex: end };
+}
+
+/**
+ * 一块材料是否还「可用」：covers 全部仍在表层，且摘要确实更小。
+ *
+ * 提交计划与分层库存都必须过这一关，但只共用到这里：提交还要求材料落在可压区
+ * （保护区之外），库存不管保护区 —— 蒸馏本来就不受保护区限制，块只是提前备好，
+ * 等材料滑出保护区再提交。
+ *
+ * 之所以按「还在不在表层」判，是因为塔外的压缩（宿主的 /compact，或老会话里
+ * 已经存在的 checkpoint）会把一段历史换成没有块号的 checkpoint。覆盖那段的块
+ * 从此永远提交不了；库存若照旧把它们算成待命，观察者会以为库存满了而停止补料，
+ * 塔就慢性停摆了。
+ *
+ * @param {object} block 块记录
+ * @param {object} scope
+ * @param {Set<number>} scope.surfaceSeqs 仍在表层的 seq 集合
+ * @returns {boolean}
+ */
+export function usable(block, { surfaceSeqs }) {
+  if (!Array.isArray(block.covers) || block.covers.length === 0) return false;
+  if (!block.covers.every((seq) => surfaceSeqs.has(seq))) return false;
+  const summaryTokens = Number(block.summaryTokens ?? 0);
+  // 公理：提交只缩小
+  return summaryTokens > 0 && summaryTokens < Number(block.coveredTokens ?? 0);
+}
+
+/**
+ * 提交计划：在可压缩区里按「层级升序、同层最老优先」挑块，累加到目标即停。
+ *
+ * 这就是 Sisyph 的「最少提交 + 分层优先」：先用 T1（原文换摘要，只损失一层），
+ * T1 用尽仍不达标才动 T2（若干已提交 checkpoint 合成一条）。所有材料一次算清，
+ * 不会出现「某块压过线就卡住」。
+ *
+ * @param {object} params
+ * @param {Array<object>} params.blocks 全部块记录
+ * @param {number[]} params.runSeqs 可压缩区的表层 seq（按位置顺序）
+ * @param {Set<number>} params.surfaceSeqs 仍在表层的 seq
+ * @param {number} params.contentTokens 当前内容用量
+ * @param {number} params.targetTokens 目标
+ * @returns {{blocks:Array<object>, projectedTokens:number}}
+ */
+export function planCommits({ blocks, runSeqs, surfaceSeqs, contentTokens, targetTokens }) {
+  const inRun = new Set(runSeqs);
+  const position = new Map(runSeqs.map((seq, index) => [seq, index]));
+
+  // 两道筛：材料还在（与库存同一判据）→ 材料在可压区。
+  const candidates = blocks.filter((block) => usable(block, { surfaceSeqs })
+    && block.covers.every((seq) => inRun.has(seq)));
+
+  candidates.sort((a, b) => (Number(a.tier ?? 1) - Number(b.tier ?? 1))
+    || ((position.get(a.covers[0]) ?? 0) - (position.get(b.covers[0]) ?? 0)));
+
+  const chosen = [];
+  let content = contentTokens;
+  for (const block of candidates) {
+    if (content <= targetTokens) break;
+    if (chosen.some((picked) => overlaps(picked, block))) continue;
+    chosen.push(block);
+    content += Number(block.summaryTokens ?? 0) - Number(block.coveredTokens ?? 0);
+  }
+  return { blocks: chosen, projectedTokens: content };
+}
+
+/** 两个块是否有覆盖交集。 */
+function overlaps(a, b) {
+  const seen = new Set(a.covers);
+  return b.covers.some((seq) => seen.has(seq));
+}
+
+/**
+ * 观察配额：从最底层开始逐层发名额，发满并发上限就停。
+ *
+ * 每层独立记账 —— 低层块只能顶低层的缺，高层块顶不了（提交顺序是低层优先，
+ * 高层要等低层用完才会被动用）。所以「T1 有 2 个 + T2 有 2 个」不等于「库存够了」。
+ *
+ * @param {object} params
+ * @param {Map<number, number>} params.available 每层现在有几个单位的材料
+ * @param {Map<number, number>} params.inventory 每层未提交块的可回收 token
+ * @param {number} params.reserveTokens 每层目标库存（token）
+ * @param {number} params.unitTokens 一个单位多少 token
+ * @param {number} params.concurrency 一次最多发几个
+ * @returns {Array<{tier: number, count: number}>}
+ */
+export function planObservation({ available, inventory, reserveTokens, unitTokens, concurrency }) {
+  const tiers = [...available.keys()].sort((a, b) => a - b);
+  const plan = [];
+  let slots = Math.max(0, Math.floor(concurrency));
+  for (const tier of tiers) {
+    if (slots <= 0) break;
+    const missing = reserveTokens - (inventory.get(tier) ?? 0);
+    if (missing <= 0) continue;          // 这一层库存够了，不再主动蒸
+    const need = Math.max(1, Math.ceil(missing / unitTokens));
+    const count = Math.min(need, available.get(tier) ?? 0, slots);
+    if (count <= 0) continue;
+    plan.push({ tier, count });
+    slots -= count;
+  }
+  return plan;
+}
+
+/**
+ * 观察者材料 A：一段连续的原文。
+ *
+ * 从最老的「既没被块覆盖、也不是 checkpoint」的位置起算，遇到 checkpoint 就断——
+ * 段内位置连续，covers 才能诚实地对应一个区间。
+ *
+ * 取多少：**攒够一个单位就收手**（`stopAtTokens`，通常是窗口的 5%）。多出来的原文
+ * 留在表层不动，下一回合接着蒸——所以单块分量是稳定的「一个单位」，不会因为旧料
+ * 攒了半天就长成一百多 K。`maxTokens` 只是保险丝（拦住异常巨大的单个节点），
+ * 不是常规尺寸。
+ *
+ * @param {ReadonlyArray<{seq:number, tokens:number}>} nodes
+ * @param {object} options
+ * @param {number} [options.stopAtTokens] 攒到这个量就停
+ * @returns {number[]} 可为空
+ */
+export function selectRawRun(nodes, { systemSeqs, protectedSeqs, coveredSeqs, checkpointSeqs, minTokens, maxTokens, stopAtTokens }) {
+  let start = 0;
+  while (start < nodes.length && systemSeqs.has(nodes[start].seq)) start += 1;
+  while (start < nodes.length) {
+    const node = nodes[start];
+    const usable = !coveredSeqs.has(node.seq) && !checkpointSeqs.has(node.seq) && !protectedSeqs.has(node.seq);
+    if (usable) break;
+    start += 1;
+  }
+
+  const seqs = [];
+  let tokens = 0;
+  for (let i = start; i < nodes.length; i += 1) {
+    const node = nodes[i];
+    if (protectedSeqs.has(node.seq) || coveredSeqs.has(node.seq) || checkpointSeqs.has(node.seq)) break;
+    if (tokens + node.tokens > maxTokens && seqs.length > 0) break;
+    seqs.push(node.seq);
+    tokens += node.tokens;
+    if (stopAtTokens !== undefined && tokens >= stopAtTokens) break;
+  }
+  if (tokens < minTokens) return [];
+  return seqs;
+}
+
+/**
+ * 观察者材料 B：相邻的、**同一层**的已提交 checkpoint。
+ *
+ * 只合并同层，是为了让塔真的按层长：两个 T1 合成一个 T2，两个 T2 才合成 T3。
+ * 若允许 T1 与 T2 混合合并，每次都会把「最新的浅块」吸进「上一层」，深度随
+ * 提交次数线性增长，分层就名存实亡了。
+ *
+ * 合并与蒸馏用同一把尺子：**材料攒够 minTokens（窗口的 5%）才值得花一次调用**。
+ * 所以从最老的 checkpoint 往后累加，一旦累计达到阈值就收手——这一次要合并的
+ * 就是「刚好够分量」的那几个，多出来的留给下一轮，别把一堆小 checkpoint 一次
+ * 吞掉（那样每次合并都只值几 K token，白花一次模型调用）。
+ *
+ * @param {ReadonlyArray<{seq:number, tokens:number}>} nodes
+ * @param {object} options
+ * @param {Map<number, number>} options.tierOf checkpoint 的层级
+ * @param {number} [options.memberTier] 只从这一层的 checkpoint 里选。塔要蒸第 N 层时
+ *   必须传 N-1：不过滤的话，从最老的 checkpoint 扫起会先撞上更深的 run，回来后
+ *   一比对「合并出来不是我要的层」就整轮空手，浅层的材料永远轮不到。
+ * @param {number} options.minCount 一次合并的块数下限（≥2）
+ * @param {number} options.minTokens 材料总量下限（通常是窗口的 5%）
+ * @param {number} options.maxTokens 一次合并的原文上限
+ * @param {Set<number>} [options.coveredSeqs] 已被更高层块覆盖的 checkpoint，不再重复合并
+ * @returns {number[]} 可为空
+ */
+export function selectMergeRun(nodes, {
+  protectedSeqs,
+  coveredSeqs,
+  checkpointSeqs,
+  tierOf,
+  memberTier,
+  minCount,
+  minTokens,
+  maxTokens,
+}) {
+  const covered = coveredSeqs ?? new Set();
+  let index = 0;
+  while (index < nodes.length) {
+    const seq = nodes[index].seq;
+    if (!checkpointSeqs.has(seq) || protectedSeqs.has(seq) || covered.has(seq)) { index += 1; continue; }
+    const tier = tierOf.get(seq);
+    if (tier === undefined) { index += 1; continue; }
+    if (memberTier !== undefined && tier !== memberTier) { index += 1; continue; }
+
+    const run = [];
+    let tokens = 0;
+    let next = index;
+    while (next < nodes.length) {
+      const candidate = nodes[next].seq;
+      if (!checkpointSeqs.has(candidate) || protectedSeqs.has(candidate) || covered.has(candidate)) break;
+      if (tierOf.get(candidate) !== tier) break;
+      if (run.length > 0 && tokens + nodes[next].tokens > maxTokens) break;
+      run.push(candidate);
+      tokens += nodes[next].tokens;
+      next += 1;
+      if (tokens >= minTokens) break;
+    }
+    if (run.length >= minCount && tokens >= minTokens) return run;
+    index = next;
+  }
+  return [];
+}
+
+/**
+ * 从「最近 retain 个 step」推导受保护的表层节点。
+ *
+ * 一个 step = 一次模型请求。保护窗口按 step 算，不按用户轮次 —— 用户发一句话之后
+ * agent 可能连续跑几十步，按轮次算会把整段新对话都圈成保护区，永远没料可蒸。
+ *
+ * @param {ReadonlyArray<number>} surfaceSeqs 表层节点 seq，按位置顺序
+ * @param {ReadonlyArray<number>} stepStarts 所有 step/start 的 seq（升序）
+ * @param {number} retainSteps 保护最近几个 step；0 = 不保护
+ * @returns {Set<number>}
+ */
+export function protectedTail(surfaceSeqs, stepStarts, retainSteps) {
+  if (retainSteps <= 0 || stepStarts.length === 0) return new Set();
+  const cutSeq = stepStarts[Math.max(0, stepStarts.length - retainSteps)];
+  return new Set(surfaceSeqs.filter((seq) => seq >= cutSeq));
+}

package/lib/server.js

@@ -0,0 +1,253 @@
+/**
+ * 给 Web 界面用的路由：状态、手动操作、配置读写。
+ *
+ * 只挂在宿主的 webServer 上（与 GUI 同源），所以客户端用相对路径 fetch 即可。
+ * headless / TUI 之类没有 webServer 的 profile 不会装载本模块。
+ */
+import { buildState } from './state.js';
+import { PROMPT_PRESETS } from './prompts.js';
+
+/** 允许的手动操作。 */
+const ACTIONS = new Set(['distill', 'commit', 'merge']);
+
+/**
+ * 注册路由。
+ * @param {object} ctx 带 webServer / sessions / agents 服务的 context
+ * @param {{tower: import('./tower.js').Tower, store: import('./config-store.js').ConfigStore}} deps
+ * @returns {() => void} disposer
+ */
+export function registerTowerRoutes(ctx, deps) {
+  const { tower, store } = deps;
+  // 宿主自带的 named route 不套登录鉴权（只有它自己的 /api 走），
+  // 所以这里自己问一次连接服务：没带会话 cookie 就 401，别把会话状态漏给本机任何进程。
+  // 注意用 ctx.get()：直接 ctx.connection 会因为没有 inject 而抛错；
+  // 也不能在注册时就取 —— 路由比连接服务先装载，那时它还是 undefined。
+  let cached;
+  const connectionOf = () => {
+    if (cached !== undefined) return cached;
+    try {
+      cached = ctx.get?.('connection');
+    } catch {
+      cached = undefined;
+    }
+    return cached;
+  };
+  const authorize = (req, res) => {
+    const connection = connectionOf();
+    if (connection === undefined || typeof connection.authorizeIndex !== 'function') return true;
+    try {
+      return connection.authorizeIndex(req, res) === true;
+    } catch {
+      return false;
+    }
+  };
+  const disposers = [
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/tower/state',
+      handler: (req, res) => (authorize(req, res) ? handleState(ctx, tower, req, res) : undefined),
+    }),
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/tower/action',
+      handler: (req, res) => (authorize(req, res) ? handleAction(ctx, tower, req, res) : undefined),
+    }),
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/tower/config',
+      handler: (req, res) => (authorize(req, res) ? handleConfig(ctx, store, req, res) : undefined),
+    }),
+  ];
+  return () => {
+    for (const dispose of disposers) dispose?.();
+  };
+}
+
+/** GET /tower/state?sessionId=…（省略时取最近一个活动会话） */
+async function handleState(ctx, tower, req, res) {
+  if (req.method !== 'GET') return fail(res, 405, 'method not allowed');
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  const wanted = url.searchParams.get('sessionId');
+  const live = listSessions(ctx);
+  const session = wanted === null || wanted.length === 0
+    ? live.at(-1)
+    : live.find((candidate) => String(candidate.id) === wanted);
+
+  if (session === undefined) {
+    return fail(res, 404, wanted === null ? 'no live session' : `session "${wanted}" is not open`);
+  }
+  try {
+    const state = await buildState(tower, session);
+    return json(res, 200, { ...state, sessions: live.map((candidate) => String(candidate.id)) });
+  } catch (error) {
+    return fail(res, 500, String(error?.message ?? error));
+  }
+}
+
+/** POST /tower/action {kind, sessionId, blockIds?} */
+async function handleAction(ctx, tower, req, res) {
+  if (req.method !== 'POST') return fail(res, 405, 'method not allowed');
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    return fail(res, 400, 'body must be JSON');
+  }
+  const kind = String(body?.kind ?? '');
+  if (!ACTIONS.has(kind)) return fail(res, 400, `unknown action "${kind}"`);
+
+  const sessionId = String(body?.sessionId ?? '');
+  const agent = lookupAgent(ctx, sessionId);
+  if (agent === undefined) return fail(res, 404, `no live agent for session "${sessionId}"`);
+
+  try {
+    if (kind === 'distill') {
+      await tower.observe(agent, undefined, undefined);
+      return json(res, 200, { ok: true, message: '已蒸馏一次' });
+    }
+    if (kind === 'commit') {
+      // 真正换成 checkpoint 必须发生在回合里，这里只排队（见 tower.requestCommit）。
+      const queued = tower.requestCommit(agent);
+      return json(res, 200, {
+        ok: true,
+        queued,
+        message: queued ? '已排队：下一个回合开始时提交' : '这个会话没有可排队的回合',
+      });
+    }
+    const blockIds = Array.isArray(body?.blockIds) ? body.blockIds.map(String) : [];
+    const record = await tower.mergeBlocks(agent, undefined, blockIds);
+    if (record === null) return fail(res, 400, '这两个块无法合并（需同层且仍在表层）');
+    return json(res, 200, { ok: true, blockId: record.blockId });
+  } catch (error) {
+    return fail(res, 500, String(error?.message ?? error));
+  }
+}
+
+/** GET /tower/config（读快照）· POST /tower/config {patch} 或 {reset:[key…]} */
+async function handleConfig(ctx, store, req, res) {
+  if (req.method === 'GET') {
+    try {
+      return json(res, 200, { ok: true, ...store.snapshot(), catalog: await modelCatalog(ctx), presets: PROMPT_PRESETS });
+    } catch (error) {
+      return fail(res, 500, String(error?.message ?? error));
+    }
+  }
+  if (req.method !== 'POST') return fail(res, 405, 'method not allowed');
+
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    return fail(res, 400, 'body must be JSON');
+  }
+
+  try {
+    if (body?.reset !== undefined) {
+      store.reset(body.reset);
+    } else if (body?.patch !== undefined) {
+      store.save(body.patch);
+    } else {
+      return fail(res, 400, '需要 patch 或 reset 字段');
+    }
+  } catch (error) {
+    return fail(res, 400, String(error?.message ?? error));
+  }
+  return json(res, 200, { ok: true, ...store.snapshot(), catalog: await modelCatalog(ctx), presets: PROMPT_PRESETS });
+}
+
+/**
+ * 宿主的模型目录：下拉框的数据源。
+ *
+ * `llm.listModels` 可能去问 provider，所以结果缓存一分钟；某个 provider 挂了
+ * 只有它自己的模型缺失，不影响其它 provider（allSettled）。
+ */
+const catalogCache = { at: 0, value: undefined, pending: undefined };
+
+async function modelCatalog(ctx) {
+  if (catalogCache.value !== undefined && Date.now() - catalogCache.at < 60000) return catalogCache.value;
+  if (catalogCache.pending !== undefined) return catalogCache.pending;
+
+  catalogCache.pending = (async () => {
+    const catalog = { providers: [], models: [] };
+    let llm;
+    try {
+      llm = ctx.get?.('llm');
+    } catch {
+      llm = undefined;
+    }
+    if (llm === undefined || llm === null || typeof llm.listProviders !== 'function') return catalog;
+    try {
+      catalog.providers = (llm.listProviders() ?? []).map((provider) => ({
+        id: String(provider.id),
+        name: String(provider.name ?? provider.id),
+      }));
+      const settled = await Promise.allSettled(
+        catalog.providers.map((provider) => llm.listModels(provider.id)),
+      );
+      settled.forEach((result, index) => {
+        if (result.status !== 'fulfilled') return;
+        const provider = catalog.providers[index].id;
+        for (const model of result.value ?? []) {
+          catalog.models.push({
+            provider,
+            id: String(model.id),
+            name: String(model.name ?? model.id),
+          });
+        }
+      });
+    } catch {
+      // 目录拿不到就当空目录：界面退化成手填不了也不至于报错。
+    }
+    return catalog;
+  })();
+
+  try {
+    const value = await catalogCache.pending;
+    if (value.providers.length > 0) {
+      catalogCache.value = value;
+      catalogCache.at = Date.now();
+    }
+    return value;
+  } finally {
+    catalogCache.pending = undefined;
+  }
+}
+
+function lookupAgent(ctx, sessionId) {  try {
+    return ctx.agents.get(sessionId);
+  } catch {
+    return undefined;
+  }
+}
+
+/** 当前打开着的会话，按打开顺序。 */
+function listSessions(ctx) {
+  try {
+    return ctx.sessions.list();
+  } catch {
+    return [];
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+function json(res, status, value) {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function fail(res, status, message) {
+  json(res, status, { ok: false, error: message });
+}

package/lib/state.js

@@ -0,0 +1,192 @@
+/**
+ * UI 数据：把一块会话的压缩状态整理成一份纯 JSON。
+ *
+ * 这里是唯一的"给界面看"的出口：不依赖任何 UI 框架，也不写日志。
+ * 块的三种状态全部从事件现算——不缓存，避免界面与账本不一致。
+ */
+import { blockText } from './tower.js';
+import {
+  checkpointIndex, formatTokens, refOf,
+} from './core.js';
+
+/**
+ * 构造一份可序列化的状态快照。
+ * @param {import('./tower.js').Tower} tower
+ * @param {object} session
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<object>}
+ */
+export async function buildState(tower, session, signal) {
+  const measurement = tower.ctx.tokenMeter.measure(session);
+  // 固定开销（system + 工具 schema）不从窗口里扣掉，进度条就会把「还能塞 700K」
+  // 画成可用空间。阈值与面板必须用同一个分母，所以两边都走 overheadOf。
+  const overhead = tower.overheadOf(session, measurement.nodes);
+  // 估算值统一乘事实修正系数，和 provider 报的真实 token 同一把尺子。
+  const scale = tower.calibration(session, measurement, overhead);
+  const blocks = tower.blocksOf(session);
+  const surfaceSeqs = session.surface.nodes;
+  const surface = new Set(surfaceSeqs);
+  const checkpointOf = checkpointIndex(session);
+  const childOf = new Set();
+  for (const block of blocks) for (const id of block.childBlockIds ?? []) childOf.add(id);
+
+  const header = session.requestHeader();
+  const route = header?.config;
+  const budget = await budgetOf(tower, route, signal);
+  const messages = Math.max(0, Number(measurement.surfaceTokens ?? 0) - overhead.system);
+  const content = Math.max(0, messages * scale);
+  const usable = budget === null ? null : Math.max(1, budget - overhead.total * scale);
+
+  return {
+    session: {
+      id: String(session.id),
+      cwd: session.header?.cwd ?? null,
+    },
+    pressure: pressureOf(tower, session),
+    observation: observationOf(tower, session),
+    budget: {
+      contextWindow: budget,
+      total: measurement.totalTokens,
+      content,
+      fixed: { system: overhead.system, tools: overhead.tools, total: Math.round(overhead.total * scale), ratio: scale },
+      usable,
+      triggerTokens: usable === null ? null : Math.round(tower.config.triggerRatio * usable),
+      targetTokens: usable === null ? null : Math.round(tower.config.targetRatio * usable),
+      triggerRatio: tower.config.triggerRatio,
+      targetRatio: tower.config.targetRatio,
+      retainRecentGroups: tower.config.retainRecentGroups,
+    },
+    blocks: blocks.map((block) => ({
+      blockId: block.blockId,
+      tier: block.tier,
+      kind: block.kind ?? 'run',
+      covers: block.covers,
+      coverRefs: block.covers.map(refOf),
+      coveredTokens: block.coveredTokens ?? 0,
+      summaryTokens: block.summaryTokens ?? 0,
+      coveredLabel: formatTokens(block.coveredTokens ?? 0),
+      summaryLabel: formatTokens(block.summaryTokens ?? 0),
+      childBlockIds: block.childBlockIds ?? [],
+      checkpointSeq: checkpointOf.get(block.blockId) ?? null,
+      status: statusOf(block, checkpointOf, surface, childOf),
+      createdAt: block.createdAt ?? null,
+      origin: block.origin ?? null,
+      summary: blockText(block),
+    })),
+    surface: surfaceSeqs.map((seq) => {
+      const event = session.eventAt(seq);
+      return {
+        seq,
+        ref: refOf(seq),
+        type: event?.type ?? 'unknown',
+        checkpoint: checkpointOf.size > 0 ? checkpointBlockOf(checkpointOf, seq) : null,
+      };
+    }),
+    stats: { ...tower.stats },
+    // 「当前组装」：表层上到底拼了些什么。只数表层上的东西 —— 已提交的块按层计数，
+    // 还没被压掉的消息算原文；待提交的块不在上下文里，不进这行。
+    composition: compositionOf(surfaceSeqs, checkpointOf, blocks, overhead.systemSeqs),
+  };
+}
+
+/**
+ * 表层配方：每层几个块 + 还剩多少条原文。
+ * @param {number[]} surfaceSeqs 表层节点（顺序即时间顺序）
+ * @param {Map<string, number>} checkpointOf blockId → checkpoint 节点
+ * @param {Array<object>} blocks 账本里的块
+ * @param {Set<number>} systemSeqs system 消息的节点（不算原文）
+ * @returns {{tiers: Array<{tier:number,count:number}>, raw:number}}
+ */
+function compositionOf(surfaceSeqs, checkpointOf, blocks, systemSeqs) {
+  const tierOf = new Map(blocks.map((block) => [block.blockId, block.tier ?? 1]));
+  const counts = new Map();
+  let raw = 0;
+  for (const seq of surfaceSeqs) {
+    if (systemSeqs?.has(seq) === true) continue;
+    const blockId = checkpointOf.size > 0 ? checkpointBlockOf(checkpointOf, seq) : null;
+    if (blockId === null) { raw += 1; continue; }
+    const tier = tierOf.get(blockId) ?? 1;
+    counts.set(tier, (counts.get(tier) ?? 0) + 1);
+  }
+  const tiers = [...counts.entries()]
+    .map(([tier, count]) => ({ tier, count }))
+    .sort((left, right) => right.tier - left.tier);
+  return { tiers, raw };
+}
+
+/** 会话里所有 checkpoint 节点：blockId → 该节点的 seq。 */
+function checkpointBlockOf(index, seq) {
+  for (const [blockId, at] of index) if (at === seq) return blockId;
+  return null;
+}
+
+/**
+ * 块状态：
+ *   consumed  = 已被上层块覆盖（上层块的 childBlockIds 里有它）
+ *   committed = 摘要节点仍在表层
+ *   dormant   = 已蒸馏但还没进过上下文
+ */
+function statusOf(block, checkpointOf, surface, childOf) {
+  if (childOf.has(block.blockId)) return 'consumed';
+  const seq = checkpointOf.get(block.blockId);
+  if (seq !== undefined && surface.has(seq)) return 'committed';
+  return 'dormant';
+}
+
+/**
+ * 上一次压力判定（为什么压 / 为什么没压）。只暴露可序列化的字段。
+ * @param {object} tower
+ * @param {object} session
+ */
+function pressureOf(tower, session) {
+  const last = tower.lastPressure?.get(session);
+  if (last === undefined || last === null) return null;
+  return {
+    at: last.at ?? null,
+    kind: last.kind ?? null,
+    total: last.total ?? null,
+    content: last.content ?? null,
+    fixed: last.fixed ?? null,
+    usable: last.usable ?? null,
+    trigger: last.trigger ?? null,
+    budget: last.budget ?? null,
+    blockIds: Array.isArray(last.blockIds) ? last.blockIds : null,
+    blockCount: Array.isArray(last.blockIds) ? last.blockIds.length : null,
+    projected: last.projected ?? null,
+    blocks: Array.isArray(last.blocks) ? last.blocks.length : (last.blocks ?? null),
+    run: last.run ?? null,
+    calls: last.calls ?? null,
+    outcome: last.outcome === undefined || last.outcome === null ? null : {
+      planned: last.outcome.planned ?? 0,
+      succeeded: last.outcome.succeeded ?? 0,
+      error: last.outcome.error ?? null,
+    },
+  };
+}
+
+/**
+ * 上一次观察判定（为什么蒸 / 为什么没蒸）。只暴露可序列化的字段。
+ * @param {object} tower
+ * @param {object} session
+ */
+function observationOf(tower, session) {
+  const last = tower.lastObservation?.get(session);
+  if (last === undefined || last === null) return null;
+  return {
+    at: last.at ?? null,
+    kind: last.kind ?? null,
+    unit: last.unit ?? null,
+    protected: last.protected ?? null,
+    plan: Array.isArray(last.plan) ? last.plan : null,
+    available: Array.isArray(last.available) ? last.available : null,
+  };
+}
+
+async function budgetOf(tower, route, signal) {
+  if (typeof route?.provider !== 'string' || typeof route?.model !== 'string') return null;
+  try {
+    return await tower.budgetOfRoute(route.provider, route.model, signal);
+  } catch {
+    return null;
+  }
+}