wave-code 1.3.0 → 1.4.0

package/src/contexts/useChat.tsx

@@ -5,10 +5,13 @@ import React, {
   useRef,
   useEffect,
   useState,
-  useMemo,
 } from "react";
 import { useInput, useStdout } from "ink";
 import { useAppConfig } from "./useAppConfig.js";
+import {
+  useRemoteControl,
+  type RemoteControlApi,
+} from "../hooks/useRemoteControl.js";
 import type {
   Message,
   McpServerStatus,
@@ -34,13 +37,64 @@ import {
   PLUGIN_CHANGE_PENDING_MESSAGE,
   PLUGIN_RELOADED_MESSAGE,
 } from "wave-agent-sdk";
+import { toString as qrToString } from "qrcode";
 import { logger } from "../utils/logger.js";
 import { displayUsageSummary } from "../utils/usageSummary.js";
 import { expandLongTextPlaceholders } from "../managers/inputHandlers.js";
+import { remoteNotifications } from "../remote/remoteNotifications.js";
+import type { RemoteNotify } from "../remote/remoteNotifications.js";
 import { readFile } from "node:fs/promises";
 
 import { BaseAppProps } from "../types.js";
 
+/** How long `/remote-control` waits for the relay's registration round trip. */
+const REMOTE_PAGE_WAIT_MS = 5_000;
+const REMOTE_PAGE_POLL_MS = 250;
+
+/**
+ * Wait for the page address. It is assembled from this machine's channel key
+ * after the relay registers it (an HTTP call) — nothing is pushed down the
+ * WebSocket — so the first snapshot may not carry it yet.
+ */
+async function waitForRemotePageUrl(
+  api: RemoteControlApi,
+): Promise<string | undefined> {
+  const deadline = Date.now() + REMOTE_PAGE_WAIT_MS;
+  while (Date.now() < deadline) {
+    const snapshot = api.getSnapshot();
+    if (snapshot.pageUrl) return snapshot.pageUrl;
+    if (snapshot.state === "error") return undefined;
+    await new Promise((resolve) => setTimeout(resolve, REMOTE_PAGE_POLL_MS));
+  }
+  return api.getSnapshot().pageUrl;
+}
+
+/**
+ * The result block a TUI session shows: the same address and the same QR that
+ * `wave remote-control on` prints, because that pair is the whole contract with
+ * the phone — the two entry points must not diverge on how it is rendered.
+ */
+async function describeRemotePage(pageUrl: string): Promise<string> {
+  const lines = [
+    "Remote control is on — this terminal's session is now served to your phone.",
+    `Page: ${pageUrl}`,
+  ];
+  try {
+    lines.push(
+      "",
+      await qrToString(pageUrl, {
+        type: "utf8",
+        errorCorrectionLevel: "L",
+      }),
+    );
+  } catch {
+    // The address above already carries the contract; a missing QR is not worth
+    // failing the command over.
+  }
+  lines.push("", "Turn it off with /remote-control off");
+  return lines.join("\n");
+}
+
 // Main Chat Context
 export interface PlanViewData {
   path?: string;
@@ -132,6 +186,19 @@ export interface ChatContextType {
   // Permission functionality
   permissionMode: PermissionMode;
   setPermissionMode: (mode: PermissionMode) => void;
+  /**
+   * Remote control for **this** foreground session. The process the user is
+   * typing in is the one that dials out — not the daemon, which cannot reach a
+   * session that only exists here.
+   */
+  remoteControl: RemoteControlApi;
+  /**
+   * `/remote-control [on|off|status] [name]` — the TUI-side switch for the hook
+   * above. Its CLI namesake talks to the daemon instead; the two are not
+   * interchangeable, because a session that lives in this process is reachable
+   * only from this process.
+   */
+  remoteControlCommand: (args?: string) => Promise<void>;
   // /plan overlay state + handler
   planView: PlanViewData | null;
   setPlanView: (view: PlanViewData | null) => void;
@@ -349,81 +416,6 @@ const applyToolBlockUpdate = (
   });
 };
 
-/**
- * Single throttled updater entry for ALL message-state updates. The one
- * 500ms window-concat window replaces the previous three-channel throttles
- * (content/reasoning/tool), so every message-state update — including the
- * tool `running` stage's high-frequency `shortResult`/`result` updates from
- * bash — coalesces into the same window.
- *
- * Semantics: leading edge applies immediately and opens a window; updates
- * arriving within the window are queued in arrival order (FIFO) and applied
- * at the trailing edge as ONE composed updater, so no update is lost and no
- * update is reordered. `flush` applies queued updates immediately (used by
- * end signals and one-shot structural updates); `cancel` drops queued
- * updates (used by refreshMessages after pulling the authoritative snapshot —
- * the queued updates are already contained in it).
- *
- * The FIFO queue structurally replaces the old tool throttle's "drop a
- * tool's buffered streaming deltas when running arrives" logic: a running
- * updater is queued BEHIND the streaming chunks that preceded it and applies
- * after them, so a stale streaming event can never flush after running and
- * regress the stage (yellow dot -> gray). See
- * docs/specs/core/stream-content-updates.md.
- */
-export function createThrottledUpdater<T>(
-  apply: (updater: (prev: T) => T) => void,
-  wait: number,
-): {
-  (updater: (prev: T) => T): void;
-  cancel: () => void;
-  flush: () => void;
-} {
-  let timer: NodeJS.Timeout | null = null;
-  let queued: Array<(prev: T) => T> = [];
-
-  const fire = () => {
-    if (queued.length === 0) return;
-    const batch = queued;
-    queued = [];
-    // Compose the whole batch into a single updater applied in FIFO order —
-    // one state commit per trailing edge, no update dropped, no reordering.
-    apply((prev) => batch.reduce((acc, upd) => upd(acc), prev));
-  };
-
-  const throttled = (updater: (prev: T) => T) => {
-    if (timer) {
-      queued.push(updater);
-      return;
-    }
-    // Leading edge: apply immediately, then open a window whose trailing
-    // edge only carries updates arriving within the window.
-    apply(updater);
-    timer = setTimeout(() => {
-      timer = null;
-      fire();
-    }, wait);
-  };
-
-  throttled.cancel = () => {
-    if (timer) {
-      clearTimeout(timer);
-      timer = null;
-    }
-    queued = [];
-  };
-
-  throttled.flush = () => {
-    if (timer) {
-      clearTimeout(timer);
-      timer = null;
-    }
-    fire();
-  };
-
-  return throttled;
-}
-
 export const ChatProvider: React.FC<ChatProviderProps> = ({
   children,
   bypassPermissions,
@@ -454,26 +446,16 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   const [latestTotalTokens, setLatestTotalTokens] = useState(0);
   const [maxInputTokens, setMaxInputTokens] = useState(200000);
 
-  // Single throttled entry for ALL message-state updates — one 500ms
-  // window-concat window shared by every callback (content/reasoning deltas,
-  // tool parametersChunk, tool `running` stage shortResult/result, one-shot
-  // structural updates). The tool `running` stage used to bypass throttling
-  // (bash shortResult height changes per chunk → layout flicker); routing it
-  // through the same window as streaming deltas coalesces it to ≤1 render per
-  // window. See createThrottledUpdater + docs/specs/core/stream-content-updates.md.
-  const updateMessages = useMemo(
-    () =>
-      createThrottledUpdater<Message[]>((updater) => setMessages(updater), 500),
-    [],
-  );
+  // All message-state updates apply IMMEDIATELY via setMessages — no data-layer
+  // throttling (removed 2026-10-15 after observing fully-immediate rendering in
+  // a real terminal with no flicker: Ink's log-update only rewrites the dynamic
+  // zone tail and its built-in maxFps:30 coalesces short-result line-count
+  // oscillation). Arrival order = application order. See
+  // docs/specs/core/stream-content-updates.md (2026-10-15 会议).
 
   useEffect(() => {
     isExpandedRef.current = isExpanded;
-    if (isExpanded) {
-      // Cancel pending throttled updates so the frozen expanded view isn't overwritten
-      updateMessages.cancel();
-    }
-  }, [isExpanded, updateMessages]);
+  }, [isExpanded]);
 
   const [isLoading, setIsLoading] = useState(false);
   const [sessionId, setSessionId] = useState("");
@@ -538,6 +520,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   >();
   const [confirmationQueue, setConfirmationQueue] = useState<
     Array<{
+      requestId: string;
       toolName: string;
       toolInput?: Record<string, unknown>;
       suggestedPrefix?: string;
@@ -551,6 +534,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     }>
   >([]);
   const [currentConfirmation, setCurrentConfirmation] = useState<{
+    requestId: string;
     toolName: string;
     toolInput?: Record<string, unknown>;
     suggestedPrefix?: string;
@@ -563,6 +547,37 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     reject: () => void;
   } | null>(null);
 
+  /**
+   * The same approvals, keyed by id, so a phone can answer them.
+   *
+   * The queue above is the terminal's view of "what am I waiting on"; this map
+   * is the phone's. Both resolve the same promise, so whichever side answers
+   * first wins — that is the whole of the concurrency rule (spec: 前台 CLI
+   * 故事场景 5), and it needs no arbitration beyond "delete on settle".
+   */
+  const remotePendingRef = useRef<
+    Map<
+      string,
+      {
+        context: ToolPermissionContext;
+        settle: (decision: PermissionDecision) => void;
+      }
+    >
+  >(new Map());
+  const [remotePending, setRemotePending] = useState<
+    Array<{ requestId: string; context: ToolPermissionContext }>
+  >([]);
+  const permissionCounterRef = useRef(0);
+
+  const syncRemotePending = useCallback(() => {
+    setRemotePending(
+      [...remotePendingRef.current.entries()].map(([requestId, entry]) => ({
+        requestId,
+        context: entry.context,
+      })),
+    );
+  }, []);
+
   // Remount state
   const [remountKey, setRemountKey] = useState(0);
 
@@ -580,6 +595,14 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
 
   const agentRef = useRef<Agent | null>(null);
 
+  /**
+   * The notifier the remote path's content-carrying frames go out through (see
+   * `remoteNotifications`). A ref because the agent callbacks are built in
+   * `initializeAgent` below, before this component has the hook that owns the
+   * connection.
+   */
+  const remoteNotifyRef = useRef<RemoteNotify | undefined>(undefined);
+
   // Full-list refresh — one-shot pull from the agent, used only for structural
   // changes (compact/clear/rewind/collapse/init). Streaming updates flow through
   // the incremental callbacks in initializeAgent below.
@@ -588,19 +611,14 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       // Pull the full UI display stream (keeps pre-compaction history);
       // `agent.messages` would only expose the folded API context.
       const msgs = agentRef.current.displayMessages.map(snapshotMessage);
-      // Snapshot-safe: the full-list replacement makes the SDK state
-      // authoritative. Any update still queued inside the 500ms throttle
-      // window was applied to the SDK before this pull, so it is already
-      // contained in `msgs` — dropping it prevents the trailing-edge flush
-      // from re-appending the pre-refresh chunk on top of the snapshot
-      // (first-word duplication). Updates arriving after the pull start fresh
-      // windows and append on top of the snapshot. See
-      // docs/specs/core/stream-content-updates.md.
-      updateMessages.cancel();
+      // The snapshot makes the SDK state authoritative: with no throttle
+      // window there is nothing pending to cancel — every pre-pull update is
+      // already applied and contained in `msgs`, and post-pull deltas append
+      // on top of the snapshot. See docs/specs/core/stream-content-updates.md.
       setMessages(msgs);
       setLatestTotalTokens(extractLatestTotalTokens(msgs));
     }
