wave-code 1.5.1 → 1.6.0

package/src/daemon/socketPath.ts

@@ -0,0 +1,123 @@
+/**
+ * Daemon socket addressing — one default, two platform shapes.
+ *
+ * POSIX keeps the file-socket it has always used (`~/.wave/daemon.sock`). On
+ * Windows libuv only accepts the `\\.\pipe\` shape: handing `net.Server.listen`
+ * a filesystem path fails with `EACCES` and the `.sock` file is never created,
+ * so the daemon could not start at all there. The default is therefore mapped to
+ * a named pipe on Windows.
+ *
+ * Two constraints shape the mapping:
+ * - the pipe namespace is **machine-global** (every OS user shares `\\.\pipe\`),
+ *   so the name must carry a per-user component — otherwise one user's daemon
+ *   occupies another's default socket;
+ * - a home path cannot be embedded verbatim, because `\` and `:` are illegal in
+ *   pipe names. Hence a stable digest of the default path, not the path itself.
+ *
+ * The mapping applies to **the default socket only**, and it is applied on both
+ * sides (client and `--daemon` server) by this one function. A name that is
+ * already a pipe, or any other path, is used verbatim: rewriting what the caller
+ * named would silently point the daemon somewhere else.
+ */
+
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+/** The default daemon socket as a file path — the shape POSIX listens on. */
+export const DEFAULT_DAEMON_SOCKET_FILE = path.join(
+  os.homedir(),
+  ".wave",
+  "daemon.sock",
+);
+
+/** libuv's Windows named-pipe prefixes (`\\.\pipe\` is the documented form). */
+const WINDOWS_PIPE_PREFIXES = ["\\\\.\\pipe\\", "\\\\?\\pipe\\"] as const;
+
+/** True when `socketPath` is already a Windows named-pipe name. */
+export function isWindowsPipeName(socketPath: string): boolean {
+  return WINDOWS_PIPE_PREFIXES.some((prefix) => socketPath.startsWith(prefix));
+}
+
+/**
+ * Derive the pipe name for a file-path socket. The digest is stable per path, so
+ * the same user always lands on the same name (a re-launched daemon finds and
+ * refuses to double-bind it), while different home directories — different OS
+ * users on one machine — land on different names.
+ */
+export function windowsPipeNameFor(socketFilePath: string): string {
+  const digest = createHash("sha256")
+    .update(socketFilePath)
+    .digest("hex")
+    .slice(0, 32);
+  return `\\\\.\\pipe\\wave-daemon-${digest}`;
+}
+
+/**
+ * Same file, allowing for how it was spelled — separator style, `.`/`..`
+ * segments, and (on Windows) letter case. A user who writes the default socket
+ * out by hand rarely matches `path.join`'s spelling byte for byte
+ * (`C:/Users/me/.wave/daemon.sock` vs `C:\Users\me\.wave\daemon.sock`), and
+ * missing that match would land the server on an `EACCES` instead of the pipe the
+ * client derives.
+ */
+function isSameFilePath(
+  a: string,
+  b: string,
+  platform: NodeJS.Platform,
+): boolean {
+  if (a === b) return true;
+  const resolvedA = path.resolve(a);
+  const resolvedB = path.resolve(b);
+  return platform === "win32"
+    ? resolvedA.toLowerCase() === resolvedB.toLowerCase()
+    : resolvedA === resolvedB;
+}
+
+/**
+ * Resolve the socket a caller means: identity on POSIX, and on Windows the pipe
+ * form of the default socket (anything else — an explicit path or a name that is
+ * already a pipe — is returned unchanged).
+ */
+export function resolveDaemonSocket(
+  platform: NodeJS.Platform,
+  socketPath: string,
+): string {
+  if (platform !== "win32") return socketPath;
+  if (isWindowsPipeName(socketPath)) return socketPath;
+  return isSameFilePath(socketPath, DEFAULT_DAEMON_SOCKET_FILE, platform)
+    ? // Digest the canonical spelling so every way of writing the default socket
+      // derives the same name — the pipe is a shared address, not a per-caller one.
+      windowsPipeNameFor(path.resolve(socketPath))
+    : socketPath;
+}
+
+/**
+ * The fixed default socket every `wave daemon` subcommand talks to (spec:
+ * 默认 socket 固定，形态随平台). No `--socket` override exists, so this is the
+ * only address the client side ever uses.
+ */
+export const DEFAULT_DAEMON_SOCKET = resolveDaemonSocket(
+  process.platform,
+  DEFAULT_DAEMON_SOCKET_FILE,
+);
+
+/**
+ * Translate a `listen` failure on a daemon address. `EADDRINUSE` is the shape a
+ * second daemon takes when the first one already holds the name — on Windows that
+ * is the *only* shape, since a pipe name has no stale file to probe first (the
+ * POSIX path detects the same situation by connecting to the socket file). The
+ * raw errno tells a user nothing actionable, so it becomes the same sentence both
+ * platforms report.
+ */
+export function describeListenError(
+  socketPath: string,
+  err: NodeJS.ErrnoException,
+): Error {
+  if (err.code === "EADDRINUSE") {
+    return new Error(
+      `Another wave daemon is already listening on ${socketPath}`,
+    );
+  }
+  return err;
+}

