@co0ontty/wand 1.64.1 → 1.65.0-beta.g14437f5

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "83d24814b236f60f1a44a92e5b894985bb34b956",
-  "builtAt": "2026-06-14T14:27:59.151Z",
-  "version": "1.64.1",
-  "channel": "stable"
+  "commit": "14437f5d049c70494f90239e85b16479d05dbf1d",
+  "builtAt": "2026-06-15T03:26:09.437Z",
+  "version": "1.65.0-beta.g14437f5",
+  "channel": "beta"
 }

package/dist/message-truncator.d.ts

@@ -3,13 +3,22 @@
  * Cards that are collapsed by default have their large results replaced
  * with a summary, and clients fetch full content on-demand via API.
  */
-import type { CardExpandDefaults, ConversationTurn } from "./types.js";
+import type { CardExpandDefaults, ContentBlock, ConversationTurn } from "./types.js";
 /**
  * 默认窗口大小：init/resync/快照/REST 默认只下发最近这么多条 turn，更早的由客户端
  * 滚动到顶时按需分页拉取。移动端 WebSocket 单帧上限（iOS 默认 1 MiB）下，长会话一次
  * 全量下发会撑爆帧导致反复断连——窗口化是根治手段，64MB 提帧只是兜底。
  */
 export declare const MESSAGE_WINDOW_SIZE = 40;