-  }, [updateMessages]);
+  }, []);
 
   // Permission confirmation methods with queue support
   const showConfirmation = useCallback(
@@ -614,8 +632,38 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       warning?: string,
       outsideSafeZoneDirectory?: string,
     ): Promise<PermissionDecision> => {
+      const requestId = `cli_perm_${++permissionCounterRef.current}`;
       return new Promise<PermissionDecision>((resolve, reject) => {
+        const context: ToolPermissionContext = {
+          toolName,
+          ...(toolInput ? { toolInput } : {}),
+          ...(suggestedPrefix ? { suggestedPrefix } : {}),
+          ...(hidePersistentOption !== undefined
+            ? { hidePersistentOption }
+            : {}),
+          ...(outsideSafeZoneDirectory ? { outsideSafeZoneDirectory } : {}),
+          ...(planContent ? { planContent } : {}),
+          // Required on the context, and the phone renders it: which mode this
+          // request is being judged under.
+          permissionMode: permissionMode ?? "default",
+          ...(warning ? { warning } : {}),
+        };
+        // Settling through the map is what keeps the phone's list honest: an
+        // approval answered at the terminal must vanish from the phone too.
+        const settle = (decision: PermissionDecision) => {
+          remotePendingRef.current.delete(requestId);
+          syncRemotePending();
+          resolve(decision);
+        };
+        const cancel = () => {
+          remotePendingRef.current.delete(requestId);
+          syncRemotePending();
+          reject();
+        };
+        remotePendingRef.current.set(requestId, { context, settle });
+        syncRemotePending();
         const queueItem = {
+          requestId,
           toolName,
           toolInput,
           suggestedPrefix,
@@ -624,15 +672,15 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           planContent,
           permissionMode,
           warning,
-          resolver: resolve,
-          reject,
+          resolver: settle,
+          reject: cancel,
         };
 
         setConfirmationQueue((prev) => [...prev, queueItem]);
         // processNextConfirmation will be called via useEffect
       });
     },
