wave-code 1.5.0 → 1.6.0

package/src/print-cli.ts

@@ -6,10 +6,18 @@ import {
   getDefaultRemoteBranch,
   validateWorktreeRemovalPath,
   setTelemetryStdoutProtected,
+  type Usage,
   type WorktreeSession,
 } from "wave-agent-sdk";
 import { displayUsageSummary } from "./utils/usageSummary.js";
-import { removeWorktree } from "./utils/worktree.js";
+import { describeWorktreeSurvival, removeWorktree } from "./utils/worktree.js";
+import {
+  drainStdout,
+  installStdoutGuard,
+  PrintOutput,
+  uninstallStdoutGuard,
+  type OutputFormat,
+} from "./utils/printOutput.js";
 import { BaseAppProps } from "./types.js";
 
 export interface PrintCliOptions extends BaseAppProps {
@@ -19,9 +27,18 @@ export interface PrintCliOptions extends BaseAppProps {
   showStats?: boolean;
   /** MCP server config parsed from --mcp-config CLI argument */
   mcpServers?: Record<string, import("wave-agent-sdk").McpServerConfig>;
+  /** --output-format: "text" (default), "json", or "stream-json" */
+  outputFormat?: OutputFormat;
 }
 
-function displayTimingInfo(startTime: Date, showStats: boolean): void {
+/** A diagnostics writer: stdout in text mode, stderr once stdout carries JSON. */
+type Writer = (text: string) => void;
+
+function displayTimingInfo(
+  startTime: Date,
+  showStats: boolean,
+  write: Writer,
+): void {
   // Skip timing info in test environment or if stats are disabled
   if (process.env.NODE_ENV === "test" || process.env.VITEST || !showStats) {
     return;
@@ -30,9 +47,9 @@ function displayTimingInfo(startTime: Date, showStats: boolean): void {
   const endTime = new Date();
   const duration = endTime.getTime() - startTime.getTime();
 
-  process.stdout.write(`\n\n📅 Start time: ${startTime.toISOString()}\n`);
-  process.stdout.write(`📅 End time: ${endTime.toISOString()}\n`);
-  process.stdout.write(`⏱️  Duration: ${duration}ms\n`);
+  write(`\n\n📅 Start time: ${startTime.toISOString()}\n`);
+  write(`📅 End time: ${endTime.toISOString()}\n`);
+  write(`⏱️  Duration: ${duration}ms\n`);
 }
 
 export async function startPrintCli(options: PrintCliOptions): Promise<void> {
@@ -57,6 +74,7 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
     originalCwd,
     model,
     mcpServers,
+    outputFormat = "text",
   } = options;
 
   if (
@@ -70,6 +88,27 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
     process.exit(1);
   }
 
+  const output = new PrintOutput({ format: outputFormat });
+  const structured = output.structured;
+  // Structured modes promise stdout carries nothing but JSON, so a stray
+  // console.log from anywhere in the process is diverted to stderr instead of
+  // tearing the NDJSON stream.
+  if (structured) installStdoutGuard();
+  /** Diagnostics: stderr when stdout is the JSON channel, stdout otherwise. */
+  const diag: Writer = (text) => output.diag(text);
+  const usageWriter = structured
+    ? toLineWriter(process.stderr.write.bind(process.stderr))
+    : undefined;
+  // Text mode keeps the exact call shape it had (console.log); structured mode
+  // is the only one that redirects the summary, and it needs stderr for it.
+  const showUsage = (usages: Usage[], sessionFilePath: string): void => {
+    if (usageWriter) {
+      displayUsageSummary(usages, sessionFilePath, usageWriter);
+    } else {
+      displayUsageSummary(usages, sessionFilePath);
+    }
+  };
+
   let agent: Agent;
   let isReasoning = false;
   let isContent = false;
@@ -82,42 +121,58 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
     onAssistantMessageAdded: () => {
       isReasoning = false;
       isContent = false;
+      output.assistantMessageAdded();
     },
-    onAssistantReasoningUpdated: (params: { chunk: string }) => {
+    onAssistantMessageDiscarded: () => {
+      // 流式降级的半截消息作废，不能算进 result / num_turns
+      output.assistantMessageDiscarded();
+    },
+    onAssistantReasoningUpdated: (params: {
+      messageId: string;
+      chunk: string;
+    }) => {
       if (!isReasoning) {
-        process.stdout.write("\n💭 Reasoning:\n");
+        output.human("\n💭 Reasoning:\n");
         isReasoning = true;
       }
-      process.stdout.write(params.chunk);
+      output.human(params.chunk);
+      output.reasoningDelta(params.messageId, params.chunk);
     },
-    onAssistantContentUpdated: (params: { chunk: string }) => {
+    onAssistantContentUpdated: (params: {
+      messageId: string;
+      chunk: string;
+    }) => {
       if (!isContent) {
         if (isReasoning) {
-          process.stdout.write("\n\n📝 Response:\n");
+          output.human("\n\n📝 Response:\n");
         } else {
-          process.stdout.write("\n");
+          output.human("\n");
         }
         isContent = true;
       }
-      process.stdout.write(params.chunk);
+      output.human(params.chunk);
+      output.contentDelta(params.messageId, params.chunk);
     },
 
     // Tool block callback - display tool name when tool starts
     onToolBlockUpdated: (params) => {
       // Print tool name only during 'running' stage (happens once per tool call)
       if (params.stage === "running" && params.name) {
-        process.stdout.write(`\n🔧 ${params.name}`);
+        output.human(`\n🔧 ${params.name}`);
         if (params.compactParams) {
-          process.stdout.write(` ${params.compactParams}`);
+          output.human(` ${params.compactParams}`);
         }
-        process.stdout.write(`\n`);
+        output.human(`\n`);
       }
+      output.toolUpdate(params);
     },
 
-    // Error block callback
-    onErrorBlockAdded: (error: string) => {
-      // Display error blocks with distinct formatting
-      process.stdout.write(`\n❌ Error: ${error}\n`);
+    // Notice callback: `error` is the turn failure, `info` a hook's line for
+    // the human. Only the former is an error for the CLI's own output.
+    onNoticeAdded: ({ level, content }) => {
+      if (level !== "error") return;
+      output.error(content);
+      diag(`\n❌ Error: ${content}\n`);
     },
   };
 
@@ -143,6 +198,18 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
       // 保持流式模式以获得更好的命令行用户体验
     });
 
+    // stream-json 的首事件：把会话元信息先交代清楚，CI 才能把后面的行归到一次运行上。
+    // 只有这一种格式会读这些 getter，别的格式没必要为它解析一遍配置。
+    if (outputFormat === "stream-json") {
+      output.init({
+        sessionId: agent.sessionId,
+        model: agent.getModelConfig().model,
+        cwd: agent.currentWorkdir,
+        permissionMode: agent.getPermissionMode(),
+        tools: agent.getAvailableToolNames(),
+      });
+    }
+
     // Inject worktree session into this agent's container (per-session, not global)
     if (worktreeSession) {
       const session: WorktreeSession = {
@@ -160,7 +227,7 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
     // Send message if provided and not empty
     if (typeof message === "string" && message.trim() !== "") {
       await agent.sendMessage(message);
-      process.stdout.write("\n");
+      output.human("\n");
     }
 
     // Wait for running background tasks/subagents to complete AND for the main
@@ -178,19 +245,29 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
       await new Promise((resolve) => setTimeout(resolve, 500));
     }
 
+    // Snapshot before destroy — the result envelope needs both, and the agent
+    // is torn down before the worktree bookkeeping below. A getter that throws
+    // must never turn a completed run into a failure, so it degrades to no
+    // usage rather than raising.
+    const usageSnapshot = readUsageSnapshot(agent);
+    let sessionId = "";
+    try {
+      sessionId = agent.sessionId;
+    } catch {
+      // Same rule as the usage snapshot: identity loss is not a run failure
+    }
+
     // Display usage summary before exit
-    if (showStats) {
+    if (showStats && usageSnapshot) {
       try {
-        const usages = agent.usages;
-        const sessionFilePath = agent.sessionFilePath;
-        displayUsageSummary(usages, sessionFilePath);
+        showUsage(usageSnapshot.usages, usageSnapshot.sessionFilePath);
       } catch {
         // Silently ignore usage summary errors
       }
     }
 
     // Display timing information
-    displayTimingInfo(startTime, showStats);
+    displayTimingInfo(startTime, showStats, diag);
 
     // Decide whether the worktree is clean enough to remove
     let cleanWorktree = false;
@@ -202,7 +279,7 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
       cleanWorktree = !hasChanges && !hasCommits;
 
       if (!cleanWorktree) {
-        process.stdout.write(
+        diag(
           `\n⚠️ Worktree '${worktreeSession.name}' has changes or commits. Keeping it at: ${worktreeSession.path}\n`,
         );
       }
@@ -222,34 +299,58 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
             worktreeSession.repoRoot,
           );
         }
-        process.stdout.write("\nDeleting worktree ...\n");
-        await removeWorktree(worktreeSession);
-        process.stdout.write("Done.\n");
+        diag("\nDeleting worktree ...\n");
+        // "Done." only when it is: removal is best-effort, and a surviving
+        // directory (with its branch kept for it) needs the cleanup commands
+        // printed rather than a success line over the leftovers.
+        diag(
+          (await removeWorktree(worktreeSession))
+            ? "Done.\n"
+            : `\n${describeWorktreeSurvival(worktreeSession)}\n`,
+        );
       } catch (error) {
         // Never block print-mode exit on worktree cleanup failures
-        process.stdout.write(
-          `\n⚠️ Skipping worktree removal: ${(error as Error).message}\n`,
-        );
+        diag(`\n⚠️ Skipping worktree removal: ${(error as Error).message}\n`);
       }
     }
 
-    process.exit(0);
+    // The result line goes out last on stdout; everything above that is either
+    // suppressed (structured) or on stderr. The exit code reads the envelope so
+    // "did this run fail" has one answer, not two: a request-level failure (model
+    // unreachable, auth rejected) never throws out of sendMessage — it only
+    // leaves an error block behind.
+    const envelope = output.result({
+      sessionId,
+      durationMs: Date.now() - startTime.getTime(),
+      usages: usageSnapshot?.usages ?? [],
+    });
+    await exitWithFlushedStdout(structured, envelope.is_error ? 1 : 0);
   } catch (error) {
     console.error("Failed to send message:", error);
+    output.error((error as Error)?.message ?? String(error));
+
+    let usages: Usage[] = [];
+    let sessionId = "";
+
     if (agent!) {
       // Display usage summary even on error
-      if (showStats) {
-        try {
-          const usages = agent.usages;
-          const sessionFilePath = agent.sessionFilePath;
-          displayUsageSummary(usages, sessionFilePath);
-        } catch {
-          // Silently ignore usage summary errors
+      try {
+        usages = agent.usages;
+        sessionId = agent.sessionId;
+        const sessionFilePath = agent.sessionFilePath;
+        if (showStats) {
+          try {
+            showUsage(usages, sessionFilePath);
+          } catch {
+            // Silently ignore usage summary errors
+          }
         }
+      } catch {
+        // Silently ignore usage access errors
       }
 
       // Display timing information even on error
-      displayTimingInfo(startTime, showStats);
+      displayTimingInfo(startTime, showStats, diag);
 
       // Decide whether the worktree is clean enough to remove
       let cleanWorktree = false;
@@ -261,7 +362,7 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
         cleanWorktree = !hasChanges && !hasCommits;
 
         if (!cleanWorktree) {
-          process.stdout.write(
+          diag(
             `\n⚠️ Worktree '${worktreeSession.name}' has changes or commits. Keeping it at: ${worktreeSession.path}\n`,
           );
         }
@@ -280,16 +381,65 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
               worktreeSession.repoRoot,
             );
           }
-          process.stdout.write("\nDeleting worktree ...\n");
-          await removeWorktree(worktreeSession);
-          process.stdout.write("Done.\n");
-        } catch (error) {
-          process.stdout.write(
-            `\n⚠️ Skipping worktree removal: ${(error as Error).message}\n`,
+          diag("\nDeleting worktree ...\n");
+          diag(
+            (await removeWorktree(worktreeSession))
+              ? "Done.\n"
+              : `\n${describeWorktreeSurvival(worktreeSession)}\n`,
           );
+        } catch (error) {
+          diag(`\n⚠️ Skipping worktree removal: ${(error as Error).message}\n`);
         }
       }
     }
-    process.exit(1);
+
+    // A CI consumer must be able to read why the run failed off stdout, so a
+    // failed run still emits its result envelope — just without `result`
+    // (Claude Code's error variant does the same). This covers the case where
+    // the agent never came up: no usages, no session id.
+    const envelope = output.result({
+      sessionId,
+      durationMs: Date.now() - startTime.getTime(),
+      usages,
+      isError: true,
+    });
+    await exitWithFlushedStdout(structured, envelope.is_error ? 1 : 0);
   }
 }
+
+/**
+ * The agent's usage table plus the transcript path, or `undefined` when either
+ * getter throws — the summary is a convenience, not part of the run's contract.
+ */
+function readUsageSnapshot(
+  agent: Agent,
+): { usages: Usage[]; sessionFilePath: string } | undefined {
+  try {
+    return { usages: agent.usages, sessionFilePath: agent.sessionFilePath };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Structured modes hand stdout to a consumer reading it line by line, so the
+ * queued writes must land before the process goes away: a truncated last line
+ * is a parse error on their side. Text mode keeps its existing exit path.
+ */
+async function exitWithFlushedStdout(
+  structured: boolean,
+  code: number,
+): Promise<void> {
+  if (structured) {
+    uninstallStdoutGuard();
+    await drainStdout();
+  }
+  process.exit(code);
+}
+
+/** Adapt a stream write to the line-writer shape `displayUsageSummary` takes. */
+function toLineWriter(
+  write: (chunk: string) => unknown,
+): (line?: string) => void {
+  return (line) => void write((line ?? "") + "\n");
+}

package/src/remote/hostIdentity.ts

@@ -122,6 +122,7 @@ function readWindowsMachineId(): string | undefined {
       encoding: "utf8",
       timeout: READ_TIMEOUT_MS,
       stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
     },
   );
   return /MachineGuid\s+REG_SZ\s+(\S+)/.exec(output)?.[1];

package/src/remote/imagePreview.ts

@@ -0,0 +1,182 @@
+/**
+ * On-demand image preview for the remote-control page.
+ *
+ * ## Why this exists
+ *
+ * The phone cannot read files: message payloads have their image bytes stripped
+ * before they cross the relay (`stdio/uiPayload.ts`), and the page has no file
+ * system of its own. A screenshot an agent saved to disk (`/tmp/shot.png`) is
+ * therefore just a path in the conversation — readable nowhere on the phone.
+ * This module is the one thing that turns such a path back into pixels, on
+ * demand, over the relay (spec `remote/remote-web.md`「点消息里的图片路径看原图」).
+ *
+ * ## The two gates
+ *
+ * 1. **Routing** — {@link IMAGE_FILE_EXTENSIONS} decides whether the *page*
+ *    offers a click target at all. That is a UI concern: an extension is a hint,
+ *    never proof.
+ * 2. **Authorisation** — the bytes are decoded here, and only a real raster
+ *    container is served (`ALLOWED_SOURCE_FORMATS`). A `/tmp/x.png` that is
+ *    really a symlink to a text file dies at this gate. Nothing else in this
+ *    path can tell the two apart, so collapsing these gates would turn a file
+ *    name into an authorisation decision.
+ *
+ * Everything is read-only: no writes, no deletions, no path is ever echoed back
+ * as something callable.
+ *
+ * ## Why the budget is not the frame budget
+ *
+ * {@link IMAGE_PREVIEW_MAX_RAW_BYTES} is the *image's* budget, derived from the
+ * relay's single-frame limit: the frame covers a whole JSON envelope and base64
+ * inflates bytes by 4/3, so the image has to fit in roughly three quarters of
+ * it. An over-budget frame is silently dropped by the relay's 1 MiB subscriber
+ * buffer, which would leave the phone with nothing — hence "shrink or report",
+ * never "send it as-is".
+ */
+import { readFile, stat } from "node:fs/promises";
+import { shrinkImageForTransport } from "wave-agent-sdk";
+import { IMAGE_FILE_EXTENSIONS } from "wave-agent-sdk/constants";
+import { REMOTE_MAX_FRAME_BYTES } from "./frameBudget.js";
+
+/** Containers the codec must report before any bytes are served. */
+const ALLOWED_SOURCE_FORMATS = new Set(["png", "jpeg", "gif", "webp"]);
+
+/**
+ * Refuse to pull an absurd file into memory before the codec gets a say. Well
+ * above any real screenshot (an 8K PNG is ~20–30 MB) and well below "a video
+ * file with a .png name".
+ */
+const MAX_SOURCE_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Raw-byte budget for the image itself: leave a little of the frame for the
+ * envelope's keys and the `data:<mime>;base64,` prefix, then undo base64's 4/3.
+ */
+export const IMAGE_PREVIEW_MAX_RAW_BYTES = Math.floor(
+  ((REMOTE_MAX_FRAME_BYTES - 2048) * 3) / 4,
+);
+
+/** Not an image, or not one of the containers above — the request is refused. */
+export const IMAGE_PREVIEW_NOT_IMAGE = -32012;
+/** Larger than the frame can carry even after every rung of the ladder. */
+export const IMAGE_PREVIEW_TOO_LARGE = -32013;
+/** sharp is missing (it is installed at runtime, not bundled). */
+export const IMAGE_PREVIEW_CODEC_UNAVAILABLE = -32014;
+/** The path could not be read (missing, permission, a directory). */
+export const IMAGE_PREVIEW_READ_FAILED = -32015;
+
+export interface ImagePreviewResult {
+  /** The path that was asked for, echoed for the page's error/placeholder copy. */
+  path: string;
+  /** `data:<mime>;base64,…`, ready for `<img src>`. */
+  dataUrl: string;
+  mime: string;
+  /** Dimensions of the bytes being returned (after any downscale). */
+  width: number;
+  height: number;
+  /** True when the image was downscaled to fit — the page says so out loud. */
+  scaled: boolean;
+  /** Encoded size of the returned bytes. */
+  bytes: number;
+}
+
+function fail(code: number, message: string): Error {
+  const error = new Error(message) as Error & { code?: number };
+  error.code = code;
+  return error;
+}
+
+/**
+ * Read one image from **this machine** and shrink it to fit a relay frame.
+ *
+ * Throws an `Error` carrying one of the `IMAGE_PREVIEW_*` codes; the remote
+ * error reply turns it into one visible line on the page.
+ */
+export async function readImagePreview(
+  filePath: string,
+): Promise<ImagePreviewResult> {
+  if (typeof filePath !== "string" || filePath.trim() === "") {
+    throw fail(IMAGE_PREVIEW_NOT_IMAGE, "getImagePreview requires a path");
+  }
+
+  let size: number;
+  try {
+    const info = await stat(filePath);
+    if (!info.isFile()) {
+      throw fail(IMAGE_PREVIEW_READ_FAILED, `Not a file: ${filePath}`);
+    }
+    size = info.size;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      typeof error.code === "number"
+    ) {
+      throw error;
+    }
+    throw fail(IMAGE_PREVIEW_READ_FAILED, `Could not read ${filePath}`);
+  }
+
+  if (size > MAX_SOURCE_BYTES) {
+    throw fail(
+      IMAGE_PREVIEW_TOO_LARGE,
+      `${filePath} is ${Math.round(size / (1024 * 1024))} MB, too large to preview`,
+    );
+  }
+
+  let source: Buffer;
+  try {
+    source = await readFile(filePath);
+  } catch {
+    throw fail(IMAGE_PREVIEW_READ_FAILED, `Could not read ${filePath}`);
+  }
+
+  const shrunk = await shrinkImageForTransport(
+    source,
+    IMAGE_PREVIEW_MAX_RAW_BYTES,
+  );
+
+  if (!shrunk.ok) {
+    switch (shrunk.reason) {
+      case "no-codec":
+        throw fail(
+          IMAGE_PREVIEW_CODEC_UNAVAILABLE,
+          "This machine has no image codec installed, so the picture cannot be prepared for the phone",
+        );
+      case "too-large":
+        throw fail(
+          IMAGE_PREVIEW_TOO_LARGE,
+          "The image is still too large for the remote channel after shrinking",
+        );
+      case "unreadable":
+        throw fail(
+          IMAGE_PREVIEW_NOT_IMAGE,
+          `${filePath} is not an image this machine can read`,
+        );
+    }
+  }
+
+  // The authorisation gate: the *decoded* container, not the file name.
+  if (
+    !shrunk.sourceFormat ||
+    !ALLOWED_SOURCE_FORMATS.has(shrunk.sourceFormat)
+  ) {
+    throw fail(
+      IMAGE_PREVIEW_NOT_IMAGE,
+      `${filePath} is not a supported image (${shrunk.sourceFormat ?? "unknown"})`,
+    );
+  }
+
+  return {
+    path: filePath,
+    dataUrl: shrunk.dataUrl,
+    mime: shrunk.mime,
+    width: shrunk.width,
+    height: shrunk.height,
+    scaled: shrunk.scaled,
+    bytes: shrunk.bytes,
+  };
+}
+
+/** Re-exported so the remote host and the page's shim quote one list. */
+export { IMAGE_FILE_EXTENSIONS };

package/src/remote/messageWindow.ts

@@ -10,11 +10,12 @@
  *
  * The list itself lives in the SDK: it starts at the last compaction, and the
  * remote page takes a `limit`-sized tail of it because of the relay's frame
- * budget. What is left here is the one rule a misreading caller cannot notice
- * on its own — a malformed parameter must fail instead of silently widening
- * into a full read.
+ * budget (a compacted session's tail is filled up to `limit` from the
+ * transcript, so the cap is a message count, not a byte range). What is left
+ * here is the one rule a misreading caller cannot notice on its own — a
+ * malformed parameter must fail instead of silently widening into a full read.
  *
- * Described in docs/specs/ui/remote-control.md (§5 白名单与增量拉取).
+ * Described in docs/specs/remote/remote-channel.md (§5 白名单与增量拉取).
  */
 
 import type { MessageWindow } from "wave-agent-sdk";
@@ -32,15 +33,24 @@ export function normalizeMessageWindow(
   window?: MessageWindow,
 ): MessageWindow | undefined {
   const since = window?.since;
+  const before = window?.before;
   const rawLimit = window?.limit;
   if (rawLimit !== undefined && (!Number.isInteger(rawLimit) || rawLimit < 1)) {
     throw new InvalidMessageWindowError(
       `getMessages limit must be a positive integer, got ${String(rawLimit)}`,
     );
   }
-  if (since === undefined && rawLimit === undefined) return undefined;
+  if (since !== undefined && before !== undefined) {
+    throw new InvalidMessageWindowError(
+      "getMessages takes either `since` or `before`, not both",
+    );
+  }
+  if (since === undefined && before === undefined && rawLimit === undefined) {
+    return undefined;
+  }
   return {
     ...(since !== undefined ? { since } : {}),
+    ...(before !== undefined ? { before } : {}),
     ...(rawLimit !== undefined ? { limit: rawLimit } : {}),
   };
 }

package/src/remote/notificationCoalescer.ts

@@ -49,8 +49,9 @@ interface MergeSpec {
  * `messageOperations.ts` accumulates `parametersChunk` by plain concatenation —
  * the same operation this class performs. A `start` / `running` / `end` frame
  * is a one-time snapshot (or the authoritative full value) and must not be
- * merged with anything. `btwContent` (the `/btw` answer stream) is the fourth:
- * one field, no stages, a delta every time.
+ * merged with anything. `btwContent` (the `/btw` answer stream) is the fourth,
+ * and the compaction summary tail (`compactionContentUpdate`) the fifth: both
+ * carry one delta field and no stages, so every frame is a delta.
  */
 function mergeSpec(method: string, params: unknown): MergeSpec | undefined {
   if (typeof params !== "object" || params === null) return undefined;
@@ -79,7 +80,7 @@ function mergeSpec(method: string, params: unknown): MergeSpec | undefined {
     };
   }
 
-  // `/btw` side question (`btwContent`, spec ui/remote-control.md「Web 页也能用
+  // `/btw` side question (`btwContent`, spec remote/remote-web.md「Web 页也能用
   // /btw 旁路提问」场景 4). Same family as the three above: `content` is a pure
   // delta the panel accumulates, so the merged frame carries exactly the bytes
   // the individual ones would. The key carries the question **and** the channel
@@ -96,6 +97,18 @@ function mergeSpec(method: string, params: unknown): MergeSpec | undefined {
     };
   }
 
+  // Compaction summary streaming: since 2026-10-27 the payload is a delta of
+  // newly produced text (it used to carry the whole tail), so it merges exactly
+  // like the three above. The key needs no stream identity: one compaction runs
+  // one stream per session, and both its start and its end
+  // (`compactionStateChange`) are discrete events that flush this buffer first
+  // (spec: ui/stdio-transport.md「流式通知纯增量负载」场景 7, remote/remote-web.md
+  // 场景 10).
+  if (method === "compactionContentUpdate") {
+    if (typeof p.content !== "string") return undefined;
+    return { field: "content", key: "k" };
+  }
+
   return undefined;
 }
 

package/src/remote/relayClient.ts

@@ -165,7 +165,7 @@ export interface RelayClientOptions {
    * This CLI's release version, reported so the relay can enforce the minimum
    * the served page was built against (the page itself is always the newest
    * one; the skew is handled by refusing old clients, not by keeping old
-   * pages — see the version note in `docs/specs/ui/remote-control.md`).
+   * pages — see the version note in `docs/specs/remote/remote-channel.md`).
    *
    * It sits at the **top level** of the auth frame, not inside `params`: that
    * is where the relay reads it, and a version it cannot parse is silently