package/src/daemon-cli.ts

@@ -1,16 +1,18 @@
 /**
  * daemon-cli.ts — Entry point for `wave --daemon <socket-path>` mode.
  *
- * Starts a DaemonServer that serves JSON-RPC over a unix socket. The desktop
- * app launches this on a remote host via nohup/setsid and tunnels the socket
- * back with `ssh -L`; multiple attach/detach cycles share one process, so
- * sessions and pending permissions survive client disconnects. The net server
- * keeps the process alive — there is no stdin to wait on.
+ * Starts a DaemonServer that serves JSON-RPC over a local socket (a unix domain
+ * socket on POSIX, a named pipe on Windows). The desktop app launches this on a
+ * remote host via nohup/setsid and tunnels the socket back with `ssh -L`;
+ * multiple attach/detach cycles share one process, so sessions and pending
+ * permissions survive client disconnects. The net server keeps the process
+ * alive — there is no stdin to wait on.
  */
 
 import { ensureRuntimeDeps } from "wave-agent-sdk";
 import { DaemonServer } from "./stdio/daemonServer.js";
 import { createRemoteControlSinkFactory } from "./remote/remoteControlSink.js";
+import { resolveDaemonSocket } from "./daemon/socketPath.js";
 
 export async function startDaemonCli(socketPath: string): Promise<void> {
   // Install the on-demand runtime dependencies (image codec + ripgrep) before
@@ -19,10 +21,21 @@ export async function startDaemonCli(socketPath: string): Promise<void> {
   // since the host reports "daemon ready" on this socket.
   await ensureRuntimeDeps();
 
+  // Resolve the address exactly like the client does. The default path is the
+  // one name both sides must agree on, and on Windows it is reachable only in
+  // its pipe form — a caller that spells it out (`wave --daemon
+  // ~/.wave/daemon.sock`) must land on the same pipe the client derives, not on
+  // an EACCES. An explicit pipe name, or any other path, is used verbatim so a
+  // wrong address still fails loudly instead of being silently renamed.
+  const resolvedSocketPath = resolveDaemonSocket(process.platform, socketPath);
+
   // The resident daemon owns the remote sessions, so it is the process that
   // serves a paired phone. Off (undefined) unless the switch says otherwise.
   const createRemoteSink = createRemoteControlSinkFactory(process.cwd());
-  const server = new DaemonServer({ socketPath, createRemoteSink });
+  const server = new DaemonServer({
+    socketPath: resolvedSocketPath,
+    createRemoteSink,
+  });
   await server.start();
   // Ready — any error that follows goes to the daemon log via stderr.
 }

package/src/index.ts

@@ -11,6 +11,12 @@ import { createWorktree, type WorktreeSession } from "./utils/worktree.js";
 import path from "path";
 import { pathToFileURL } from "url";
 import { readNearestPackageJson } from "./utils/readPackageJson.js";
+import { ensurePlainNodeArgv } from "./utils/argvCompat.js";
+
+// Must run before `main()` builds its yargs instance (see argvCompat.ts):
+// when a host runs this bundle directly under Electron RUN_AS_NODE, yargs would
+// otherwise treat the script path as an unknown positional and exit 1.
+ensurePlainNodeArgv();
 
 const version = readNearestPackageJson().version;
 

package/src/print-cli.ts

@@ -10,7 +10,7 @@ import {
   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,
@@ -167,11 +167,12 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
       output.toolUpdate(params);
     },
 
-    // Error block callback
-    onErrorBlockAdded: (error: string) => {
-      // Display error blocks with distinct formatting
-      output.error(error);
-      diag(`\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`);
     },
   };
 
