wave-code 1.3.0 → 1.5.0

package/src/remote/remoteControlCliHost.ts

@@ -0,0 +1,420 @@
+/**
+ * RemoteControlCliHost — serves the **interactive CLI's own session** to a
+ * phone.
+ *
+ * The daemon and each GUI host's `--stdio` child serve their sessions through
+ * `AgentBridge`, which owns a registry of them. The front end the user is
+ * typing in has no RPC server at all: one session, held in React state. Rather
+ * than pretend otherwise, this host implements the same three-method
+ * `RemoteControlHost` contract against that single session, so the relay, the
+ * 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 故事):
+ *
+ * - Both ways of asking for the session list (`listDaemonSessions`, which the
+ *   page reads, and `listSessions`) answer with exactly this session. The
+ *   phone's list is a navigation surface, and there is nothing else to navigate
+ *   to — scanning disk for older conversations would offer rows that cannot be
+ *   opened.
+ * - The host dies with its process. Nothing here survives the TUI exiting, and
+ *   that is the point: a session nobody holds cannot be served, only resumed
+ *   (as a new session).
+ */
+
+import type {
+  BackgroundTaskSummary,
+  Message,
+  PermissionDecision,
+  PermissionMode,
+  QueuedMessage,
+  SessionMetadata,
+  SlashCommand,
+  Task,
+  ToolPermissionContext,
+} 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,
+  normalizeMessageWindow,
+  type MessageWindow,
+  type MessageWindowResult,
+} from "./messageWindow.js";
+import {
+  REMOTE_HOST_UNSUPPORTED,
+  type RemoteControlHost,
+} from "./remoteControlService.js";
+
+/**
+ * What this host needs from the front end. Supplied by the chat hook, which
+ * owns all of it; every getter must return the **current** value (the host is
+ * long-lived and the session underneath it is not).
+ */
+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;
+  /** 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;
+  /** User-set title (the one `/rename` sets); undefined when it has none. */
+  customTitle(): string | undefined;
+  availableTools(): string[];
+  isLoading(): boolean;
+  hasRunningBackgroundWork(): boolean;
+  hasPendingMessages(): boolean;
+  /** The todo list (TaskCreate/TaskUpdate) — a *state*, the page re-reads it. */
+  tasks(): Task[];
+  isCompacting(): boolean;
+  isCommandRunning(): boolean;
+  queuedMessages(): QueuedMessage[];
+  /**
+   * Background tasks (shell / subagent / workflow) as the TUI holds them. Same
+   * role as `tasks`: the page's `/tasks` dialog reads the current set on its
+   * alignment paths, because the change notification only reports changes.
+   */
+  backgroundTasks(): BackgroundTaskSummary[];
+  /** Approvals waiting on the user right now (terminal or phone). */
+  pendingPermissions(): Array<{
+    requestId: string;
+    context: ToolPermissionContext;
+  }>;
+  sendMessage(text: string, force?: boolean): void | Promise<void>;
+  abort(): void;
+  setPermissionMode(mode: PermissionMode): void;
+  /** Resolve a pending approval, whichever side asked for it. */
+  respondPermission(requestId: string, decision: PermissionDecision): void;
+  /** Set this session's custom title (the value `wave -r` lists). */
+  renameSession(title: string): void | Promise<void>;
+  /** Compact this conversation, optionally with custom instructions. */
+  compact(customInstructions?: string): void | Promise<void>;
+  /**
+   * The slash commands this session offers (skills / custom commands). The
+   * page renders these as a menu; the SDK's own list is exactly what a phone
+   * can run, since host-local commands (`/plan`, `/config`, …) live outside it.
+   */
+  slashCommands(): SlashCommand[];
+}
+
+/** The JSON-RPC code for a rejected parameter (matches the daemon's answer). */
+const INVALID_PARAMS = -32602;
+
+function invalidParams(message: string): Error {
+  const err = new Error(message) as Error & { code?: number };
+  err.code = INVALID_PARAMS;
+  return err;
+}
+
+/**
+ * "The channel carries this method, this host does not." The white list is
+ * channel-wide (a daemon, a GUI's `--stdio` child and this foreground session all
+ * read the same set), while the three hosts implement different amounts of it:
+ * `AgentBridge` serves a registry of conversations, this host serves the one on
+ * screen and is wired to a subset. Answering `-32601` here would tell the page the
+ * method is unavailable over remote control at all — i.e. "upgrade the machine" —
+ * when the truth is "this machine can, this session cannot".
+ */
+function hostUnsupported(method: string): Error {
+  const err = new Error(
+    `Not implemented by a foreground CLI session: ${method}`,
+  ) as Error & { code?: number };
+  err.code = REMOTE_HOST_UNSUPPORTED;
+  return err;
+}
+
+export class RemoteControlCliHost implements RemoteControlHost {
+  constructor(private readonly session: RemoteControlCliSession) {}
+
+  async handleRequest(method: string, params: unknown): Promise<unknown> {
+    const p = (params ?? {}) as Record<string, unknown>;
+    switch (method) {
+      case "listSessions":
+        return this.listSessions();
+      case "listDaemonSessions":
+        return this.listDaemonSessions();
+      case "getSessionInfo":
+        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":
+        await this.session.sendMessage(
+          typeof p.text === "string" ? p.text : "",
+          p.force === true,
+        );
+        return null;
+      case "abortMessage":
+        this.session.abort();
+        return null;
+      case "setPermissionMode":
+        this.session.setPermissionMode(p.mode as PermissionMode);
+        return null;
+      case "renameSession": {
+        // The daemon's AgentBridge takes the target session from params (a host
+        // serves many). This host serves exactly one, so the title is the only
+        // input that means anything here — an empty one is a caller bug.
+        const title = typeof p.title === "string" ? p.title.trim() : "";
+        if (!title) throw invalidParams("renameSession requires a title");
+        await this.session.renameSession(title);
+        return null;
+      }
+      case "compact":
+        await this.session.compact(
+          typeof p.customInstructions === "string"
+            ? p.customInstructions
+            : undefined,
+        );
+        return null;
+      case "getSlashCommands":
+        return {
+          // 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). 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
+        // arriving here is a method the *channel* carries and this host does not
+        // (rewind, `clearMessages`, background tasks, `searchFiles`, … — see
+        // `REMOTE_HOST_UNSUPPORTED`). Said as exactly that, not as a bad
+        // parameter and not as silence: the page turns it into one visible line.
+        throw hostUnsupported(method);
+    }
+  }
+
+  handleNotification(method: string, params: unknown): void {
+    if (method !== "permissionResponse") return;
+    const p = (params ?? {}) as {
+      requestId?: unknown;
+      decision?: unknown;
+    };
+    if (typeof p.requestId !== "string" || !p.decision) return;
+    this.session.respondPermission(
+      p.requestId,
+      p.decision as PermissionDecision,
+    );
+  }
+
+  /**
+   * One row, one word. The relay turns a transition *into* `requires_action`
+   * into a Web Push, so this is what makes a phone ring when the terminal is
+   * waiting on an approval.
+   */
+  listSessionStatuses(): Array<{
+    sessionId: string;
+    status: "running" | "idle" | "requires_action";
+  }> {
+    const sessionId = this.session.sessionId();
+    if (!sessionId) return [];
+    if (this.session.pendingPermissions().length > 0) {
+      return [{ sessionId, status: "requires_action" }];
+    }
+    const busy =
+      this.session.isLoading() || this.session.hasRunningBackgroundWork();
+    return [{ sessionId, status: busy ? "running" : "idle" }];
+  }
+
+  private async listSessions(): Promise<{ sessions: SessionMetadata[] }> {
+    const sessionId = this.session.sessionId();
+    if (!sessionId) return { sessions: [] };
+    // Prefer the real record from disk — it carries the title, timestamps and
+    // token count the page renders. A session that has not been flushed yet
+    // has no record, and an empty list would read on the phone as "this
+    // machine has nothing to control", so synthesize the row instead.
+    try {
+      const persisted = await listSessions(this.session.workdir());
+      const mine = persisted.find((entry) => entry.id === sessionId);
+      if (mine) return { sessions: [mine] };
+    } catch {
+      // Unreadable project directory: the synthesized row is still the truth.
+    }
+    return { sessions: [this.synthesizedMetadata(sessionId)] };
+  }
+
+  private synthesizedMetadata(sessionId: string): SessionMetadata {
+    const now = new Date();
+    const firstMessage = this.session.threadSummary().firstUserText;
+    const customTitle = this.session.customTitle();
+    return {
+      id: sessionId,
+      sessionType: "main",
+      workdir: this.session.workdir(),
+      createdAt: now,
+      lastActiveAt: now,
+      latestTotalTokens: this.session.latestTotalTokens(),
+      ...(customTitle ? { customTitle } : {}),
+      ...(firstMessage ? { firstMessage } : {}),
+    };
+  }
+
+  /**
+   * The session list the page actually reads. A daemon has a real registry of
+   * them (`AgentBridge.listDaemonSessions`); this host holds exactly one, so its
+   * registry is that one — same shape, one row, and no disk read (the page can
+   * only open sessions that are live in the serving process, and this is the
+   * only one that is; see 规格 remote-control「边界情况」).
+   *
+   * Not `listSessions`: that reads the transcripts and would answer with rows
+   * the page cannot open — including this machine's older, unloaded ones.
+   */
+  private listDaemonSessions(): {
+    sessions: Array<{
+      sessionId: string;
+      sessionCwd: string;
+      isLoading: boolean;
+      hasRunningBackgroundWork: boolean;
+      hasPendingMessages: boolean;
+      messageCount: number;
+      /** User-set title; wins over `firstMessage` in the UI. */
+      customTitle?: string;
+      /** First real user message — the label when no custom title is set. */
+      firstMessage?: string;
+      /** Last display message's timestamp: the session list's ordering key. */
+      lastActiveAt?: string;
+    }>;
+  } {
+    const sessionId = this.session.sessionId();
+    if (!sessionId) return { sessions: [] };
+    const customTitle = this.session.customTitle();
+    const summary = this.session.threadSummary();
+    const firstMessage = summary.firstUserText;
+    const lastActiveAt = summary.lastActiveAt;
+    return {
+      sessions: [
+        {
+          sessionId,
+          sessionCwd: this.session.sessionCwd(),
+          isLoading: this.session.isLoading(),
+          hasRunningBackgroundWork: this.session.hasRunningBackgroundWork(),
+          hasPendingMessages: this.session.hasPendingMessages(),
+          messageCount: summary.messageCount,
+          ...(customTitle ? { customTitle } : {}),
+          ...(firstMessage ? { firstMessage } : {}),
+          ...(lastActiveAt ? { lastActiveAt } : {}),
+        },
+      ],
+    };
+  }
+
+  private getSessionInfo(): {
+    sessionId: string;
+    sessionCwd: string;
+    latestTotalTokens: number;
+    permissionMode: PermissionMode;
+    availableTools: string[];
+    tasks: Task[];
+    isCompacting: boolean;
+    isCommandRunning: boolean;
+    queuedMessages: QueuedMessage[];
+    backgroundTasks: BackgroundTaskSummary[];
+  } {
+    return {
+      sessionId: this.session.sessionId(),
+      sessionCwd: this.session.sessionCwd(),
+      latestTotalTokens: this.session.latestTotalTokens(),
+      permissionMode: this.session.permissionMode(),
+      availableTools: this.session.availableTools(),
+      // The session-state family the page re-reads (spec remote-control
+      // 「Web 页作为第五种宿主」场景 26): current values, not transitions.
+      tasks: this.session.tasks(),
+      isCompacting: this.session.isCompacting(),
+      isCommandRunning: this.session.isCommandRunning(),
+      queuedMessages: this.session.queuedMessages(),
+      backgroundTasks: this.session.backgroundTasks(),
+    };
+  }
+
+  private async getMessages(p: Record<string, unknown>): Promise<{
+    messages: Message[];
+    contextUsagePercent: number;
+    reset?: boolean;
+  }> {
+    const contextUsagePercent = this.session.contextUsagePercent();
+    const window: MessageWindow = {};
+    if (typeof p.since === "string") window.since = p.since;
+    if (p.limit !== undefined) window.limit = Number(p.limit);
+
+    let normalized: MessageWindow | undefined;
+    try {
+      normalized = normalizeMessageWindow(window);
+    } catch (err) {
+      if (err instanceof InvalidMessageWindowError)
+        throw invalidParams(err.message);
+      throw err;
+    }
+    // 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(): {
+    requests: Array<{
+      requestId: string;
+      sessionId?: string;
+      context: ToolPermissionContext;
+    }>;
+  } {
+    const sessionId = this.session.sessionId();
+    return {
+      requests: this.session.pendingPermissions().map((pending) => ({
+        requestId: pending.requestId,
+        ...(sessionId ? { sessionId } : {}),
+        context: pending.context,
+      })),
+    };
+  }
+}

package/src/remote/remoteControlCommands.ts

@@ -0,0 +1,197 @@
+/**
+ * `wave remote-control` — the operator's handle on the relay connection.
+ *
+ * These subcommands serve the **daemon**: it is the resident host (it owns
+ * sessions across client detach/attach and keeps generating while nothing is
+ * attached), and it is the process whose emit fan-out the relay subscribes to.
+ * They are therefore a client of the daemon socket, exactly like `wave daemon …`
+ * — `on` starts a daemon on demand, `off`/`status` never do.
+ *
+ * A session that lives in the *foreground* CLI process is out of reach from
+ * here; that process serves itself through the TUI's `/remote-control` command
+ * (see `remoteControlCliHost.ts`). The switch can be on for both at once without
+ * either one covering the other's sessions.
+ *
+ * The page address a phone opens is assembled from this machine's channel key,
+ * which the daemon got by registering with the relay (an HTTP call) — nothing is
+ * pushed down the WebSocket for it. So `on` may have to wait for a registration
+ * round trip, and everything it learned stays on the daemon, where `status` can
+ * pick it up.
+ *
+ * All subcommands are non-interactive (stdout for results, stderr for
+ * diagnostics, exit code set here) — yargs would otherwise fall through to the
+ * Ink TUI.
+ */
+
+import { toString as qrToString } from "qrcode";
+import type { RemoteControlSnapshot } from "wave-agent-sdk";
+import {
+  DEFAULT_DAEMON_SOCKET,
+  connectDaemonIfRunning,
+  connectDaemonOrExit,
+} from "../daemon/commands.js";
+import type { SocketClient } from "../daemon/socketClient.js";
+
+/** How long `on` waits for the page address to come back from the daemon. */
+export const PAGE_WAIT_MS = 5_000;
+const PAGE_POLL_MS = 500;
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * The switch lives in settings, so a daemon started before it was turned on
+ * cannot serve — and the error it returns says which key to set but not that
+ * the running daemon has to be replaced for the change to take effect.
+ */
+function hintFor(message: string): string | undefined {
+  if (!message.includes("enableRemoteControl")) return undefined;
+  return 'Set "enableRemoteControl": true in ~/.wave/settings.json (or .wave/settings.json in the project), then run `wave daemon restart` — a daemon that was already running keeps its old settings.';
+}
+
+function printEnableHint(message: string): void {
+  console.error(message);
+  const hint = hintFor(message);
+  if (hint) console.error(hint);
+}
+
+/**
+ * Print the page the phone should open, and a QR of that page.
+ *
+ * The options are Claude Code's bridge-dialog pair (`type: "utf8"`,
+ * `errorCorrectionLevel: "L"`) minus its `small: true`, which is inert here:
+ * node-qrcode reads `small` only in the *terminal* renderer, and `utf8` is
+ * already the compact half-block form (`▀▄█`) with no ANSI — so the code stays
+ * copyable out of a terminal. Encoding is the only thing that can fail (and only
+ * for absurd input), and the address printed above is the real contract — a
+ * missing QR is not worth failing the command.
+ */
+async function printPageUrl(pageUrl: string): Promise<void> {
+  console.log("");
+  console.log(`Web 页：${pageUrl}`);
+  console.log(
+    "手机：用相机扫码或在 Safari 中打开，再「添加到主屏幕」（控制中心的扫码器打开的容器加不了主屏）。",
+  );
+  try {
+    console.log(
+      await qrToString(pageUrl, {
+        type: "utf8",
+        errorCorrectionLevel: "L",
+      }),
+    );
+  } catch {
+    // Nothing to add: the line above already carries the address.
+  }
+}
+
+/** Poll the daemon until the registration round trip hands back a page address. */
+async function waitForPageUrl(
+  client: SocketClient,
+  initial: RemoteControlSnapshot,
+): Promise<string | undefined> {
+  const deadline = Date.now() + PAGE_WAIT_MS;
+  let snapshot = initial;
+  while (Date.now() < deadline) {
+    if (snapshot.pageUrl) return snapshot.pageUrl;
+    if (snapshot.state === "error") {
+      printEnableHint(`远程控制连接失败：${snapshot.message ?? "未知错误"}`);
+      process.exit(1);
+    }
+    await new Promise((resolve) => setTimeout(resolve, PAGE_POLL_MS));
+    snapshot = (await client.request(
+      "remoteControlStatus",
+      {},
+    )) as RemoteControlSnapshot;
+  }
+  return snapshot.pageUrl;
+}
+
+/**
+ * Turn remote control on for this machine and show the page a phone opens.
+ * Idempotent: running it while already online re-reads the same address.
+ */
+export async function remoteControlOnCommand(name?: string): Promise<void> {
+  let client: SocketClient | undefined;
+  try {
+    client = await connectDaemonOrExit(DEFAULT_DAEMON_SOCKET);
+    const connecting = (await client.request(
+      "remoteControlConnect",
+      name ? { name } : {},
+    )) as RemoteControlSnapshot;
+
+    if (connecting.state === "error") {
+      printEnableHint(`远程控制开启失败：${connecting.message ?? "未知错误"}`);
+      process.exit(1);
+    }
+
+    const pageUrl = await waitForPageUrl(client, connecting);
+    if (!pageUrl) {
+      console.error("远程控制已连上，但没能从 daemon 拿到页面地址。");
+      process.exit(1);
+    }
+    await printPageUrl(pageUrl);
+    console.log("");
+    console.log("关闭远程控制：`wave remote-control off`");
+  } catch (err) {
+    printEnableHint(`wave remote-control on 失败：${describe(err)}`);
+    process.exit(1);
+  } finally {
+    client?.dispose();
+  }
+  process.exit(0);
+}
+
+/**
+ * Disconnect. Idempotent, and like `wave daemon stop` it never starts a daemon
+ * — with nothing running there is nothing to turn off.
+ */
+export async function remoteControlOffCommand(): Promise<void> {
+  const client = await connectDaemonIfRunning(DEFAULT_DAEMON_SOCKET);
+  if (!client) {
+    console.log("远程控制未开启（wave daemon 未运行）");
+    process.exit(0);
+  }
+  try {
+    await client.request("remoteControlDisconnect", {});
+    console.log("远程控制已断开");
+  } catch (err) {
+    // "Not enabled" lands here too: the daemon has no relay at all, which is
+    // the same end state the user asked for, so it is reported as success —
+    // with the switch hint on stderr, because turning it on would change that.
+    const message = describe(err);
+    console.log(`远程控制已关闭（${message}）`);
+    const hint = hintFor(message);
+    if (hint) console.error(hint);
+  } finally {
+    client.dispose();
+  }
+  process.exit(0);
+}
+
+/** Report the connection state, and the page address when there is one. */
+export async function remoteControlStatusCommand(): Promise<void> {
+  const client = await connectDaemonIfRunning(DEFAULT_DAEMON_SOCKET);
+  if (!client) {
+    console.log("状态：未开启（wave daemon 未运行）");
+    process.exit(0);
+  }
+  let ok = true;
+  try {
+    const snapshot = (await client.request(
+      "remoteControlStatus",
+      {},
+    )) as RemoteControlSnapshot;
+    console.log(`状态：${snapshot.state}`);
+    if (snapshot.message) console.log(`说明：${snapshot.message}`);
+    if (snapshot.pageUrl) await printPageUrl(snapshot.pageUrl);
+  } catch (err) {
+    // Unlike `off`, a status we could not read is a real failure: the daemon
+    // may be an older build that predates this method.
+    ok = false;
+    printEnableHint(`读取远程控制状态失败：${describe(err)}`);
+  } finally {
+    client.dispose();
+  }
+  process.exit(ok ? 0 : 1);
+}