wave-code 1.4.0 → 1.5.0

package/src/remote/remoteControlCliHost.ts

@@ -33,10 +33,19 @@ import type {
   Task,
   ToolPermissionContext,
 } from "wave-agent-sdk";
-import { listSessions } from "wave-agent-sdk";
+import {
+  listSessions,
+  readRecentWorkdirs,
+  rememberRecentWorkdir,
+} from "wave-agent-sdk";
+import {
+  hostSlashCommandsFor,
+  toSlashCommandInfo,
+} from "../stdio/hostSlashCommands.js";
+import { messagesForUi } from "../stdio/uiPayload.js";
 import {
   InvalidMessageWindowError,
-  sliceMessageWindow,
+  normalizeMessageWindow,
   type MessageWindow,
   type MessageWindowResult,
 } from "./messageWindow.js";
@@ -53,8 +62,20 @@ import {
 export interface RemoteControlCliSession {
   /** Empty until the first turn mints one — there is nothing to serve yet. */
   sessionId(): string;
+  /** Where the shell is now (drifts on `cd`) — used for live directory reads. */
   workdir(): string;
-  displayMessages(): Message[];
+  /** Where the session was opened; the row the page groups by. */
+  sessionCwd(): string;
+  /** One page of the list, sliced in memory. */
+  messagePage(window: MessageWindow): Promise<MessageWindowResult>;
+  /** The whole list as the agent holds it (it starts at the last compaction). */
+  currentThread(): Promise<Message[]>;
+  /** Thread totals the session list needs (the window cannot answer them). */
+  threadSummary(): {
+    messageCount: number;
+    firstUserText?: string;
+    lastActiveAt?: string;
+  };
   contextUsagePercent(): number;
   latestTotalTokens(): number;
   permissionMode(): PermissionMode;
@@ -123,18 +144,6 @@ function hostUnsupported(method: string): Error {
   return err;
 }
 
-function firstUserText(messages: Message[]): string | undefined {
-  const user = messages.find((message) => message.role === "user");
-  if (!user) return undefined;
-  for (const block of user.blocks) {
-    if (block.type === "text" && typeof block.content === "string") {
-      const text = block.content.trim();
-      if (text) return text;
-    }
-  }
-  return undefined;
-}
-
 export class RemoteControlCliHost implements RemoteControlHost {
   constructor(private readonly session: RemoteControlCliSession) {}
 
@@ -149,6 +158,14 @@ export class RemoteControlCliHost implements RemoteControlHost {
         return this.getSessionInfo();
       case "getMessages":
         return this.getMessages(p);
+      // 最近打开的工作目录是本机的事实，与「这条前台会话」无关：同一个文件
+      // AgentBridge 也在读（spec core/recent-workdirs.md）。不实现的话，页面
+      // 会落到「这台电脑上的会话不支持这个操作」——白名单放行 ≠ 宿主实现。
+      case "getRecentWorkdirs":
+        return { dirs: readRecentWorkdirs() };
+      case "rememberRecentWorkdir":
+        rememberRecentWorkdir(typeof p.workdir === "string" ? p.workdir : "");
+        return null;
       case "listPendingPermissions":
         return this.listPendingPermissions();
       case "sendMessage":
@@ -184,15 +201,14 @@ export class RemoteControlCliHost implements RemoteControlHost {
           // Narrowed to what the page renders, like the desktop host does: the
           // SDK's SlashCommand carries a `handler` function, which has no
           // business travelling over a relay (and would be dropped silently,
-          // leaving the frame's shape to chance).
-          commands: this.session.slashCommands().map((command) => ({
-            id: command.id,
-            name: command.name,
-            description: command.description,
-            ...(command.skillSource
-              ? { skillSource: command.skillSource }
-              : {}),
-          })),
+          // leaving the frame's shape to chance). The host-local half comes
+          // from the one table, filtered for this entry (spec
+          // ui/slash-commands.md「弹窗里的宿主命令只有一份表」) — the same bytes
+          // the daemon returns, so the phone sees one list either way.
+          commands: [
+            ...this.session.slashCommands().map(toSlashCommandInfo),
+            ...hostSlashCommandsFor("remote-page"),
+          ],
         };
       default:
         // The white list already rejected everything outside it, so anything
@@ -255,7 +271,7 @@ export class RemoteControlCliHost implements RemoteControlHost {
 
   private synthesizedMetadata(sessionId: string): SessionMetadata {
     const now = new Date();
-    const firstMessage = firstUserText(this.session.displayMessages());
+    const firstMessage = this.session.threadSummary().firstUserText;
     const customTitle = this.session.customTitle();
     return {
       id: sessionId,
@@ -282,7 +298,7 @@ export class RemoteControlCliHost implements RemoteControlHost {
   private listDaemonSessions(): {
     sessions: Array<{
       sessionId: string;
-      workingDirectory: string;
+      sessionCwd: string;
       isLoading: boolean;
       hasRunningBackgroundWork: boolean;
       hasPendingMessages: boolean;
@@ -297,19 +313,19 @@ export class RemoteControlCliHost implements RemoteControlHost {
   } {
     const sessionId = this.session.sessionId();
     if (!sessionId) return { sessions: [] };
-    const messages = this.session.displayMessages();
     const customTitle = this.session.customTitle();
-    const firstMessage = firstUserText(messages);
-    const lastActiveAt = messages[messages.length - 1]?.timestamp;
+    const summary = this.session.threadSummary();
+    const firstMessage = summary.firstUserText;
+    const lastActiveAt = summary.lastActiveAt;
     return {
       sessions: [
         {
           sessionId,
-          workingDirectory: this.session.workdir(),
+          sessionCwd: this.session.sessionCwd(),
           isLoading: this.session.isLoading(),
           hasRunningBackgroundWork: this.session.hasRunningBackgroundWork(),
           hasPendingMessages: this.session.hasPendingMessages(),
-          messageCount: messages.length,
+          messageCount: summary.messageCount,
           ...(customTitle ? { customTitle } : {}),
           ...(firstMessage ? { firstMessage } : {}),
           ...(lastActiveAt ? { lastActiveAt } : {}),
@@ -320,7 +336,7 @@ export class RemoteControlCliHost implements RemoteControlHost {
 
   private getSessionInfo(): {
     sessionId: string;
-    workingDirectory: string;
+    sessionCwd: string;
     latestTotalTokens: number;
     permissionMode: PermissionMode;
     availableTools: string[];
@@ -332,7 +348,7 @@ export class RemoteControlCliHost implements RemoteControlHost {
   } {
     return {
       sessionId: this.session.sessionId(),
-      workingDirectory: this.session.workdir(),
+      sessionCwd: this.session.sessionCwd(),
       latestTotalTokens: this.session.latestTotalTokens(),
       permissionMode: this.session.permissionMode(),
       availableTools: this.session.availableTools(),
@@ -346,30 +362,43 @@ export class RemoteControlCliHost implements RemoteControlHost {
     };
   }
 
-  private getMessages(p: Record<string, unknown>): {
+  private async getMessages(p: Record<string, unknown>): Promise<{
     messages: Message[];
     contextUsagePercent: number;
-    hasMore?: boolean;
     reset?: boolean;
-    total?: number;
-  } {
-    const all = this.session.displayMessages();
+  }> {
     const contextUsagePercent = this.session.contextUsagePercent();
     const window: MessageWindow = {};
-    if (typeof p.before === "string") window.before = p.before;
     if (typeof p.since === "string") window.since = p.since;
     if (p.limit !== undefined) window.limit = Number(p.limit);
 
-    let sliced: MessageWindowResult | undefined;
+    let normalized: MessageWindow | undefined;
     try {
-      sliced = sliceMessageWindow(all, window);
+      normalized = normalizeMessageWindow(window);
     } catch (err) {
       if (err instanceof InvalidMessageWindowError)
         throw invalidParams(err.message);
       throw err;
     }
-    if (!sliced) return { messages: all, contextUsagePercent };
-    return { ...sliced, contextUsagePercent };
+    // No parameters = the whole list the agent holds (spec
+    // ui/message-rendering-system.md「首屏就是整份列表」). A `limit` is a tail
+    // slice of the same list, for the phone's frame budget.
+    //
+    // Both answers are trimmed: the phone renders no tool pictures, and its
+    // frame budget cannot carry one
+    // (specs/ui/stdio-transport.md「工具图片的字节不下发 UI」).
+    if (!normalized) {
+      return {
+        messages: messagesForUi(await this.session.currentThread()),
+        contextUsagePercent,
+      };
+    }
+    const page = await this.session.messagePage(normalized);
+    return {
+      ...page,
+      messages: messagesForUi(page.messages),
+      contextUsagePercent,
+    };
   }
 
   private listPendingPermissions(): {

package/src/remote/remoteControlConfig.ts

@@ -225,18 +225,33 @@ export async function registerRelayHost(options: {
  * fresh registration. Never registers twice for the same machine — and, with the
  * derived id, no longer registers a second row for it either when the state file
  * went missing.
+ *
+ * `refresh` is the one exception, and it has one caller: the relay answered
+ * `4003` with a stale-identity reason, so the stored pair is known to be dead
+ * (revoked row / expired token / a file whose id and token never belonged
+ * together). Dropping it *before* registering is deliberate — if the
+ * registration then fails (an expired sign-in is the common case), the file must
+ * not keep pointing at an identity the relay has already refused, or the next
+ * attempt would hand the same dead token over and the user would be back to
+ * moving that file by hand.
  */
 export async function ensureRelayHostRegistration(
   name?: string,
+  options: { refresh?: boolean } = {},
 ): Promise<RelayHostRegistration> {
   const state = readState();
-  const storedId = asString(state.hostId);
-  const storedToken = asString(state.hostToken);
-  if (storedId && storedToken) {
-    return { hostId: storedId, hostToken: storedToken };
+  const storedName = asString(state.name);
+  if (!options.refresh) {
+    const storedId = asString(state.hostId);
+    const storedToken = asString(state.hostToken);
+    if (storedId && storedToken) {
+      return { hostId: storedId, hostToken: storedToken };
+    }
+  } else {
+    writeState(storedName ? { name: storedName } : {});
   }
 
-  const label = name && name.trim().length > 0 ? name.trim() : os.hostname();
+  const label = name?.trim() || storedName || os.hostname();
   const registration = await registerRelayHost({
     name: label,
     id: deriveHostId(),
@@ -294,6 +309,8 @@ export function buildPageUrl(hostId: string): string | undefined {
 export async function resolveRemoteControlEndpoint(
   options: {
     name?: string;
+    /** Register again instead of trusting the stored pair (see above). */
+    refreshIdentity?: boolean;
   } = {},
 ): Promise<{
   endpoint?: RemoteControlEndpoint;
@@ -302,7 +319,9 @@ export async function resolveRemoteControlEndpoint(
 }> {
   let registration: RelayHostRegistration;
   try {
-    registration = await ensureRelayHostRegistration(options.name);
+    registration = await ensureRelayHostRegistration(options.name, {
+      refresh: options.refreshIdentity,
+    });
   } catch (err) {
     return { error: err instanceof Error ? err.message : String(err) };
   }

package/src/remote/remoteControlService.ts

@@ -95,38 +95,9 @@ import type { RemoteControlEndpoint } from "./remoteControlConfig.js";
  *   the write fails), so switching on the phone switches it for every session on
  *   this machine. The page says so in its confirmation.
  *
- * **Settings (2026-10-17, third batch)** — read the configuration, edit the
- * personalisation, and toggle the project's built-in plugin. This used to sit in
- * the paragraph below as one undifferentiated "the host holds the data" lump;
- * checked key by key, exactly three of the settings page's views are things a
- * phone can carry — 全局设置 / 个性化 / 项目设置. What the page cannot carry is
- * the **interface** around them: the plugin market, the MCP / skills / subagents
- * / hooks managers (all four need a folder tree, a file path or an install
- * flow), login, and the desktop-only 主题 / Beta 通道 blocks. Those stay
- * unrendered on the page and their methods stay out of this list. So:
- *
- * - `getUserSettings` / `updateUserSettings` — the user preference file, **effective
- *   value + per-key source layer**. The layer is why the page can keep the same
- *   "由组织配置管理" grey-out the desktop has: a key inherited from the org's
- *   remote config arrives already marked, no second read.
- * - `getAgentsContent` / `setAgentsContent` — the two AGENTS.md editors
- *   (user-level / project-level). Same RPC the desktop and IDE settings pages use.
- * - `getProjectSettings` / `setBuiltinPluginEnabled` — the 项目设置 view's one
- *   switch (SDD). **Project scope only** is reachable from the page's UI; the
- *   method's `scope` parameter is not narrowed here because the desktop uses the
- *   same call for the same single toggle.
- *
- * Deliberately **not** added with them: `updateConfig` (the session-level
- * `AgentOptions` overlay — the settings page stopped using it on 2026-09-10;
- * every key it saves is a user preference, so `updateUserSettings` is the whole
- * write path and adding `updateConfig` would expose a knob with no caller) and
- * `getConfiguredModels` (already allowed since the second batch — the page's
- * `/model` needs it; the settings page's completion-model dropdown does **not**
- * exist here, see below).
- *
- * Still out, and deliberately: the plugin market / skills / subagents / hooks /
- * MCP managers, login (`login`, `logout`, …), anything that opens an editor
- * (`openFile` is not even a bridge method), the on-disk session list
+ * Still out, and deliberately: settings / plugin market / login (`getUserSettings`,
+ * `updateUserSettings`, plugins, `login`, `logout`, …), anything that opens an
+ * editor (`openFile` is not even a bridge method), the on-disk session list
  * (`listAllSessions` / `restoreSession`), the process-lifecycle calls
  * (`shutdown` / `bang`), and the **read-only panes the page has no
  * surface for** — `getWorkspaceDiff` / `getWorktreeChanges` / `getPlanFile` /
@@ -192,16 +163,11 @@ export const REMOTE_ALLOWED_METHODS: ReadonlySet<string> = new Set([
   "searchFiles",
   "getPromptHistory",
   "searchPromptHistory",
-  // ── 第三批：设置页（spec ui/remote-control.md「Web 端也能改设置」）──
-  // 只有「读配置 + 个性化 + 项目设置」这三块页面：用户偏好（生效值 + 每键来源层）、
-  // 两份 AGENTS.md、项目内置插件开关。插件市场 / MCP / 技能 / 子代理 / 钩子 / 登录
-  // 那批要的是宿主的**界面**能力，页面不渲染、方法也不放行（见上面注释）。
-  "getUserSettings",
-  "updateUserSettings",
-  "getAgentsContent",
-  "setAgentsContent",
-  "getProjectSettings",
-  "setBuiltinPluginEnabled",
+  // `/btw` 旁路提问（spec「Web 页也能用 /btw 旁路提问」）：单轮 fork、不执行工具、
+  // 不进对话历史 —— 它作用于当前会话、既不需要编辑器也不需要文件系统，与第二批
+  // 那条「页面能不能承载」同一条判据。**只放行请求**：流式增量是宿主推的
+  // `btwContent` 通知，走既有的通知扇出，白名单管不到也不需要管。
+  "askBtw",
   // ── 第四批：会话删除（spec「手机端的会话列表与删除」）──
   // 写：`destroy` 带上可选 `removeWorktree`（默认 false）。工作树由 daemon 从该
   // 会话的 createdWorkdir 定位、并在 agent.destroy() 之后删除，页面给不出路径。
@@ -211,6 +177,13 @@ export const REMOTE_ALLOWED_METHODS: ReadonlySet<string> = new Set([
   // 「能指名任意路径」不是同一个能力。
   "destroy",
   "getSessionWorktreeChanges",
+  // ── 第五批：最近打开的工作目录（spec core/recent-workdirs.md）──
+  // 读：`getRecentWorkdirs` 回这台机器自己的 MRU 列表（`~/.wave/recent-workdirs.json`）。
+  // 写：`rememberRecentWorkdir` 只在新建会话成功后由页面调用一次，参数是那次
+  // 创建用的目录——它不会删改已有条目，也换不来「在任意目录跑 agent」之外
+  // 的任何东西（那个能力本来就在 `initialize` 里）。
+  "getRecentWorkdirs",
+  "rememberRecentWorkdir",
 ]);
 
 /**
@@ -313,7 +286,10 @@ export interface RemoteControlServiceOptions {
    * this is also where the one registration call happens, which is why it is
    * async.
    */
-  resolveEndpoint: (options?: { name?: string }) => Promise<{
+  resolveEndpoint: (options?: {
+    name?: string;
+    refreshIdentity?: boolean;
+  }) => Promise<{
     endpoint?: RemoteControlEndpoint;
     pageUrl?: string;
     error?: string;
@@ -341,6 +317,17 @@ export class RemoteControlService implements RemoteControlController {
    * connection the user has already turned off.
    */
   private generation = 0;
+  /**
+   * The stale-identity self-heal already ran in this process.
+   *
+   * Re-registering mints a **new** token, and any other entry on this machine is
+   * still holding the old one — so an unbounded heal turns two processes into a
+   * loop of re-signing each other's credential away (the same shape as the `4001`
+   * takeover ping-pong). One attempt per process is what keeps it convergent:
+   * whoever healed last serves, the other stops. A second, different reason is
+   * an expiry 90 days out, which is not worth spending the budget on.
+   */
+  private identityRefreshUsed = false;
 
   constructor(
     private readonly bridge: RemoteControlHost,
@@ -359,17 +346,30 @@ export class RemoteControlService implements RemoteControlController {
    * Resolve the identity (registering this machine on first use), then dial.
    * Every await is followed by a generation check, so a `stop` that arrives
    * while the relay is being asked for a host id wins.
+   *
+   * `refreshIdentity` forces that registration to happen again, which is only
+   * ever set by the self-heal below.
    */
-  private async setup(generation: number): Promise<void> {
-    const resolved = await this.options.resolveEndpoint(
-      this.name !== undefined ? { name: this.name } : {},
-    );
+  private async setup(
+    generation: number,
+    options: { refreshIdentity?: boolean } = {},
+  ): Promise<void> {
+    const resolved = await this.options.resolveEndpoint({
+      ...(this.name !== undefined ? { name: this.name } : {}),
+      ...(options.refreshIdentity ? { refreshIdentity: true } : {}),
+    });
     if (generation !== this.generation) return;
 
     if (!resolved.endpoint) {
+      const reason = resolved.error ?? "Remote control is unavailable.";
       this.setStatus({
         state: "error",
-        message: resolved.error ?? "Remote control is unavailable.",
+        // Two layers, because the user has to act on both halves: the identity
+        // this machine stored is gone, *and* replacing it did not work. Saying
+        // only the latter would read like a flaky network.
+        message: options.refreshIdentity
+          ? `the relay no longer knows this machine, and registering it again failed: ${reason}`
+          : reason,
       });
       return;
     }
@@ -411,14 +411,10 @@ export class RemoteControlService implements RemoteControlController {
       },
       onAuthError: (info) => {
         // The close that follows carries the mechanics (4003 = do not retry);
-        // the frame is the only place the *reason* lives, and for a version
-        // floor the only place the required version lives.
+        // the frame is the only place the *reason* lives.
         this.setStatus({
           state: "error",
-          message:
-            info.error === "host_version_unsupported"
-              ? `the relay requires a newer wave on this machine${info.minVersion ? ` (minimum ${info.minVersion})` : ""}`
-              : `the relay refused this machine: ${info.error}`,
+          message: `the relay refused this machine: ${info.error}`,
         });
       },
       onPeerDisconnected: () => {
@@ -436,6 +432,10 @@ export class RemoteControlService implements RemoteControlController {
         this.emitStatus(true);
       },
       onFrame: (frame) => this.handleFrame(frame),
+      onStaleIdentity: (info) => {
+        if (generation !== this.generation) return;
+        this.refreshIdentity(info.error);
+      },
       onFatal: (message) => {
         if (generation !== this.generation) return;
         this.setStatus({ state: "error", message });
@@ -444,6 +444,34 @@ export class RemoteControlService implements RemoteControlController {
     this.client.start();
   }
 
+  /**
+   * The relay refused the credential with a stale-identity reason — the stored
+   * row is gone (revoked, expired, or a file whose id and token never belonged
+   * together). Recover by registering again: the id is derived from the machine,
+   * so the relay reuses the same row and the page URL survives, and the fresh
+   * token then dials out. Without this the only way back was for the user to
+   * delete `~/.wave/remote-control.json` by hand, which nobody knows exists
+   * (2026-10-16: a revoked row left a Mac unable to reconnect at all).
+   *
+   * Attempted **once per process** — see `identityRefreshUsed`.
+   */
+  private refreshIdentity(error: string): void {
+    if (this.identityRefreshUsed) {
+      this.setStatus({
+        state: "error",
+        message: `the relay rejected this machine even after registering it again (4003): ${error}`,
+      });
+      return;
+    }
+    this.identityRefreshUsed = true;
+    const generation = ++this.generation;
+    this.setStatus({
+      state: "connecting",
+      message: "the relay no longer knows this machine: registering it again",
+    });
+    void this.setup(generation, { refreshIdentity: true });
+  }
+
   stop(): void {
     // Ordered before the teardown so a registration still in flight cannot
     // finish and dial out afterwards.
@@ -583,11 +611,10 @@ export class RemoteControlService implements RemoteControlController {
    * Answer a request, hammering the answer into the frame budget.
    *
    * A read answer is the one frame whose size follows the session (a page of
-   * `displayMessages`), so it is the one frame that gets trimmed instead of
-   * dropped. `getMessages` answers are pageable and the phone asked for the
-   * tail, so an over-budget page is cut to the **newest** messages that fit and
-   * flagged `hasMore` — the phone keeps a usable page instead of nothing, and
-   * walking further back is a smaller `limit` away. Every other over-budget
+   * the message list), so it is the one frame that gets trimmed instead of
+   * dropped. A `getMessages` answer can be cut and the phone asked for the
+   * tail, so an over-budget one is cut to the **newest** messages that fit — the
+   * phone keeps a usable list instead of nothing. Every other over-budget
    * answer is an explicit error: truncating a `getSessionInfo` or a
    * `listSessions` would hand the phone a well-formed lie about which sessions
    * exist, and there is no "newer part" of such an answer to prefer.
@@ -615,9 +642,8 @@ export class RemoteControlService implements RemoteControlController {
         (count) =>
           frameBytes(pageFrame(replyId, page, count)) <= REMOTE_MAX_FRAME_BYTES,
       );
-      // Not even one message fits: pageable or not, there is nothing to send
-      // that the phone could render, and an empty page claiming `hasMore` would
-      // only make it ask again forever.
+      // Not even one message fits: there is nothing to send that the phone
+      // could render, and an empty list would only make it re-ask forever.
       if (kept > 0) {
         this.send(pageFrame(replyId, page, kept));
         return;
@@ -756,18 +782,18 @@ function describeRpcError(err: unknown): { code: number; message: string } {
   return { code: Number.isFinite(code) ? code : -32603, message };
 }
 
-/** A `getMessages` answer: the one read shape that can be cut into a page. */
+/** A `getMessages` answer: the one read shape that can be cut. */
 interface MessagePage {
   messages: unknown[];
-  /** Whatever else the host put in the answer (`hasMore` / `reset` / `total`). */
+  /** Whatever else the host put in the answer (`reset` / `contextUsagePercent`). */
   rest: Record<string, unknown>;
 }
 
 /**
- * Recognise a pageable answer by its shape rather than by the method that
+ * Recognise a cuttable answer by its shape rather than by the method that
  * produced it: `getMessages` is the only method that returns `messages` today,
- * and matching on the shape means a future paged read is covered without a
- * second list of method names to keep in sync.
+ * and matching on the shape means a future read is covered without a second
+ * list of method names to keep in sync.
  */
 function asMessagePage(result: unknown): MessagePage | undefined {
   if (typeof result !== "object" || result === null) return undefined;
@@ -790,9 +816,6 @@ function pageFrame(
       result: {
         ...page.rest,
         messages: page.messages.slice(-count),
-        // The page is by definition no longer the whole answer, and the phone
-        // reads this flag to decide whether asking again is worth anything.
-        hasMore: true,
       },
     },
   };

package/src/remote/remoteControlSink.ts

@@ -64,9 +64,10 @@ export interface RemoteControlSink
 export function createRemoteControlSinkFactory(
   workdir: string,
 ): ((host: RemoteControlHost) => RemoteControlSink) | undefined {
-  // Opt-in twice over: this switch says the machine *may* serve its sessions to
-  // a paired phone, and `wave remote-control on` / `/remote-control` is what
-  // actually dials out. The sink is therefore built but not connected.
+  // Two-step by design: this switch (on unless a settings file or a remote
+  // push turns it off) says the machine *may* serve its sessions to a paired
+  // phone, and `wave remote-control on` / `/remote-control` is what actually
+  // dials out. The sink is therefore built but not connected.
   if (!isRemoteControlEnabled(workdir)) {
     return undefined;
   }

package/src/remote/remoteNotifications.ts

@@ -27,6 +27,7 @@ import type {
   ToolBlockUpdateCallbackParams,
   ToolPermissionContext,
 } from "wave-agent-sdk";
+import { toolBlockUpdateForUi } from "../stdio/uiPayload.js";
 
 /**
  * A content delta exactly as the SDK callback hands it over — derived rather
@@ -73,10 +74,15 @@ export const remoteWire = {
    * `running` (one-time snapshots) and `end` (the authoritative full value) keep
    * `parameters`. The coalescer's merge rule is keyed on exactly this shape, so
    * this pick is what makes the 150 ms window behave the same in both hosts.
+   *
+   * `images` is cut on every stage: tool pictures are base64 that no UI renders
+   * (specs/ui/stdio-transport.md「工具图片的字节不下发 UI」), and one of them can
+   * be larger than a remote frame may be.
    */
   toolBlockUpdated: (params: ToolBlockUpdateCallbackParams) => {
-    if (params.stage !== "streaming") return params;
-    const { parameters, ...rest } = params;
+    const trimmed = toolBlockUpdateForUi(params);
+    if (trimmed.stage !== "streaming") return trimmed;
+    const { parameters, ...rest } = trimmed;
     void parameters;
     return rest;
   },