@@ -299,8 +300,14 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
           );
         }
         diag("\nDeleting worktree ...\n");
-        await removeWorktree(worktreeSession);
-        diag("Done.\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
         diag(`\n⚠️ Skipping worktree removal: ${(error as Error).message}\n`);
@@ -375,8 +382,11 @@ export async function startPrintCli(options: PrintCliOptions): Promise<void> {
             );
           }
           diag("\nDeleting worktree ...\n");
-          await removeWorktree(worktreeSession);
-          diag("Done.\n");
+          diag(
+            (await removeWorktree(worktreeSession))
+              ? "Done.\n"
+              : `\n${describeWorktreeSurvival(worktreeSession)}\n`,
+          );
         } catch (error) {
           diag(`\n⚠️ Skipping worktree removal: ${(error as Error).message}\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";

package/src/remote/notificationCoalescer.ts

@@ -80,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
@@ -102,7 +102,7 @@ function mergeSpec(method: string, params: unknown): MergeSpec | undefined {
   // 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, ui/remote-control.md
+  // (spec: ui/stdio-transport.md「流式通知纯增量负载」场景 7, remote/remote-web.md
   // 场景 10).
   if (method === "compactionContentUpdate") {
     if (typeof p.content !== "string") 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

package/src/remote/remoteControlCliHost.ts

@@ -10,7 +10,7 @@
  * white list and the page need no special case.
  *
  * Two consequences of "one session, and it is the one on screen", both
- * deliberate (docs/specs/ui/remote-control.md, 前台 CLI 故事):
+ * deliberate (docs/specs/remote/remote-web.md, 前台 CLI 故事):
  *
  * - Both ways of asking for the session list (`listDaemonSessions`, which the
  *   page reads, and `listSessions`) answer with exactly this session. The
@@ -42,6 +42,8 @@ import {
   hostSlashCommandsFor,
   toSlashCommandInfo,
 } from "../stdio/hostSlashCommands.js";
+import { readImagePreview } from "./imagePreview.js";
+import { readTextPreview } from "./textPreview.js";
 import { messagesForUi } from "../stdio/uiPayload.js";
 import {
   InvalidMessageWindowError,
@@ -163,6 +165,17 @@ export class RemoteControlCliHost implements RemoteControlHost {
       // 会落到「这台电脑上的会话不支持这个操作」——白名单放行 ≠ 宿主实现。
       case "getRecentWorkdirs":
         return { dirs: readRecentWorkdirs() };
+      // 远控页按需取图（spec「点消息里的图片路径看原图」）。与 daemon 那条
+      // 共用 `imagePreview.ts`：判型按解码后的真实容器、压到单帧预算内。
+      // 不实现的话页面会落到 hostUnsupported，而「白名单放行 ≠ 宿主实现」
+      // 这份规格已经踩过一次（见场景 7）。
+      case "getImagePreview":
+        return readImagePreview(typeof p.path === "string" ? p.path : "");
+      case "getTextPreview":
+        // 与取图同一条按需读取通道（spec remote/remote-web.md「点消息里的文件
+        // 路径看内容」）；前台 CLI 会话同样要能回，见图片故事场景 7 那条
+        // 「白名单放行 ≠ 宿主实现」。
+        return readTextPreview(typeof p.path === "string" ? p.path : "");
       case "rememberRecentWorkdir":
         rememberRecentWorkdir(typeof p.workdir === "string" ? p.workdir : "");
         return null;
@@ -203,11 +216,20 @@ export class RemoteControlCliHost implements RemoteControlHost {
           // business travelling over a relay (and would be dropped silently,
           // 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/slash-commands.md「弹窗里的宿主命令只有一份表」) — the same
+          // bytes the daemon returns, with one exception: `/resume` is dropped
+          // here, because this host holds exactly one session slot. Restoring a
+          // transcript from disk would mean replacing the session the user is
+          // watching in the terminal (and `initialize` is not implemented here
+          // either), so the row would be one that does nothing when picked —
+          // the exact defect the one-table rule forbids. The table declares the
+          // entry's ceiling; the host narrows it to what it can actually run
+          // (spec commands/slash-commands.md 场景 4).
           commands: [
             ...this.session.slashCommands().map(toSlashCommandInfo),
-            ...hostSlashCommandsFor("remote-page"),
+            ...hostSlashCommandsFor("remote-page").filter(
+              (command) => command.id !== "resume",
+            ),
           ],
         };
       default: