dsh-plugin-mobile-link 0.4.1 → 0.6.5

package/lib/diagnostics.js

@@ -0,0 +1,172 @@
+/**
+ * 一次接入的计时与有界耗时汇总（spec 020）。
+ *
+ * 职责（只做这三件，别的都不做）：
+ *   1. **阶段计时**：一次设备接入走完「接入 → `_link/hello` → 首个数据请求 → 首个响应」各用了多少毫秒；
+ *      没发生的阶段必须是 `null` 并在 `missing` 里列出——**不许记 0**（0 与"没发生"在判读时是两回事）。
+ *   2. **慢请求**：单次请求超过阈值时产出一条 `request.slow`（方法名、耗时、字节数）。
+ *   3. **有界汇总**：一次接入的 `requests / slow / maxMs / p50Ms / p95Ms / top3`，
+ *      用**定长水库**估分位，数组长度不随请求数增长（否则"记日志"本身会变成新的性能问题）。
+ *
+ * 本模块是纯逻辑：它不认识 socket、不认识 journal，事件由上层通过 `onEvent` 注入
+ * （宪法原则 VII.1：能力注入，不在内部读全局状态）。
+ *
+ * 契约：`docs/diagnostics-events.md`
+ * 数据模型：`specs/020-link-diagnostics/data-model.md` §3–§5
+ */
+
+/** 水库样本容量：估 p50/p95 够用，且不随请求数增长。 */
+export const RESERVOIR_SIZE = 256
+/** 每累计这么多请求写一条汇总（加上断开时那条，构成"条数常数级"的上界）。 */
+export const SUMMARY_EVERY = 200
+/** `top3` 保留几条最慢的请求。 */
+export const TOP_SLOWEST = 3
+
+/** 阶段名（对外，出现在 `missing` 里）。 */
+export const PHASES = Object.freeze({
+  helloMs: 'hello',
+  firstRequestMs: 'first-request',
+  firstResponseMs: 'first-response',
+})
+
+/** 握手方法名（与 `hello.js` 同口径；这里只用来区分"握手"与"数据请求"）。 */
+const HELLO_METHOD = '_link/hello'
+
+/** 最近秩分位数：样本少的时候比插值更保守，也更容易在单测里核对。 */
+function percentile(sorted, fraction) {
+  if (sorted.length === 0) return 0
+  const rank = Math.ceil(fraction * sorted.length)
+  return sorted[Math.max(0, Math.min(sorted.length - 1, rank - 1))]
+}
+
+export class DeviceTimeline {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.deviceId]
+   * @param {number} [options.slowRequestMs] 超过它才记 `request.slow`；0 表示关闭该逐条记录
+   * @param {() => number} [options.now]
+   * @param {(kind: string, detail: Record<string, unknown>) => void} [options.onEvent]
+   */
+  constructor({ deviceId, slowRequestMs = 2000, now = Date.now, onEvent = () => {} } = {}) {
+    this.deviceId = deviceId
+    this.slowRequestMs = Number(slowRequestMs) || 0
+    this.now = now
+    this.onEvent = onEvent
+    this.attachedAt = now()
+    this.helloAt = undefined
+    this.firstRequestAt = undefined
+    this.firstResponseAt = undefined
+    this.requests = 0
+    this.slow = 0
+    this.maxMs = 0
+    /** 定长水库：满了以后按步长覆盖（确定性的系统抽样，避免引入随机数让单测发抖）。 */
+    this._samples = []
+    this._sampleCursor = 0
+    /** 最慢的若干条，长度恒 ≤ TOP_SLOWEST。 */
+    this._top = []
+    this._phaseEmitted = false
+  }
+
+  /** 收到 `_link/hello`（只在第一次生效）。 */
+  noteHello(at = this.now()) {
+    if (this.helloAt === undefined) this.helloAt = at
+  }
+
+  /**
+   * 一次请求收尾。
+   *
+   * @param {{method: string, startedAt: number, ms: number, bytes: number}} request
+   */
+  noteRequest({ method, startedAt, ms, bytes }) {
+    const isHello = method === HELLO_METHOD
+    if (isHello) this.noteHello(startedAt)
+    if (!isHello && this.firstRequestAt === undefined) this.firstRequestAt = startedAt
+    // 只认**数据请求**的响应：握手响应不算。否则 `firstResponseMs` 会小于 `firstRequestMs`
+    // （握手先回、数据请求后发），三段的阶梯就读不出来了。
+    if (!isHello && this.firstResponseAt === undefined) this.firstResponseAt = startedAt + ms
+
+    this.requests += 1
+    this.maxMs = Math.max(this.maxMs, ms)
+    this.#sample(ms)
+    this.#keepTop({ method, ms, bytes })
+    if (this.slowRequestMs > 0 && ms > this.slowRequestMs) {
+      this.slow += 1
+      // 字段叫 elapsedMs 而不是 ms：`ms` 是信封上的**时刻**，同名会把时刻冲掉（见 journal.js）。
+      this.onEvent('request.slow', { deviceId: this.deviceId, method, elapsedMs: ms, bytes })
+    }
+    if (this.requests % SUMMARY_EVERY === 0) this.emitSummary()
+    this.#maybeEmitPhase()
+  }
+
+  /** 阶段明细（`missing` 里的阶段名，其 `phases.*Ms` 必为 null）。 */
+  phaseDetail() {
+    const relative = (at) => (at === undefined ? null : at - this.attachedAt)
+    const phases = {
+      helloMs: relative(this.helloAt),
+      firstRequestMs: relative(this.firstRequestAt),
+      firstResponseMs: relative(this.firstResponseAt),
+    }
+    const missing = Object.entries(phases)
+      .filter(([, value]) => value === null)
+      .map(([key]) => PHASES[key])
+    return { deviceId: this.deviceId, phases, missing }
+  }
+
+  /** 汇总明细（分位来自定长水库）。 */
+  summaryDetail() {
+    const sorted = [...this._samples].sort((a, b) => a - b)
+    return {
+      deviceId: this.deviceId,
+      requests: this.requests,
+      slow: this.slow,
+      maxMs: this.maxMs,
+      p50Ms: percentile(sorted, 0.5),
+      p95Ms: percentile(sorted, 0.95),
+      top3: this._top.map((entry) => ({ ...entry })),
+    }
+  }
+
+  /** 断开时调用：补齐阶段事件（若还没写过）并在有请求时才写汇总。 */
+  finish() {
+    if (!this._phaseEmitted) {
+      this._phaseEmitted = true
+      this.onEvent('device.phase', this.phaseDetail())
+    }
+    if (this.requests > 0) this.emitSummary()
+  }
+
+  /** 写一条汇总（供断开与每 `SUMMARY_EVERY` 个请求两个时机调用）。 */
+  emitSummary() {
+    this.onEvent('device.summary', this.summaryDetail())
+  }
+
+  #sample(ms) {
+    if (this._samples.length < RESERVOIR_SIZE) {
+      this._samples.push(ms)
+      return
+    }
+    const index = this._sampleCursor % RESERVOIR_SIZE
+    this._samples[index] = ms
+    this._sampleCursor += 1
+  }
+
+  #keepTop(entry) {
+    this._top.push(entry)
+    this._top.sort((a, b) => b.ms - a.ms)
+    if (this._top.length > TOP_SLOWEST) this._top.length = TOP_SLOWEST
+  }
+
+  #maybeEmitPhase() {
+    if (this._phaseEmitted) return
+    // 三段**全齐**才写；缺哪一段就等 `finish()` 时按 missing 写（读者要知道"没发生"，而不是看到 0）。
+    //
+    // 为什么要求全齐而不是"有数据请求就写"：App 的真实顺序是**先探针（session/list）再握手**
+    // （`ConnectionStore.connect()` 先 `sessions()`，再在 `install()` 里发 `_link/hello`）。
+    // 按旧条件，阶段事件会在探针那一刻写出来、`missing: ['hello']`，于是最有用的
+    // 「attach→hello 用了多久」在事件里永远是空的——2026-10-13 09:28 的中转运行实测到了这一条。
+    if (this.helloAt === undefined) return
+    if (this.firstRequestAt === undefined || this.firstResponseAt === undefined) return
+    this._phaseEmitted = true
+    this.onEvent('device.phase', this.phaseDetail())
+  }
+}