+/**
+ * 块级窗口的默认预算：init/REST 默认只下发最近这么多个「内容块」（跨 turn 累计，
+ * 必要时切掉最旧那条 turn 的头部），更早的块由客户端滚动到顶时按需分页拉取。
+ * turn 级窗口（MESSAGE_WINDOW_SIZE）对「单条 turn 携带上百块」的长任务无能为力——
+ * 一条流式 assistant turn 可膨胀到 1MB+，整条下发会撑爆移动端 WS 帧、拖慢打开。
+ * 块级窗口是对这种会话的根治手段。仅在客户端显式带 blockBudget 时启用（iOS），
+ * Web/Android 走原有 turn 级路径不受影响。
+ */
+export declare const MESSAGE_BLOCK_WINDOW = 60;
 export interface WindowedMessages {
     /** 已截断 + 窗口化后的 turn 列表（最近 windowSize 条）。 */
     messages: ConversationTurn[];
@@ -18,6 +27,24 @@ export interface WindowedMessages {
     /** 完整历史的 turn 总数（客户端据此判断是否还有更早的可加载）。 */
     messageTotal: number;
 }
+export interface BlockWindowedMessages extends WindowedMessages {
+    /** messages[0] 被切掉的头部块数（0 表示该 turn 完整；>0 表示其更早的块需翻页）。 */
+    leadingBlockOffset: number;
+    /** turn messageOffset 的完整块数（客户端据此判断该 turn 是否已全部加载）。 */
+    leadingBlockTotal: number;
+}
+/**
+ * 块级窗口：取完整历史「最近 blockBudget 个内容块」并做 transport 截断。
+ * 从最新 turn 往回累计块数，能整条放下就整条放，放不下的那条（最旧的入窗 turn）
+ * 只取其尾部若干块，并通过 leadingBlockOffset 告知客户端「这条 turn 还有更早的块」。
+ * 客户端先按块翻完这条 turn 的头部，再按 turn 往前翻更早的整条。
+ */
+export declare function blockWindowMessagesForTransport(all: ConversationTurn[] | undefined, cardDefaults: CardExpandDefaults, blockBudget?: number): BlockWindowedMessages;
+/**
+ * 块级翻页：取某条 turn 的 content[start, end) 这一段（已做 transport 截断）。
+ * 客户端滚动到顶、且当前最旧 turn 仍有更早块时调用，end = 客户端当前 leadingBlockOffset。
+ */
+export declare function sliceTurnBlocksForTransport(turn: ConversationTurn, start: number, end: number, cardDefaults: CardExpandDefaults): ContentBlock[];
 /**
  * 取完整历史的「最近 windowSize 条」并对其做 transport 截断，附带 offset/total 元数据。
  * 客户端持有的永远是一段连续的「后缀」（最近的若干条），更早的按 offset 往前翻页。

package/dist/message-truncator.js

@@ -11,6 +11,89 @@ const SUMMARY_LENGTH = 100;
  * 全量下发会撑爆帧导致反复断连——窗口化是根治手段，64MB 提帧只是兜底。
  */
 export const MESSAGE_WINDOW_SIZE = 40;
+/**
+ * 块级窗口的默认预算：init/REST 默认只下发最近这么多个「内容块」（跨 turn 累计，
+ * 必要时切掉最旧那条 turn 的头部），更早的块由客户端滚动到顶时按需分页拉取。
+ * turn 级窗口（MESSAGE_WINDOW_SIZE）对「单条 turn 携带上百块」的长任务无能为力——
+ * 一条流式 assistant turn 可膨胀到 1MB+，整条下发会撑爆移动端 WS 帧、拖慢打开。
+ * 块级窗口是对这种会话的根治手段。仅在客户端显式带 blockBudget 时启用（iOS），
+ * Web/Android 走原有 turn 级路径不受影响。
+ */
+export const MESSAGE_BLOCK_WINDOW = 60;
+/**
+ * 块级窗口：取完整历史「最近 blockBudget 个内容块」并做 transport 截断。
+ * 从最新 turn 往回累计块数，能整条放下就整条放，放不下的那条（最旧的入窗 turn）
+ * 只取其尾部若干块，并通过 leadingBlockOffset 告知客户端「这条 turn 还有更早的块」。
+ * 客户端先按块翻完这条 turn 的头部，再按 turn 往前翻更早的整条。
+ */
+export function blockWindowMessagesForTransport(all, cardDefaults, blockBudget = MESSAGE_BLOCK_WINDOW) {
+    const turns = all ?? [];
+    const total = turns.length;
+    if (total === 0) {
+        return { messages: [], messageOffset: 0, messageTotal: 0, leadingBlockOffset: 0, leadingBlockTotal: 0 };
+    }
+    const budget = Math.max(1, blockBudget);
+    let startTurn = total - 1;
+    let leadingBlockOffset = 0;
+    let acc = 0;
+    for (let i = total - 1; i >= 0; i--) {
+        const n = turns[i].content.length;
+        if (i === total - 1) {
+            // 最新一条 turn 必须入窗：整条放得下就整条，放不下取尾部 budget 块。
+            if (n <= budget) {
+                acc = n;
+                startTurn = i;
+                leadingBlockOffset = 0;
+            }
+            else {
+                startTurn = i;
+                leadingBlockOffset = n - budget;
+                acc = budget;
+                break;
+            }
+        }
+        else if (acc + n <= budget) {
+            acc += n;
+            startTurn = i;
+            leadingBlockOffset = 0;
+        }
+        else {
+            const remaining = budget - acc;
+            if (remaining > 0) {
+                startTurn = i;
+                leadingBlockOffset = n - remaining;
+                acc += remaining;
+            }
+            break;
+        }
+    }
+    const windowedTurns = [];
+    for (let i = startTurn; i < total; i++) {
+        if (i === startTurn && leadingBlockOffset > 0) {
+            windowedTurns.push({ ...turns[i], content: turns[i].content.slice(leadingBlockOffset) });
+        }
+        else {
+            windowedTurns.push(turns[i]);
+        }
+    }
+    return {
+        messages: truncateMessagesForTransport(windowedTurns, cardDefaults),
+        messageOffset: startTurn,
+        messageTotal: total,
+        leadingBlockOffset,
+        leadingBlockTotal: turns[startTurn].content.length,
+    };
+}
+/**
+ * 块级翻页：取某条 turn 的 content[start, end) 这一段（已做 transport 截断）。
+ * 客户端滚动到顶、且当前最旧 turn 仍有更早块时调用，end = 客户端当前 leadingBlockOffset。
+ */
+export function sliceTurnBlocksForTransport(turn, start, end, cardDefaults) {
+    const blocks = turn.content.slice(start, end);
+    if (blocks.length === 0)
+        return [];
+    return truncateMessagesForTransport([{ ...turn, content: blocks }], cardDefaults)[0].content;
+}
 /**
  * 取完整历史的「最近 windowSize 条」并对其做 transport 截断，附带 offset/total 元数据。
  * 客户端持有的永远是一段连续的「后缀」（最近的若干条），更早的按 offset 往前翻页。

package/dist/server-session-routes.js

@@ -1,7 +1,7 @@
 import express from "express";
 import { SessionInputError } from "./process-manager.js";
 import { normalizeMode } from "./config.js";
-import { truncateMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
+import { blockWindowMessagesForTransport, sliceTurnBlocksForTransport, truncateMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
 import { checkSessionWorktreeMergeability, cleanupSessionWorktree, getWorktreeMergeErrorCode, mergeSessionWorktree, WorktreeMergeError } from "./git-worktree.js";
 import { getGitStatus, QuickCommitError, runQuickCommit, runTagHead, runPush, generateCommitMessageOnly, } from "./git-quick-commit.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -599,6 +599,22 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             ? processes.getPtyTranscript(snapshot.id) ?? snapshot.output
             : snapshot.output;
         if (req.query.format === "chat") {
+            // 客户端带 blockBudget（iOS）走块级窗口：只回最近 N 个块（必要时切掉最旧 turn 的头部），
+            // 根治「单条 turn 上百块/1MB」的长任务打开慢。Web/Android 不带该参数，走原 turn 级窗口。
+            const rawBudget = parseInt(String(req.query.blockBudget ?? ""), 10);
+            if (Number.isFinite(rawBudget) && rawBudget > 0) {
+                const windowed = blockWindowMessagesForTransport(snapshot.messages ?? [], config.cardDefaults ?? {}, rawBudget);
+                res.json({
+                    ...snapshot,
+                    output: transcriptOutput,
+                    messages: windowed.messages,
+                    messageOffset: windowed.messageOffset,
+                    messageTotal: windowed.messageTotal,
+                    leadingBlockOffset: windowed.leadingBlockOffset,
+                    leadingBlockTotal: windowed.leadingBlockTotal,
+                });
+                return;
+            }
             // 与 WS init 对齐：只回最近一窗 turn + offset/total，更早的走 /messages 翻页。
             const windowed = windowMessagesForTransport(snapshot.messages ?? [], config.cardDefaults ?? {});
             res.json({
@@ -623,6 +639,26 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         }
         const all = snapshot.messages ?? [];
         const total = all.length;
+        // 块级翻页（iOS）：?turn=<i>&blockOffset=<当前 leading 偏移>&blockLimit=<N>
+        // 取该 turn 的 [start, blockOffset) 段（start = max(0, blockOffset - blockLimit)）。
+        const rawTurn = parseInt(String(req.query.turn ?? ""), 10);
+        if (Number.isFinite(rawTurn)) {
+            const turnIndex = Math.min(Math.max(rawTurn, 0), Math.max(total - 1, 0));
+            const turn = all[turnIndex];
+            if (!turn) {
+                res.json({ turnIndex, blocks: [], blockOffset: 0, blockTotal: 0 });
+                return;
+            }
+            const blockTotal = turn.content.length;
+            const rawBlockLimit = parseInt(String(req.query.blockLimit ?? ""), 10);
+            const rawBlockOffset = parseInt(String(req.query.blockOffset ?? ""), 10);
+            const blockLimit = Math.min(Math.max(Number.isFinite(rawBlockLimit) ? rawBlockLimit : 40, 1), 200);
+            const blockEnd = Math.min(Math.max(Number.isFinite(rawBlockOffset) ? rawBlockOffset : blockTotal, 0), blockTotal);
+            const blockStart = Math.max(0, blockEnd - blockLimit);
+            const blocks = sliceTurnBlocksForTransport(turn, blockStart, blockEnd, config.cardDefaults ?? {});
+            res.json({ turnIndex, blocks, blockOffset: blockStart, blockTotal });
+            return;
+        }
         const rawLimit = parseInt(String(req.query.limit ?? ""), 10);
         const rawOffset = parseInt(String(req.query.offset ?? ""), 10);
         const limit = Math.min(Math.max(Number.isFinite(rawLimit) ? rawLimit : 40, 1), 200);

package/dist/ws-broadcast.d.ts

@@ -35,6 +35,11 @@ export declare class WsBroadcastManager {
      * and the first incremental update.
      */
     private sendInit;
+    /**
+     * 按客户端偏好窗口化一段完整 messages：opted-in 的块级窗口（iOS）会附带
+     * leadingBlockOffset/leadingBlockTotal；否则 turn 级窗口（字段与改动前一致）。
+     */
+    private windowForClient;
     private broadcast;
     private processWsQueue;
 }

