@tunnelbox/core 0.1.7 → 0.1.8

package/dist/index.js

@@ -116,6 +116,7 @@ var zh_CN_default = {
   "index.error.pairTimeout": "\u7B49\u5F85\u914D\u5BF9\u7801\u8D85\u65F6\uFF08\u4E2D\u7EE7\u672A\u54CD\u5E94\uFF09",
   "index.log.claimed": "\u5DF2\u7ED1\u5B9A\u5230\u624B\u673A\u8D26\u53F7\uFF0C\u4E4B\u540E\u624B\u673A\u4ECE\u300C\u6211\u7684\u7535\u8111\u300D\u76F4\u63A5\u8FDE\u63A5\uFF0C\u65E0\u9700\u518D\u626B\u7801",
   "index.log.connectedRelay": "\u5DF2\u8FDE\u63A5\u4E2D\u7EE7 {url}",
+  "index.log.loaded": "tunnelbox opencode \u63D2\u4EF6\u5DF2\u542F\u52A8\uFF08v{version}\uFF09",
   "index.log.disconnected": "\u4E0E\u4E2D\u7EE7\u65AD\u5F00\uFF0C\u6B63\u5728\u81EA\u52A8\u91CD\u8FDE\u2026",
   "index.log.exit": "\u5DF2\u9000\u51FA",
   "index.log.pairCode": "\u751F\u6210\u914D\u5BF9\u7801: {code}",
@@ -279,6 +280,7 @@ var zh_TW_default = {
   "index.error.pairTimeout": "\u7B49\u5F85\u914D\u5C0D\u78BC\u903E\u6642\uFF08\u4E2D\u7E7C\u672A\u56DE\u61C9\uFF09",
   "index.log.claimed": "\u5DF2\u7D81\u5B9A\u5230\u624B\u6A5F\u5E33\u865F\uFF0C\u4E4B\u5F8C\u624B\u6A5F\u76F4\u63A5\u5F9E\u300C\u6211\u7684\u96FB\u8166\u300D\u9023\u63A5\uFF0C\u4E0D\u9700\u518D\u6383\u78BC",
   "index.log.connectedRelay": "\u5DF2\u9023\u63A5\u4E2D\u7E7C {url}",
+  "index.log.loaded": "tunnelbox opencode \u5916\u639B\u5DF2\u555F\u52D5\uFF08v{version}\uFF09",
   "index.log.disconnected": "\u8207\u4E2D\u7E7C\u65B7\u7DDA\uFF0C\u6B63\u5728\u81EA\u52D5\u91CD\u9023\u2026",
   "index.log.exit": "\u5DF2\u9000\u51FA",
   "index.log.pairCode": "\u7522\u751F\u914D\u5C0D\u78BC: {code}",
@@ -442,6 +444,7 @@ var en_US_default = {
   "index.error.pairTimeout": "Timed out waiting for a pairing code (the relay did not respond)",
   "index.log.claimed": "Bound to your phone account. From now on the phone connects directly from My Computers; no need to scan again",
   "index.log.connectedRelay": "Connected to relay {url}",
+  "index.log.loaded": "tunnelbox opencode plugin started (v{version})",
   "index.log.disconnected": "Disconnected from relay, reconnecting automatically\u2026",
   "index.log.exit": "Exited",
   "index.log.pairCode": "Generated pairing code: {code}",
@@ -605,6 +608,7 @@ var ja_JP_default = {
   "index.error.pairTimeout": "\u30DA\u30A2\u30EA\u30F3\u30B0\u30B3\u30FC\u30C9\u306E\u53D6\u5F97\u304C\u30BF\u30A4\u30E0\u30A2\u30A6\u30C8\u3057\u307E\u3057\u305F\uFF08\u30EA\u30EC\u30FC\u304C\u5FDC\u7B54\u3057\u307E\u305B\u3093\uFF09",
   "index.log.claimed": "\u30B9\u30DE\u30DB\u306E\u30A2\u30AB\u30A6\u30F3\u30C8\u306B\u7D10\u4ED8\u3051\u307E\u3057\u305F\u3002\u4EE5\u964D\u306F\u300C\u30DE\u30A4 PC\u300D\u304B\u3089\u76F4\u63A5\u63A5\u7D9A\u3055\u308C\u308B\u305F\u3081\u3001\u518D\u30B9\u30AD\u30E3\u30F3\u306F\u4E0D\u8981\u3067\u3059",
   "index.log.connectedRelay": "\u30EA\u30EC\u30FC\u306B\u63A5\u7D9A\u3057\u307E\u3057\u305F {url}",
+  "index.log.loaded": "tunnelbox opencode \u30D7\u30E9\u30B0\u30A4\u30F3\u3092\u8D77\u52D5\u3057\u307E\u3057\u305F\uFF08v{version}\uFF09",
   "index.log.disconnected": "\u30EA\u30EC\u30FC\u304B\u3089\u5207\u65AD\u3001\u81EA\u52D5\u7684\u306B\u518D\u63A5\u7D9A\u3057\u3066\u3044\u307E\u3059\u2026",
   "index.log.exit": "\u7D42\u4E86\u3057\u307E\u3057\u305F",
   "index.log.pairCode": "\u30DA\u30A2\u30EA\u30F3\u30B0\u30B3\u30FC\u30C9\u3092\u751F\u6210: {code}",
@@ -768,6 +772,7 @@ var ko_KR_default = {
   "index.error.pairTimeout": "\uD398\uC5B4\uB9C1 \uCF54\uB4DC \uB300\uAE30 \uC2DC\uAC04 \uCD08\uACFC(\uB9B4\uB808\uC774\uAC00 \uC751\uB2F5\uD558\uC9C0 \uC54A\uC74C)",
   "index.log.claimed": "\uD734\uB300\uD3F0 \uACC4\uC815\uC5D0 \uC5F0\uACB0\uB418\uC5C8\uC2B5\uB2C8\uB2E4. \uC774\uC81C \uD734\uB300\uD3F0\uC740 \u300C\uB0B4 PC\u300D\uC5D0\uC11C \uC9C1\uC811 \uC5F0\uACB0\uD558\uBA70 \uB2E4\uC2DC \uC2A4\uCE94\uD560 \uD544\uC694\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4",
   "index.log.connectedRelay": "\uB9B4\uB808\uC774\uC5D0 \uC5F0\uACB0\uB428 {url}",
+  "index.log.loaded": "tunnelbox opencode \uD50C\uB7EC\uADF8\uC778\uC744 \uC2DC\uC791\uD588\uC2B5\uB2C8\uB2E4\uFF08v{version}\uFF09",
   "index.log.disconnected": "\uB9B4\uB808\uC774 \uC5F0\uACB0\uC774 \uB04A\uACA8 \uC790\uB3D9\uC73C\uB85C \uC7AC\uC5F0\uACB0 \uC911\u2026",
   "index.log.exit": "\uC885\uB8CC\uB428",
   "index.log.pairCode": "\uD398\uC5B4\uB9C1 \uCF54\uB4DC \uC0DD\uC131: {code}",
@@ -931,6 +936,7 @@ var fr_FR_default = {
   "index.error.pairTimeout": "D\xE9lai d'attente du code d'appairage d\xE9pass\xE9 (le relais ne r\xE9pond pas)",
   "index.log.claimed": "Li\xE9 \xE0 votre compte t\xE9l\xE9phone. Le t\xE9l\xE9phone se connecte d\xE9sormais directement depuis \xAB Mes PC \xBB ; plus besoin de scanner",
   "index.log.connectedRelay": "Connect\xE9 au relais {url}",
+  "index.log.loaded": "Plugin tunnelbox opencode d\xE9marr\xE9 (v{version})",
   "index.log.disconnected": "D\xE9connect\xE9 du relais, reconnexion automatique\u2026",
   "index.log.exit": "Arr\xEAt\xE9",
   "index.log.pairCode": "Code d'appairage g\xE9n\xE9r\xE9 : {code}",
@@ -1094,6 +1100,7 @@ var de_DE_default = {
   "index.error.pairTimeout": "Zeit\xFCberschreitung beim Warten auf einen Pairing-Code (Relay antwortet nicht)",
   "index.log.claimed": "An Ihr Telefonkonto gebunden. Das Telefon verbindet sich nun direkt \xFCber \u201CMeine PCs\u201D; kein erneutes Scannen n\xF6tig",
   "index.log.connectedRelay": "Mit Relay verbunden {url}",
+  "index.log.loaded": "tunnelbox-opencode-Plugin gestartet (v{version})",
   "index.log.disconnected": "Vom Relay getrennt, verbinde automatisch neu\u2026",
   "index.log.exit": "Beendet",
   "index.log.pairCode": "Pairing-Code erzeugt: {code}",
@@ -1257,6 +1264,7 @@ var es_ES_default = {
   "index.error.pairTimeout": "Tiempo de espera agotado al obtener el c\xF3digo de emparejamiento (el relay no responde)",
   "index.log.claimed": "Vinculado a su cuenta de tel\xE9fono. El tel\xE9fono se conecta ahora directamente desde \xABMis PC\xBB; no hace falta volver a escanear",
   "index.log.connectedRelay": "Conectado al relay {url}",
+  "index.log.loaded": "Plugin tunnelbox opencode iniciado (v{version})",
   "index.log.disconnected": "Desconectado del relay, reconectando autom\xE1ticamente\u2026",
   "index.log.exit": "Salido",
   "index.log.pairCode": "C\xF3digo de emparejamiento generado: {code}",
@@ -1609,20 +1617,127 @@ async function printPairing(code, type, name, lang) {
   console.log("  " + tt("qr.fileWritten", { path: file }));
   console.log("");
 }
+
+// src/messages.ts
+var DEFAULT_PAGE_SIZE = 50;
+var MAX_PART_TEXT = 16e3;
+var MAX_PART_ARGS = 4e3;
+var MAX_PAGE_BYTES = 15e5;
+function capStr(s, max) {
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}\u2026`;
+}
+function capMessage(m) {
+  let parts;
+  for (let i = 0; i < m.parts.length; i++) {
+    const p = m.parts[i];
+    const nText = typeof p.text === "string" && p.text.length > MAX_PART_TEXT ? capStr(p.text, MAX_PART_TEXT) : p.text;
+    const nDelta = typeof p.delta === "string" && p.delta.length > MAX_PART_TEXT ? capStr(p.delta, MAX_PART_TEXT) : p.delta;
+    const nArgs = typeof p.args === "string" && p.args.length > MAX_PART_ARGS ? capStr(p.args, MAX_PART_ARGS) : p.args;
+    if (nText !== p.text || nDelta !== p.delta || nArgs !== p.args) {
+      if (!parts) parts = m.parts.slice(0, i);
+      parts.push({ ...p, text: nText, delta: nDelta, args: nArgs });
+    } else if (parts) {
+      parts.push(p);
+    }
+  }
+  return parts ? { ...m, parts } : m;
+}
+function capMessages(messages) {
+  let changed = false;
+  const out = messages.map((m) => {
+    const c = capMessage(m);
+    if (c !== m) changed = true;
+    return c;
+  });
+  return changed ? out : messages;
+}
+function byteLength(messages) {
+  try {
+    return JSON.stringify(messages).length;
+  } catch {
+    return messages.length * MAX_PART_TEXT * 2;
+  }
+}
+function sliceWindow(full, query = {}) {
+  const limit = Math.max(1, query.limit ?? DEFAULT_PAGE_SIZE);
+  const maxBytes = query.maxBytes ?? MAX_PAGE_BYTES;
+  let end = full.length;
+  if (query.before !== void 0 && query.before !== "") {
+    const idx = full.findIndex((m) => m.id === query.before);
+    if (idx >= 0) end = idx;
+  }
+  let start = Math.max(0, end - limit);
+  let messages = full.slice(start, end);
+  while (messages.length > 1) {
+    const capped = capMessages(messages);
+    if (byteLength(capped) <= maxBytes) {
+      messages = capped;
+      break;
+    }
+    start++;
+    messages = full.slice(start, end);
+  }
+  return { messages: capMessages(messages), hasMore: start > 0 };
+}
+var MessagesCache = class {
+  ttlMs;
+  maxEntries;
+  store = /* @__PURE__ */ new Map();
+  constructor(ttlMs = 2e3, maxEntries = 64) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+  /** 命中且未过 TTL 时返回完整列表副本；否则 undefined。 */
+  get(sessionID, now = Date.now()) {
+    const e = this.store.get(sessionID);
+    if (!e) return void 0;
+    if (now - e.at > this.ttlMs) {
+      this.store.delete(sessionID);
+      return void 0;
+    }
+    return e.full;
+  }
+  put(sessionID, full) {
+    if (this.store.size >= this.maxEntries && !this.store.has(sessionID)) {
+      const oldest = this.store.keys().next().value;
+      if (oldest !== void 0) this.store.delete(oldest);
+    }
+    this.store.set(sessionID, { full, at: Date.now() });
+  }
+  /** 会话内容变化（流式部件/状态/删除等）时调用，立即失效快照。 */
+  invalidate(sessionID) {
+    this.store.delete(sessionID);
+  }
+  /** 适配器重连/整体失效（如清除全部快照）。 */
+  clear() {
+    this.store.clear();
+  }
+};
+var messagesCache = new MessagesCache();
 export {
   DEFAULT_LANG,
+  DEFAULT_PAGE_SIZE,
   LANG_TAGS,
+  MAX_PAGE_BYTES,
+  MAX_PART_ARGS,
+  MAX_PART_TEXT,
+  MessagesCache,
   RelayClient,
+  capMessage,
+  capMessages,
   detectSystemLang,
   envelope,
   injectedRelayUrl,
   loadState,
   makeT,
+  messagesCache,
   normalizeLang,
   printPairing,
   renderPairingQrText,
   resolveLang,
   saveState,
+  sliceWindow,
   statePath,
   t,
   writePairingFile,

package/locales/de-DE.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "Zeitüberschreitung beim Warten auf einen Pairing-Code (Relay antwortet nicht)",
   "index.log.claimed": "An Ihr Telefonkonto gebunden. Das Telefon verbindet sich nun direkt über “Meine PCs”; kein erneutes Scannen nötig",
   "index.log.connectedRelay": "Mit Relay verbunden {url}",
+  "index.log.loaded": "tunnelbox-opencode-Plugin gestartet (v{version})",
   "index.log.disconnected": "Vom Relay getrennt, verbinde automatisch neu…",
   "index.log.exit": "Beendet",
   "index.log.pairCode": "Pairing-Code erzeugt: {code}",

package/locales/en-US.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "Timed out waiting for a pairing code (the relay did not respond)",
   "index.log.claimed": "Bound to your phone account. From now on the phone connects directly from My Computers; no need to scan again",
   "index.log.connectedRelay": "Connected to relay {url}",
+  "index.log.loaded": "tunnelbox opencode plugin started (v{version})",
   "index.log.disconnected": "Disconnected from relay, reconnecting automatically…",
   "index.log.exit": "Exited",
   "index.log.pairCode": "Generated pairing code: {code}",

package/locales/es-ES.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "Tiempo de espera agotado al obtener el código de emparejamiento (el relay no responde)",
   "index.log.claimed": "Vinculado a su cuenta de teléfono. El teléfono se conecta ahora directamente desde «Mis PC»; no hace falta volver a escanear",
   "index.log.connectedRelay": "Conectado al relay {url}",
+  "index.log.loaded": "Plugin tunnelbox opencode iniciado (v{version})",
   "index.log.disconnected": "Desconectado del relay, reconectando automáticamente…",
   "index.log.exit": "Salido",
   "index.log.pairCode": "Código de emparejamiento generado: {code}",

package/locales/fr-FR.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "Délai d'attente du code d'appairage dépassé (le relais ne répond pas)",
   "index.log.claimed": "Lié à votre compte téléphone. Le téléphone se connecte désormais directement depuis « Mes PC » ; plus besoin de scanner",
   "index.log.connectedRelay": "Connecté au relais {url}",
+  "index.log.loaded": "Plugin tunnelbox opencode démarré (v{version})",
   "index.log.disconnected": "Déconnecté du relais, reconnexion automatique…",
   "index.log.exit": "Arrêté",
   "index.log.pairCode": "Code d'appairage généré : {code}",

package/locales/ja-JP.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "ペアリングコードの取得がタイムアウトしました（リレーが応答しません）",
   "index.log.claimed": "スマホのアカウントに紐付けました。以降は「マイ PC」から直接接続されるため、再スキャンは不要です",
   "index.log.connectedRelay": "リレーに接続しました {url}",
+  "index.log.loaded": "tunnelbox opencode プラグインを起動しました（v{version}）",
   "index.log.disconnected": "リレーから切断、自動的に再接続しています…",
   "index.log.exit": "終了しました",
   "index.log.pairCode": "ペアリングコードを生成: {code}",

package/locales/ko-KR.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "페어링 코드 대기 시간 초과(릴레이가 응답하지 않음)",
   "index.log.claimed": "휴대폰 계정에 연결되었습니다. 이제 휴대폰은 「내 PC」에서 직접 연결하며 다시 스캔할 필요가 없습니다",
   "index.log.connectedRelay": "릴레이에 연결됨 {url}",
+  "index.log.loaded": "tunnelbox opencode 플러그인을 시작했습니다（v{version}）",
   "index.log.disconnected": "릴레이 연결이 끊겨 자동으로 재연결 중…",
   "index.log.exit": "종료됨",
   "index.log.pairCode": "페어링 코드 생성: {code}",

package/locales/zh-CN.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "等待配对码超时（中继未响应）",
   "index.log.claimed": "已绑定到手机账号，之后手机从「我的电脑」直接连接，无需再扫码",
   "index.log.connectedRelay": "已连接中继 {url}",
+  "index.log.loaded": "tunnelbox opencode 插件已启动（v{version}）",
   "index.log.disconnected": "与中继断开，正在自动重连…",
   "index.log.exit": "已退出",
   "index.log.pairCode": "生成配对码: {code}",

package/locales/zh-TW.json

@@ -18,6 +18,7 @@
   "index.error.pairTimeout": "等待配對碼逾時（中繼未回應）",
   "index.log.claimed": "已綁定到手機帳號，之後手機直接從「我的電腦」連接，不需再掃碼",
   "index.log.connectedRelay": "已連接中繼 {url}",
+  "index.log.loaded": "tunnelbox opencode 外掛已啟動（v{version}）",
   "index.log.disconnected": "與中繼斷線，正在自動重連…",
   "index.log.exit": "已退出",
   "index.log.pairCode": "產生配對碼: {code}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tunnelbox/core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "tunnelbox 共享核心：协议类型、中继客户端、状态持久化、二维码配对",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./state";
 export * from "./env";
 export * from "./qr";
 export * from "./i18n";
+export * from "./messages";

package/src/messages.ts

@@ -0,0 +1,171 @@
+/**
+ * 会话消息快照缓存与分页窗口工具（各智能体适配器共享）。
+ *
+ * 背景：拉取历史（session.messages）在部分适配器开销可观——opencode 会对整段会话做
+ * 全量 hydrate、claude-code 需读盘解析 transcript；手机端蜂窝环境下还要把整份 JSON
+ * 经 WS 下发并一次性渲染。两点缓解：
+ *  1. 分页窗口：应答按 [before, limit] 只下发最近的 N 条，过长历史由手机端"滚动到顶
+ *     加载更早"再拉；构建出完整列表后切片（构建仍是最重一步，缓存命中可完全跳过）。
+ *  2. 短 TTL 快照：对重复/快速回看的打开直接从缓存切片，避免重复构建。快照在流式事件
+ *     （message.part / session.status 等）到达时由适配器 invalidate，保证不长期陈旧。
+ *
+ * 消息数组统一约定为**时间升序（旧 → 新）**，与手机端展示顺序一致。
+ *
+ * 3. 载荷上界：超长会话/超大单条内容可能把一帧 push 撑到 relay 的连接读上限
+ *    （旧 relay 4MB）而被误判断开。sliceWindow 统一在返回前截断单条文本/参数长度，
+ *    并做**字节预算**——超预算从窗口更旧侧继续裁剪（保留最新，缺口可经 before 续拉，
+ *    不丢内容），保证任何应答帧稳定远小于连接上限。截断只影响手机端展示。
+ */
+import type { ChatMessage, Part } from "./types";
+
+/** 单页默认条数（手机端首屏展示窗口）。 */
+export const DEFAULT_PAGE_SIZE = 50;
+
+/** 单条 part 文本（text/thinking）展示上限（字符）。 */
+export const MAX_PART_TEXT = 16000;
+/** 单条 tool 参数展示上限（字符）。 */
+export const MAX_PART_ARGS = 4000;
+/** 单页串行化字节预算：预留明显余量，确保帧远小于 relay 连接读上限（4MB/32MB）。 */
+export const MAX_PAGE_BYTES = 1_500_000;
+
+export interface MessagesPageQuery {
+  /** 游标：只返回早于该消息 id 的更早消息（第一页不传）。 */
+  before?: string;
+  /** 每页条数（缺省 DEFAULT_PAGE_SIZE）。 */
+  limit?: number;
+  /** 字节预算（缺省 MAX_PAGE_BYTES）。 */
+  maxBytes?: number;
+}
+
+export interface MessagesPageResult {
+  sessionID: string;
+  messages: ChatMessage[];
+  /** 更早历史是否仍存在（手机端据此决定是否继续"加载更早"）。 */
+  hasMore?: boolean;
+}
+
+function capStr(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…`;
+}
+
+/** 截断单条消息内过大部件（返回新对象；未超限原样返回）。只影响手机端展示体积。 */
+export function capMessage(m: ChatMessage): ChatMessage {
+  let parts: Part[] | undefined;
+  for (let i = 0; i < m.parts.length; i++) {
+    const p = m.parts[i];
+    const nText =
+      typeof p.text === "string" && p.text.length > MAX_PART_TEXT
+        ? capStr(p.text, MAX_PART_TEXT)
+        : p.text;
+    const nDelta =
+      typeof p.delta === "string" && p.delta.length > MAX_PART_TEXT
+        ? capStr(p.delta, MAX_PART_TEXT)
+        : p.delta;
+    const nArgs =
+      typeof p.args === "string" && p.args.length > MAX_PART_ARGS
+        ? capStr(p.args, MAX_PART_ARGS)
+        : p.args;
+    if (nText !== p.text || nDelta !== p.delta || nArgs !== p.args) {
+      if (!parts) parts = m.parts.slice(0, i);
+      parts.push({ ...p, text: nText, delta: nDelta, args: nArgs });
+    } else if (parts) {
+      parts.push(p);
+    }
+  }
+  return parts ? { ...m, parts } : m;
+}
+
+/** 整批截断（仅对确有超限的条目重建，避免无谓分配）。 */
+export function capMessages(messages: ChatMessage[]): ChatMessage[] {
+  let changed = false;
+  const out = messages.map((m) => {
+    const c = capMessage(m);
+    if (c !== m) changed = true;
+    return c;
+  });
+  return changed ? out : messages;
+}
+
+function byteLength(messages: ChatMessage[]): number {
+  try {
+    return JSON.stringify(messages).length;
+  } catch {
+    // 循环引用等异常兜底：按上限放大估算，防止误超
+    return messages.length * MAX_PART_TEXT * 2;
+  }
+}
+
+/** 在完整（升序）消息列表上切出目标窗口：截断超大内容 + 字节预算裁剪最旧侧。 */
+export function sliceWindow(
+  full: ChatMessage[],
+  query: MessagesPageQuery = {},
+): Pick<MessagesPageResult, "messages" | "hasMore"> {
+  const limit = Math.max(1, query.limit ?? DEFAULT_PAGE_SIZE);
+  const maxBytes = query.maxBytes ?? MAX_PAGE_BYTES;
+  let end = full.length;
+  if (query.before !== undefined && query.before !== "") {
+    const idx = full.findIndex((m) => m.id === query.before);
+    // 游标消息本身不含在内；找不到（已被清理/不一致）时回退整段，避免丢消息。
+    if (idx >= 0) end = idx;
+  }
+  let start = Math.max(0, end - limit);
+  let messages = full.slice(start, end);
+  // 先按条数取窗口，再在「截断后」体积上做预算：超出才从最旧侧继续裁剪
+  // （单条超大内容经 cap 已大幅缩小，避免按原始长度过度裁剪）。
+  while (messages.length > 1) {
+    const capped = capMessages(messages);
+    if (byteLength(capped) <= maxBytes) {
+      messages = capped;
+      break;
+    }
+    start++;
+    messages = full.slice(start, end);
+  }
+  return { messages: capMessages(messages), hasMore: start > 0 };
+}
+
+/** 会话消息快照缓存：仅缓存**完整列表**（窗口切片在各请求时现算）。 */
+export class MessagesCache {
+  private ttlMs: number;
+  private maxEntries: number;
+  private store = new Map<string, { full: ChatMessage[]; at: number }>();
+
+  constructor(ttlMs = 2000, maxEntries = 64) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+
+  /** 命中且未过 TTL 时返回完整列表副本；否则 undefined。 */
+  get(sessionID: string, now = Date.now()): ChatMessage[] | undefined {
+    const e = this.store.get(sessionID);
+    if (!e) return undefined;
+    if (now - e.at > this.ttlMs) {
+      this.store.delete(sessionID);
+      return undefined;
+    }
+    return e.full;
+  }
+
+  put(sessionID: string, full: ChatMessage[]): void {
+    if (this.store.size >= this.maxEntries && !this.store.has(sessionID)) {
+      // 简单 FIFO 淘汰最旧条目，防内存膨胀
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) this.store.delete(oldest);
+    }
+    this.store.set(sessionID, { full, at: Date.now() });
+  }
+
+  /** 会话内容变化（流式部件/状态/删除等）时调用，立即失效快照。 */
+  invalidate(sessionID: string): void {
+    this.store.delete(sessionID);
+  }
+
+  /** 适配器重连/整体失效（如清除全部快照）。 */
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+/** 共享会话消息快照缓存（各适配器复用同一实例）。 */
+export const messagesCache = new MessagesCache();

package/src/types.ts

@@ -142,6 +142,25 @@ export interface CommandInfo {
   description?: string;
 }
 
+/**
+ * 会话消息分页拉取请求（session.messages）：
+ * - 缺省（无 before）：返回最近 limit 条（首屏）；
+ * - before：返回早于该消息 id 的更早 limit 条（滚动到顶"加载更早"）。
+ */
+export interface SessionMessagesQuery {
+  sessionID: string;
+  before?: string;
+  limit?: number;
+}
+
+/** 会话消息应答（messages）：hasMore 用于手机端分页续拉（游标由手机端取已加载最旧一条的 id）。 */
+export interface SessionMessagesReply {
+  sessionID: string;
+  messages: ChatMessage[];
+  /** 更早历史是否仍存在（缺省 false）。 */
+  hasMore?: boolean;
+}
+
 /** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
 export interface AgentClaimedMessage {
   email?: string;