package/lib/hello.js

@@ -41,8 +41,9 @@ function readManifestVersion() {
  * - `events`         the per-device `$events` stream is served
  * - `session-streams` logical streams (`session/follow`, …) are served
  * - `pair-code`      this connector can mint a pairing code on request
- * - `qr-pairing`     this connector can render the pairing QR itself
- *                    (`GET /mobile-link/qr`), so the desktop needs no client
+ * - `qr-pairing`     this connector renders the pairing QR itself (the `svg`
+ *                    field of `POST /mobile-link/pair-code`), so the DSH client
+ *                    needs no QR library of its own
  * - `self-enroll`    this connector can register itself with an invite code
  * - `git`            git status / diff / log / show can be read from the work
  *                    tree on this computer (see git.js)
@@ -57,6 +58,22 @@ function readManifestVersion() {
 export const SERVER_CAPABILITIES = [
   'file-transfer', 'events', 'session-streams', 'pair-code', 'qr-pairing', 'self-enroll', 'git',
   'background-transfer',
+  // history-window: the connector answers `_link/sessionWindow` (exact seq window);
+  // session-search: it answers `_link/sessionFind` (in-session literal search). The
+  // phone switches channels on these and falls back to `session/page` without them.
+  'history-window', 'session-search',
+  // session-digest: 连接器答 `_link/sessionDigest`（`session/list` 的精简同形副本，
+  // 去掉 App 侧零读取点的字段、可按要求 gzip）。手机侧按这条能力切换，缺了就回退到
+  // `session/list`——spec 021 只做连接器侧，切换在后续规格。
+  'session-digest',
+  // history-role-filter: `_link/sessionWindow` accepts `roles` (e.g. just the
+  // "me" role) and returns only matching records; seq cursor semantics are
+  // unchanged (spec 009 T031).
+  'history-role-filter',
+  // history-scan-boundary: such a page also carries `scanBoundary` — the seq the
+  // scan actually reached — so a caller whose page was filtered empty can still
+  // advance instead of asking for the same stretch forever (spec 009 T039).
+  'history-scan-boundary',
 ]
 
 export function isHelloMethod(method) {

package/lib/history/filter-scan.js

@@ -0,0 +1,145 @@
+/**
+ * `_link/sessionWindow` 的**角色过滤**扫描（spec 016 的"来回次数"一条）。
+ *
+ * 为什么单独一条路径：未过滤的浏览翻页要的是"按 seq 精确的一段原始事件"，`readEvent`
+ * 一次 51 条正合适；但**按角色过滤**（"只看我的提问"灌库、只看工具/助手）时，命中往往很稀疏，
+ * 用 `readEvent` 就是"扫 12 块、每块 51 条、回 1 条"——实测一页 2.5–4.1 秒，而且随会话变长而变慢。
+ *
+ * 宿主另有一个按 seq 段过滤的接口（`sessionQuery.filterEvents`），**一次能覆盖 2000 个 seq**
+ * （实测 420–500 ms，约 0.22 ms/seq，而 `readEvent` 是 4.4 ms/seq），返回的是**消息类文档**
+ * （`user/message`、`assistant/message`、`tool/call`、`tool/result` 等），带 `seq` 与 `type`、
+ * `data.source`——足够判断角色。所以：
+ *
+ *   1. 用 `filterEvents` 按 2000 seq 的块从新到旧定位**命中的 seq**；
+ *   2. 把命中 seq 合并成 ≤51 宽的簇，**只对命中的那几簇** `readEvent` 取完整记录。
+ *
+ * 两点必须守住：
+ * - **对外语义不变**：本模块返回的形状与 `scanOlder` 完全一致（`events` / `truncatedBy` /
+ *   `clamped` / `exhausted` / `scannedFloor`），裁剪与分页仍由 `pageFrom` 一处决定。
+ * - **`scanBoundary` 的承诺不破**：没取回来的命中必须能被下一页重新扫到，所以提前收工时
+ *   `scannedFloor` 落在"真正取到的那一段"的最老 seq 上（见下）。
+ */
+
+import { MAX_CHUNKS_PER_CALL } from './records.js'
+
+/// 一个 `filterEvents` 块覆盖多少 seq。实测 2000 seq ≈ 420–500 ms（含宿主侧过滤）。
+export const FILTER_CHUNK = 2000
+
+/// 一次调用最多扫几个 `filterEvents` 块：6 × 2000 = 12000 seq。
+/// 取这个数是因为一块 ~0.5 s，六块 ~3 s，仍在宿主调用 8 s 预算内，且远小于一次超时。
+export const MAX_FILTER_CHUNKS_PER_CALL = 6
+
+/// 一次调用最多做几次"定向取完整记录"。命中稀疏时簇会多，这里封顶免得一次调用打太多来回。
+export const MAX_FILTER_READS_PER_CALL = 8
+
+/// `readEvent` 的 `before` 上限（宿主硬约束），一个簇因此最多覆盖 51 个 seq。
+const READ_SPAN = MAX_CHUNKS_PER_CALL === 12 ? 50 : 50
+
+/**
+ * 把命中 seq 合并成"一次 `readEvent` 能覆盖"的簇。
+ *
+ * 升序返回 `[{from, to}]`，每个簇宽度 ≤ 51（`to - from ≤ 50`），
+ * 这样 `readEvent({seq: to, before: 50})` 一定涵盖 `[from, to]`。
+ */
+export function clusterSeqs(seqs) {
+  const sorted = [...new Set(seqs)].sort((a, b) => a - b)
+  const clusters = []
+  for (const seq of sorted) {
+    const last = clusters[clusters.length - 1]
+    if (last !== undefined && seq - last.from <= READ_SPAN) last.to = seq
+    else clusters.push({ from: seq, to: seq })
+  }
+  return clusters
+}
+
+/**
+ * 角色过滤扫描。与 `scanOlder` 同形返回。
+ *
+ * @param {object} input
+ * @param {(sessionId: string, from: number, to: number) => Promise<{docs: Array, clamped?: boolean}>} input.readFilterChunk
+ * @param {(sessionId: string, seq: number) => Promise<{window: {events: Array}, clamped?: boolean}>} input.readRecords
+ * @param {string} input.sessionId
+ * @param {number} input.before 最新边界（不含）
+ * @param {number|undefined} input.through 下界（含）
+ * @param {number} input.limit 目标记录条数
+ * @param {Set<string>} input.roles 角色白名单
+ * @param {(doc: unknown) => string|undefined} input.roleOf 角色判定（与原始事件同一份口径）
+ *
+ * 字节预算不在这里裁：命中记录要取回来才知道大小，统一交给 `pageFrom`（它同时负责
+ * `truncatedBy='bytes'` 与 `scanBoundary` 的收口，与未过滤路径共用同一处规则）。
+ */
+export async function filteredScan({
+  readFilterChunk, readRecords, newestSeq, sessionId, before, through, limit, roles, roleOf,
+}) {
+  let cursor = Math.min(before - 1, through ?? Number.MAX_SAFE_INTEGER)
+  const matched = []
+  let truncatedBy = null
+  let clamped = false
+  let exhausted = false
+  let scannedFloor = null
+
+  // **必须自己 clamp**：`filterEvents` 对越界的 seq 段**不报错、只回空数组**（`readEvent` 会抛
+  // "has no event at seq"）。不 clamp 的后果实测过：某个日志只到 1208 的会话，App 传来的游标是
+  // 投影的 asOfSeq（101473），新路径于是扫了六段空区间、返回空页并把 `scanBoundary` 推到 89474，
+  // 调用方从这里往回读会**整段跳过**真实历史。`newestSeq` 与旧路径共用（会话内 5 秒缓存）。
+  if (typeof newestSeq === 'function') {
+    const newest = await newestSeq(sessionId)
+    if (Number.isInteger(newest) && newest >= 0 && cursor > newest) {
+      cursor = newest
+      clamped = true
+    }
+  }
+
+  if (cursor < 0) return { events: [], truncatedBy: null, clamped, exhausted: true, scannedFloor: 0 }
+
+  for (let chunk = 0; chunk < MAX_FILTER_CHUNKS_PER_CALL && cursor >= 0; chunk += 1) {
+    const from = Math.max(0, cursor - FILTER_CHUNK + 1)
+    const { docs = [], clamped: thisClamped } = await readFilterChunk(sessionId, from, cursor)
+    clamped = clamped || thisClamped === true
+    scannedFloor = scannedFloor === null ? from : Math.min(scannedFloor, from)
+    // 文档升序；从后往前插到队首，保持升序（与 scanOlder 同一手法）。
+    for (let index = docs.length - 1; index >= 0; index -= 1) {
+      const doc = docs[index]
+      if (!Number.isInteger(doc?.seq) || doc.seq < from || doc.seq > cursor) continue
+      if (!roles.has(roleOf(doc))) continue
+      matched.unshift(doc)
+    }
+    if (matched.length >= limit) { truncatedBy = 'count'; break }
+    const next = from - 1
+    if (next < 0) { exhausted = true; break }
+    cursor = next
+  }
+
+  // 命中 seq → 簇 → 只取命中那几簇的完整记录。簇太多时**只取最新的一段**，
+  // 并把 `scannedFloor` 收到这一段的最老 seq：下一页会从这里往回扫，丢掉的命中还能被重新找到
+  // （`pageFrom` 对过滤页用的正是 `scan.scannedFloor`）。
+  const all = clusterSeqs(matched.map((doc) => doc.seq))
+  const kept = all.slice(Math.max(0, all.length - MAX_FILTER_READS_PER_CALL))
+  const wanted = new Set(matched.map((doc) => doc.seq))
+  const events = []
+  for (const cluster of kept) {
+    const { window: result, clamped: thisClamped } = await readRecords(sessionId, cluster.to)
+    clamped = clamped || thisClamped === true
+    for (const event of Array.isArray(result?.events) ? result.events : []) {
+      // **必须同时卡簇边界**：相邻簇的 `readEvent` 窗口会重叠（`before: 50` 往前多取 50 个 seq），
+      // 只按 `wanted` 过滤会把上一个簇里的命中重复收进来（实测 48 号记录进了两页，两页并集少一条）。
+      if (event?.seq < cluster.from || event?.seq > cluster.to || !wanted.has(event.seq)) continue
+      // **角色必须用原始事件复判一次**，不能信文档的判定：宿主的 `filterEvents` 文档不带
+      // `data.source`（实测：`source.kind = "agent-instructions"` 的注入消息在 doc 路径下被判成
+      // `me`），而 `roleOf` 正是靠 `data.source` 才能把注入消息排除掉——spec 009 修过的那个
+      // "把 plugin 注入消息错算成提问"的缺陷（实测占比 24%）会由 doc 判定重新引入。
+      // 文档在这里只是"定位用的索引"，命中与否以原始事件为准。
+      if (roles !== undefined && !roles.has(roleOf(event))) continue
+      events.push(event)
+    }
+  }
+  events.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0))
+
+  if (all.length > kept.length) {
+    truncatedBy = truncatedBy ?? 'count'
+    exhausted = false
+    scannedFloor = kept.length > 0 ? kept[0].from : scannedFloor
+  }
+
+  return { events, truncatedBy, clamped, exhausted, scannedFloor }
+}

package/lib/history/records.js

@@ -0,0 +1,125 @@
+/**
+ * `_link/sessionWindow` / `_link/sessionFind` 共用的事件→记录件。
+ *
+ * 抽出来的理由与 `shared.js` 同一条（spec 007 T065）：窗口扫描、检索、探针三块
+ * 都要按角色归类事件、都要按字节预算裁剪，放在 `history.js` 里会把那个文件撑到
+ * 读不动，也确实漏过一次导入（`probe.js` 里 `bytesOf`/`summarizeEvents` 一直是
+ * 未定义的名字）。
+ *
+ * 这里只有纯函数：没有 IO、没有服务状态。
+ */
+
+/// Host hard cap: `readEvent` rejects `before > 50` (`before must be an integer
+/// between 0 and 50`). One chunk therefore yields at most 51 raw events.
+export const WINDOW_CHUNK = 50
+
+/// Defaults for one page. The phone may override both; the byte budget wins when
+/// they disagree (measured: 51 raw events can already be 253KB on a long session).
+export const DEFAULT_LIMIT = 60
+export const DEFAULT_MAX_BYTES = 256 * 1024
+
+/// Ceiling on how much one call reads, so a page request can never pin the
+/// connector's serial inbox (measured: ~30ms per chunk on a 2.3k session).
+export const MAX_CHUNKS_PER_CALL = 12
+
+export function bytesOf(value) {
+  try {
+    return Buffer.byteLength(JSON.stringify(value), 'utf8')
+  } catch {
+    return -1
+  }
+}
+
+export function summarizeEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return { count: 0, firstSeq: null, lastSeq: null, types: [] }
+  }
+  const types = [...new Set(events.map((event) => event?.type).filter(Boolean))].slice(0, 8)
+  return {
+    count: events.length,
+    firstSeq: events[0]?.seq ?? null,
+    lastSeq: events[events.length - 1]?.seq ?? null,
+    types,
+  }
+}
+
+export function toRecord(event) {
+  return { type: 'event', event }
+}
+
+/// 去掉一条记录里**只用于诊断、渲染不读**的宿主模型输出日志。
+///
+/// 口径只有一份，写在这里由三条回包路径共用（精确窗口 / 搜索 / 旧分页），
+/// 见 `specs/016-history-load-perf/contracts/history-record-trim.md`。
+///
+/// 为什么删：实测该字段占样本会话报文约 60%、占 assistant 记录 75.7%、
+/// 占手机侧解码耗时约 94%（`specs/016-history-load-perf/research.md` §0），
+/// 而产品路径没有任何消费者（`DSHKit` 里只有一句"不能拿它当流式判据"的注释）。
+///
+/// 两条纪律：
+/// - **不就地改写**：宿主回包可能仍被别处引用（测试与探针都会再看一眼），
+///   所以带该键时产生新的 `data` 对象，不带时按原对象返回（不复制、不白花时间）。
+/// - **只删这一个键**：`message` / `usage` / `meta` / `arguments` 等一律原样，
+///   删它们就是丢屏幕上要显示的内容。
+export function trimRecordForWire(record) {
+  const event = record?.event
+  const data = event?.data
+  if (data === null || typeof data !== 'object' || !('stream' in data)) return record
+  const { stream: _dropped, ...rest } = data
+  return { ...record, event: { ...event, data: rest } }
+}
+
+/// 一整页记录的同一条清洗（顺序与长度不变）。
+export function trimRecordsForWire(records) {
+  if (!Array.isArray(records)) return records
+  return records.map(trimRecordForWire)
+}
+
+export function bytesOfRecords(records) {
+  return bytesOf(records)
+}
+
+/// Drop the **oldest** end until the page fits. The newest edge must stay exact
+/// (it is the seq the phone's window abuts), so trimming only ever happens here.
+export function trimToBytes(records, maxBytes) {
+  let truncated = false
+  while (records.length > 1 && bytesOfRecords(records) > maxBytes) {
+    records.shift()
+    truncated = true
+  }
+  return truncated
+}
+
+/// Which of the three transcript roles one event belongs to (the phone's own
+/// `TranscriptSearchHit.Role`).
+///
+/// `user/message` only counts as **me** when the event really came from the
+/// user: measured on a real session, ~24% of `user/message` events are
+/// plugin/system injections (`data.source.kind` other than `"user"`), and
+/// agent-relayed ones carry a `data.source.rpcId` starting with `agent-`.
+/// Events with no `data.source` at all predate the marker and stay `me`
+/// (old-data compatibility). Non-`me` user messages return `undefined` —
+/// they remain visible to full-text search, they just never enter the
+/// "my questions" set (spec 009 T031).
+export function roleOf(event) {
+  const type = event?.type
+  if (type === 'user/message') {
+    const source = event?.data?.source
+    if (source !== undefined && source !== null && typeof source === 'object') {
+      if (source.kind !== undefined && source.kind !== 'user') return undefined
+      if (typeof source.rpcId === 'string' && source.rpcId.startsWith('agent-')) return undefined
+    }
+    return 'me'
+  }
+  if (type === 'assistant/message') return 'agent'
+  if (type === 'tool/call' || type === 'tool/result') return 'tool'
+  return undefined
+}
+
+/// What the search hit is *displayed* as. Injected/relayed user messages are
+/// not "me" for the curated set, but they are still user speech in full-text
+/// search (spec 009: excluded from "我的提问", not from the corpus), so an
+/// unfiltered search shows them under the user bucket.
+export function displayRoleOf(event) {
+  return roleOf(event) ?? (event?.type === 'user/message' ? 'me' : undefined)
+}