-    [],
+    [syncRemotePending],
   );
 
   // Initialize AI manager
@@ -641,10 +689,23 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       const effectiveRestoreSessionId =
         restoreSessionIdOverride ?? restoreSessionId;
 
+      // The remote path's copy of the payload-carrying frames (see
+      // `remoteNotifications`: the streaming trio plus the error block), emitted
+      // *beside* the local state updates — never instead of them, and outside the
+      // `isExpanded` guards below, because the TUI's own view mode is not the
+      // phone's. Built only while a sink exists, so a process with remote control
+      // off allocates nothing per chunk.
+      const remoteNotify = remoteNotifyRef.current;
+      const remoteStream = remoteNotify
+        ? remoteNotifications(remoteNotify)
+        : undefined;
+
       const callbacks: AgentCallbacks = {
         // ── Incremental message updates (no full-list pushes) ──────
-        // All of these funnel through the single throttled `updateMessages`
-        // entry, so every message-state update shares one 500ms window.
+        // Every update applies immediately via setMessages — no data-layer
+        // throttling (removed 2026-10-15, see docs/specs/core/stream-content-updates.md).
+        // Arrival order = application order; terminal write frequency is
+        // bounded by Ink's built-in maxFps:30.
         onUserMessageAdded: () => {
           if (isExpandedRef.current || !agentRef.current) return;
           const msgs = agentRef.current.messages;
@@ -654,12 +715,11 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           // the batch flush, so evaluating snapshotMessage inside the updater
           // would read the SDK message after its in-place mutations.
           const snapshot = snapshotMessage(last);
-          updateMessages((prev) =>
+          // One-shot structural update — applied directly (a window would
+          // only delay the message card, no coalescing value).
+          setMessages((prev) =>
             prev.some((m) => m.id === last.id) ? prev : [...prev, snapshot],
           );
-          // One-shot structural update — flush immediately so the message
-          // card appears at once (queuing it gains no coalescing).
-          updateMessages.flush();
         },
         onAssistantMessageAdded: (messageId: string) => {
           if (isExpandedRef.current || !agentRef.current) return;
@@ -669,29 +729,43 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           // fires this callback BEFORE the first delta writes into the shared
           // message, so capturing here copies the pre-mutation (empty) blocks.
           const snapshot = snapshotMessage(msg);
-          updateMessages((prev) =>
+          setMessages((prev) =>
             prev.some((m) => m.id === messageId) ? prev : [...prev, snapshot],
           );
-          updateMessages.flush();
+        },
+        onAssistantMessageDiscarded: (messageId: string) => {
+          // The streamed attempt died mid-body and was re-issued without
+          // streaming; its half message is void (spec: 流式响应正文中途断连时
+          // 降级为非流式重发).
+          if (isExpandedRef.current) return;
+          setMessages((prev) => prev.filter((m) => m.id !== messageId));
         },
         onAssistantContentUpdated: (params) => {
+          remoteStream?.onAssistantContentUpdated(params);
           if (isExpandedRef.current) return;
-          updateMessages((prev) => applyContentDelta(prev, params));
-          if (params.stage === "end") updateMessages.flush();
+          // Text delta: height grows monotonically → per-delta application.
+          // No flush on end: this channel has no pending updates, and the
+          // tool-running window must not be cut short by a text end.
+          setMessages((prev) => applyContentDelta(prev, params));
         },
         onAssistantReasoningUpdated: (params) => {
+          remoteStream?.onAssistantReasoningUpdated(params);
           if (isExpandedRef.current) return;
-          updateMessages((prev) => applyReasoningDelta(prev, params));
-          if (params.stage === "end") updateMessages.flush();
+          setMessages((prev) => applyReasoningDelta(prev, params));
         },
         onToolBlockUpdated: (params) => {
+          remoteStream?.onToolBlockUpdated(params);
           if (isExpandedRef.current) return;
-          updateMessages((prev) => applyToolBlockUpdate(prev, params));
-          if (params.stage === "end") updateMessages.flush();
+          // All stages (start/streaming/running/end) apply directly —
+          // `end` carries the authoritative final values.
+          setMessages((prev) => applyToolBlockUpdate(prev, params));
         },
         onErrorBlockAdded: (error: string) => {
+          remoteStream?.onErrorBlockAdded(error);
           if (isExpandedRef.current) return;
-          updateMessages((prev) => {
+          // One-shot structural update — applied directly (errors must not be
+          // delayed by the tool-running window).
+          setMessages((prev) => {
             // Append to the LAST message only if it is an assistant message
             // (the current turn's in-flight reply). If the last message is a
             // user message, the error belongs BELOW it — create a new
@@ -719,9 +793,6 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
               },
             ];
           });
-          // One-shot structural update — flush immediately (errors must not be
-          // delayed by a streaming window).
-          updateMessages.flush();
         },
         onLatestTotalTokensChange: (tokens) => {
           setLatestTotalTokens(tokens);
@@ -828,6 +899,8 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           isNewWorktree: worktreeSession?.isNew,
           model,
           mcpServers,
+          // This session was created from the interactive CLI → `app.entrypoint`.
+          entrypoint: "cli",
         });
 
         agentRef.current = agent;
@@ -910,7 +983,6 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       originalCwd,
       model,
       initialPermissionMode,
-      updateMessages,
       mcpServers,
     ],
   );