package/dist/ws-broadcast.js

@@ -5,7 +5,7 @@
 import { WebSocket } from "ws";
 import { EventEmitter } from "node:events";
 import { readSessionCookie, validateSession } from "./auth.js";
-import { windowMessagesForTransport } from "./message-truncator.js";
+import { blockWindowMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
 // ── Constants ──
 const MAX_QUEUE_SIZE = 500;
 const OUTPUT_DEBOUNCE_MS = 16;
@@ -70,6 +70,11 @@ export class WsBroadcastManager {
                 try {
                     const msg = JSON.parse(data.toString());
                     if (msg.type === "subscribe" && msg.sessionId) {
+                        // 客户端可在 subscribe 时声明块级窗口预算（iOS）；后续 init/resync/广播
+                        // 全量快照都按它块级窗口化。不带则保持 turn 级（Web/Android）。
+                        if (typeof msg.blockBudget === "number" && msg.blockBudget > 0) {
+                            client.blockBudget = msg.blockBudget;
+                        }
                         const snapshot = getSession(msg.sessionId);
                         if (snapshot) {
                             this.sendInit(client, msg.sessionId, snapshot, false);
@@ -222,10 +227,9 @@ export class WsBroadcastManager {
      * and the first incremental update.
      */
     sendInit(client, sessionId, snapshot, resync) {
-        // 只下发最近 MESSAGE_WINDOW_SIZE 条 turn，附 offset/total；更早的客户端按需翻页。
-        const windowed = snapshot.messages
-            ? windowMessagesForTransport(snapshot.messages, this.getCardDefaults())
-            : { messages: undefined, messageOffset: 0, messageTotal: 0 };
+        // 块级窗口客户端（iOS）只下发最近 blockBudget 个块；其余走 turn 级窗口。
+        // 两种都附 offset/total，更早的客户端按需翻页。
+        const windowed = this.windowForClient(client, snapshot.messages);
         const seq = (client.outputSeqBySession.get(sessionId) ?? 0) + 1;
         client.outputSeqBySession.set(sessionId, seq);
         client.pendingResyncSessions.delete(sessionId);
@@ -236,40 +240,78 @@ export class WsBroadcastManager {
             ...(resync ? { resync: true } : {}),
             data: {
                 ...snapshot,
-                messages: windowed.messages,
-                messageOffset: windowed.messageOffset,
-                messageTotal: windowed.messageTotal,
+                ...windowed,
                 output: snapshot.output,
             },
         }));
     }
+    /**
+     * 按客户端偏好窗口化一段完整 messages：opted-in 的块级窗口（iOS）会附带
+     * leadingBlockOffset/leadingBlockTotal；否则 turn 级窗口（字段与改动前一致）。
+     */
+    windowForClient(client, messages) {
+        if (!messages) {
+            return { messages: undefined, messageOffset: 0, messageTotal: 0 };
+        }
+        if (client.blockBudget && client.blockBudget > 0) {
+            const w = blockWindowMessagesForTransport(messages, this.getCardDefaults(), client.blockBudget);
+            return {
+                messages: w.messages,
+                messageOffset: w.messageOffset,
+                messageTotal: w.messageTotal,
+                leadingBlockOffset: w.leadingBlockOffset,
+                leadingBlockTotal: w.leadingBlockTotal,
+            };
+        }
+        const w = windowMessagesForTransport(messages, this.getCardDefaults());
+        return { messages: w.messages, messageOffset: w.messageOffset, messageTotal: w.messageTotal };
+    }
     broadcast(event) {
         // 非增量事件若带完整 messages（结构化 output/ended 快照、PTY 非流式 chat 快照），
         // 在这个统一出口窗口化——避免逐个 emit 点各自处理、也防止超大帧撑爆移动端 WS。
         // 增量事件只带 lastMessage，不含 messages 数组，不受影响。
+        // 块级窗口客户端（iOS）需按各自预算切，所以这里改为「按客户端」窗口化；
+        // turn 级（Web/Android）的结果跨客户端一致，缓存一次复用，避免重复计算。
         const data = event.data;
-        if (data && !data.incremental && Array.isArray(data.messages)) {
-            const windowed = windowMessagesForTransport(data.messages, this.getCardDefaults());
-            event = {
-                ...event,
-                data: {
-                    ...data,
-                    messages: windowed.messages,
-                    messageOffset: windowed.messageOffset,
-                    messageTotal: windowed.messageTotal,
-                },
-            };
-        }
+        const hasFullMessages = !!(data && !data.incremental && Array.isArray(data.messages));
+        const rawMessages = hasFullMessages
+            ? data.messages
+            : undefined;
+        let turnWindowedEvent;
+        const eventForClient = (client) => {
+            if (!hasFullMessages)
+                return event;
+            if (client.blockBudget && client.blockBudget > 0) {
+                return {
+                    ...event,
+                    data: { ...data, ...this.windowForClient(client, rawMessages) },
+                };
+            }
+            if (!turnWindowedEvent) {
+                const w = windowMessagesForTransport(rawMessages, this.getCardDefaults());
+                turnWindowedEvent = {
+                    ...event,
+                    data: {
+                        ...data,
+                        messages: w.messages,
+                        messageOffset: w.messageOffset,
+                        messageTotal: w.messageTotal,
+                    },
+                };
+            }
+            return turnWindowedEvent;
+        };
         for (const client of this.clients) {
             if (client.ws.readyState !== WebSocket.OPEN)
                 continue;
+            const clientEvent = eventForClient(client);
             // Stamp output events with a per-(client, session) sequence number so
             // the client can detect a gap caused by backpressure drops.
-            let outgoing = event;
+            let outgoing = clientEvent;
             if (event.type === "output") {
                 const seq = (client.outputSeqBySession.get(event.sessionId) ?? 0) + 1;
                 client.outputSeqBySession.set(event.sessionId, seq);
-                outgoing = { ...event, seq };
+                outgoing = { ...clientEvent, seq };
             }
             // Apply backpressure if queue is too large. We mark the session as
             // needing a resync rather than silently discarding — the client will

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@co0ontty/wand",
-  "version": "1.64.1",
+  "version": "1.65.0-beta.g14437f5",
   "description": "A web terminal for local CLI tools like Claude.",
   "type": "module",
   "bin": {