package/lib/history/session-snapshot.js

@@ -0,0 +1,119 @@
+/**
+ * 会话日志快照（spec 016 "来回次数"一条的第二步）。
+ *
+ * A1 把"扫描"从 `readEvent`（51 事件/块）换成 `filterEvents`（2000 seq/块）之后，单会话成本
+ * 仍停在"每条命中一次 `readEvent`"这道墙上：实测 163 条命中 ≈ 163 个簇 × ~225 ms ≈ 37 秒。
+ * 根因是宿主的**每次调用地板价**，不是扫描算法。
+ *
+ * 宿主另有一条 `readSession(sessionId)`：一次返回整份日志（2026-10-08 spike 实测 13k 会话
+ * 116–315 ms，冷会话可用、不激活 Agent）。于是"要全量用户输入"这件事的正确做法是：
+ *
+ *   1. 一个会话**读一次**整份日志；
+ *   2. 在连接器里按角色过滤（同一份 `roleOf` 口径）；
+ *   3. 之后这个会话的每一页都从这份快照出，**不再打宿主**。
+ *
+ * 三条护栏（都是防"为了省几次调用把进程拖垮"）：
+ * - **事件数上限**：超过 `MAX_EVENTS` 的会话不做快照，退回 A1 的分块路径（那些会话本来就少）。
+ * - **条目上限 + TTL**：同时只留 `MAX_ENTRIES` 份、`TTL_MS` 到期即弃。灌库是串行的、搜索面板是
+ *   单会话的，所以留一两份就够；过期即弃避免刚发出去的消息被旧快照盖住。
+ * - **失败即弃**：宿主没有这个接口、抛错、或返回形状不对，一律返回 undefined（调用方退回 A1）。
+ */
+
+import { bytesOfRecords, toRecord } from './records.js'
+
+/// 一份快照最多装多少条事件。超过就不快照（内存护栏）。
+export const SNAPSHOT_MAX_EVENTS = 20_000
+/// 同时留几份。灌库串行、面板单会话，两份足够覆盖"两台设备交替看"。
+export const SNAPSHOT_MAX_ENTRIES = 2
+/// 快照寿命（毫秒）。短一点，避免刚发出的提问被旧快照挡住。
+export const SNAPSHOT_TTL_MS = 90_000
+
+/**
+ * 建一个按会话的快照缓存。
+ *
+ * @param {object} input
+ * @param {(sessionId: string) => Promise<{events?: Array}>} input.readSession 宿主的整份读接口
+ * @param {() => number} [input.now]
+ */
+export function createSnapshotCache({
+  readSession, maxEvents = SNAPSHOT_MAX_EVENTS, maxEntries = SNAPSHOT_MAX_ENTRIES,
+  ttlMs = SNAPSHOT_TTL_MS, now = Date.now,
+} = {}) {
+  const entries = new Map()
+
+  return {
+    /** 命中且新鲜就返回；否则读一次；读不到/超限/形状不对一律 undefined。 */
+    async get(sessionId) {
+      const cached = entries.get(sessionId)
+      if (cached !== undefined && now() - cached.at < ttlMs) {
+        // LRU：命中后挪到队尾。
+        entries.delete(sessionId)
+        entries.set(sessionId, cached)
+        return cached
+      }
+      if (typeof readSession !== 'function') return undefined
+      let snapshot
+      try {
+        snapshot = await readSession(sessionId)
+      } catch {
+        return undefined
+      }
+      const events = snapshot?.events
+      if (!Array.isArray(events) || events.length > maxEvents) return undefined
+      const entry = {
+        events,
+        newestSeq: events.length > 0 ? events[events.length - 1].seq : -1,
+        at: now(),
+      }
+      entries.set(sessionId, entry)
+      while (entries.size > maxEntries) entries.delete(entries.keys().next().value)
+      return entry
+    },
+    invalidate(sessionId) { entries.delete(sessionId) },
+    get size() { return entries.size },
+  }
+}
+
+/**
+ * 从快照扫一页。**纯函数**，返回形状与 `scanOlder` / `filteredScan` 完全一致，
+ * 于是裁剪与分页仍然由 `pageFrom` 一处决定。
+ *
+ * 与分块路径的差别只在"看了多少"：快照里我们已经拥有整段，所以 `scannedFloor` 是**这段区间的
+ * 下界**（而不是"扫到第几块就停"），空页因此能一次推进到底。
+ */
+export function scanSnapshot(snapshot, { before, through, limit, maxBytes = 256 * 1024, roles, roleOf }) {
+  // `through` 与 `scanOlder` 同义：它只**封顶新边**（`cursor = min(before-1, through)`），
+  // 不是下界——扫描一律往下走到 seq 0。
+  const requested = Math.min(before - 1, through ?? Number.MAX_SAFE_INTEGER)
+  const newest = Number.isInteger(snapshot?.newestSeq) ? snapshot.newestSeq : -1
+  const clamped = requested > newest
+  const upper = clamped ? newest : requested
+  if (upper < 0) {
+    return { events: [], truncatedBy: null, clamped, exhausted: true, scannedFloor: 0 }
+  }
+  const matches = []
+  for (const event of snapshot.events ?? []) {
+    const seq = event?.seq
+    if (!Number.isInteger(seq) || seq > upper) continue
+    if (roles !== undefined && !roles.has(roleOf(event))) continue
+    matches.push(event)
+  }
+  matches.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0))
+
+  // **裁剪只由 `pageFrom` 一处做**（模块契约）：这里把区间内全部命中交出去，另给三个信号。
+  //
+  // `exhausted` 的含义与 `scanOlder` 对齐：它表示"这道区间里所有命中都交出去了、下面没有了"，
+  // 而不是"我看过整段"。不这么定就会出错：快照一次就能看到全部命中，若直接设 true，
+  // `pageFrom` 按条数裁掉一部分后会给出 `hasMore=false`，调用方停手，被裁掉的命中永远拿不到。
+  // 而 `scannedFloor` 保持 0（= 真下界）也只在"没被裁"时才被 `pageFrom` 当作 `scanBoundary`；
+  // 一旦裁剪发生，`pageFrom` 会改用页内最老记录，调用方据此续读，不重不漏。
+  const moreThanOnePage = matches.length > limit
+    || bytesOfRecords(matches.map(toRecord)) >= maxBytes
+  return {
+    events: matches,
+    truncatedBy: moreThanOnePage ? (matches.length > limit ? 'count' : 'bytes') : null,
+    clamped,
+    exhausted: !moreThanOnePage,
+    scannedFloor: 0,
+  }
+}

package/lib/history/shared.js

@@ -0,0 +1,25 @@
+/**
+ * `_link/sessionWindow` / `_link/sessionFind` 共用的小工具：调用上限、超时与错误文案。
+ *
+ * 抽出来的理由：这两个助手原先在 `history.js` 里，而窗口、检索、探针三块都要用；
+ * 放在这里可以让三块各自成文件（spec 007 T065）。
+ */
+
+/// Host-side call ceiling. The connector's inbox is serial, so one slow query
+/// would otherwise hold up every other frame on the tunnel.
+export const HOST_CALL_TIMEOUT_MS = 8000
+
+/// 包一层超时：连接器的入站链是**串行**的，一次不返回的宿主调用会卡住整条链。
+export function withTimeout(promise, ms, label) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+  })
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer))
+}
+
+export function messageOf(error) {
+  if (error === undefined || error === null) return 'unknown error'
+  if (typeof error === 'string') return error
+  return error.message ?? String(error)
+}