@@ -968,7 +1040,6 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   // Cleanup on unmount
   useEffect(() => {
     return () => {
-      updateMessages.cancel();
       if (agentRef.current) {
         try {
           // Display usage summary before cleanup
@@ -982,7 +1053,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
         agentRef.current.destroy();
       }
     };
-  }, [updateMessages]);
+  }, []);
 
   // Send message function (including judgment logic)
   const sendMessage = useCallback(
@@ -1334,6 +1405,165 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     hideConfirmation();
   }, [currentConfirmation, hideConfirmation]);
 
+  // Mirrors for the remote-control host: it outlives any single render, so it
+  // must read the confirmation showing *now* rather than the one captured when
+  // it was built.
+  const currentConfirmationRef = useRef<typeof currentConfirmation>(null);
+  useEffect(() => {
+    currentConfirmationRef.current = currentConfirmation;
+  }, [currentConfirmation]);
+  const hideConfirmationRef = useRef(hideConfirmation);
+  useEffect(() => {
+    hideConfirmationRef.current = hideConfirmation;
+  }, [hideConfirmation]);
+
+  /**
+   * Answer an approval from the phone. It settles the same promise the terminal
+   * is waiting on, so this advances the session exactly as pressing the key
+   * would — and if that request is the one on screen, the dialog goes away.
+   */
+  const respondPermission = useCallback(
+    (requestId: string, decision: PermissionDecision) => {
+      const entry = remotePendingRef.current.get(requestId);
+      if (!entry) return;
+      entry.settle(decision);
+      if (currentConfirmationRef.current?.requestId === requestId) {
+        hideConfirmationRef.current();
+      }
+    },
+    [],
+  );
+
+  const getAvailableTools = useCallback(
+    () => agentRef.current?.getAvailableToolNames() ?? [],
+    [],
+  );
+
+  // Serve this foreground session to a phone, if the switch allows it. The hook
+  // owns the outbound connection; it reads current state through a ref, so
+  // passing the values here (rather than wiring callbacks into every setter) is
+  // what keeps this the whole of the integration.
+  const remoteControl = useRemoteControl({
+    workdir: workdir ?? process.cwd(),
+    sessionId,
+    messages,
+    isLoading,
+    permissionMode,
+    latestTotalTokens,
+    maxInputTokens,
+    // 手机侧会话列表的标题材料：`customTitle` 不走 React state（agent 自己存着，
+    // 重命名后即刻生效），所以按「取当前值」的函数递给门面。
+    customTitle: () => agentRef.current?.customTitle,
+    hasRunningBackgroundWork: backgroundTasks.length > 0,
+    hasPendingMessages: queuedMessages.length > 0,
+    // 场景 26 的会话状态族：远控页按状态重读 `getSessionInfo`，这四个是它的
+    // 当前值（回调本就把它们写进 state，这里原样递给门面即可）。
+    tasks,
+    backgroundTasks,
+    isCompacting,
+    isCommandRunning,
+    queuedMessages,
+    pending: remotePending,
+    availableTools: getAvailableTools,
+    sendMessage: (text) => sendMessage(text),
+    abort: () => agentRef.current?.abortMessage(),
+    setPermissionMode,
+    respondPermission,
+    // 会话自身的维护动作（重命名 / 压缩 / 指令清单）：页面能直接用，且都由这一份
+    // 会话状态来答，所以给的是「取当前值」的函数。重命名走 agent 而非 /rename 命令，
+    // 是为了让失败以 RPC 错误回给页面（TUI 那条路径把错误渲染成一条消息）。
+    renameSession: (title) => agentRef.current?.renameSession(title),
+    compact: (instructions) => compact(instructions),
+    slashCommands: () => agentRef.current?.getSlashCommands() ?? [],
+  });
+
+  // `initializeAgent` reads this ref when it runs, which is always in an effect
+  // — after this render. `notify` is stable (the hook builds it once, over a sink
+  // it creates once), so assigning it during render is enough to have it in place
+  // before anything can call the agent.
+  remoteNotifyRef.current = remoteControl.notify;
+
+  /**
+   * `/remote-control [on|off|status] [name]` — offer this terminal's session to
+   * a phone. It is deliberately *not* a front end for `wave remote-control`:
+   * that subcommand drives the daemon, and this session exists only in this
+   * process, so the daemon could not serve it (spec: remote-control.md,
+   * "前台 CLI 会话也能被手机接管").
+   */
+  const remoteControlCommand = useCallback(
+    async (args?: string) => {
+      const showResult = (content: string) => {
+        setMessages((prev) => [
+          ...prev,
+          {
+            id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+            role: "assistant",
+            timestamp: new Date().toISOString(),
+            blocks: [{ type: "text", content, stage: "end" }],
+          },
+        ]);
+      };
+
+      const parts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+      const action = parts[0]?.toLowerCase() ?? "";
+      if (
+        action &&
+        action !== "on" &&
+        action !== "off" &&
+        action !== "status"
+      ) {
+        showResult("Usage: /remote-control [on|off|status] [name]");
+        return;
+      }
+
+      if (!remoteControl.enabled) {
+        showResult(
+          'Remote control is unavailable in this process. Set "enableRemoteControl": true in ~/.wave/settings.json (or .wave/settings.json in the project), then restart the CLI — a process that is already running keeps the settings it started with.',
+        );
+        return;
+      }
+
+      if (action === "off") {
+        remoteControl.disconnect();
+        showResult(
+          "Remote control is off — this terminal's session is no longer served.",
+        );
+        return;
+      }
+
+      const current = remoteControl.getSnapshot();
+      const serving =
+        current.state === "online" || current.state === "connecting";
+      // A bare `/remote-control` means "start serving" the first time and
+      // "what is it doing?" afterwards, so a second one cannot silently dial
+      // again and cannot hide an address the user still needs.
+      if (action === "status" || (!action && serving)) {
+        showResult(
+          current.pageUrl
+            ? await describeRemotePage(current.pageUrl)
+            : `Remote control status: ${current.state}${
+                current.message ? ` — ${current.message}` : ""
+              }`,
+        );
+        return;
+      }
+
+      remoteControl.connect(parts[1]);
+      const pageUrl = await waitForRemotePageUrl(remoteControl);
+      const after = remoteControl.getSnapshot();
+      if (!pageUrl) {
+        showResult(
+          after.state === "error"
+            ? `Remote control failed: ${after.message ?? "unknown error"}`
+            : "Connected to the relay, but no page address came back yet — run /remote-control status in a moment.",
+        );
+        return;
+      }
+      showResult(await describeRemotePage(pageUrl));
+    },
+    [remoteControl],
+  );
+
   const backgroundCurrentTask = useCallback(() => {
     agentRef.current?.backgroundCurrentTask();
   }, []);
@@ -1462,6 +1692,8 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     hooks,
     permissionMode,
     setPermissionMode,
+    remoteControl,
+    remoteControlCommand,
     planView,
     setPlanView,
     handlePlanCommand,