wave-code 1.3.0 → 1.5.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,
@@ -37,6 +40,8 @@ import {
 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";
@@ -109,6 +114,10 @@ export interface ChatContextType {
   // Workflow runs
   workflowRuns: WorkflowRun[];
   stopWorkflowRun: (runId: string) => void;
+  saveWorkflowScript: (
+    runId: string,
+    options: { name: string; scope: "project" | "user"; overwrite?: boolean },
+  ) => Promise<{ name: string; path: string }>;
   // Tasks
   tasks: Task[];
   getBackgroundTaskOutput: (taskId: string) => {
@@ -132,6 +141,12 @@ 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;
   // /plan overlay state + handler
   planView: PlanViewData | null;
   setPlanView: (view: PlanViewData | null) => void;
@@ -166,7 +181,7 @@ export interface ChatContextType {
   backgroundCurrentTask: () => void;
   // Remount functionality
   remountKey: number;
-  forceRemount: () => void;
+  forceRemount: (options?: { preserveScrollback?: boolean }) => void;
   // Rewind functionality
   handleRewindSelect: (index: number) => Promise<void>;
   getFullMessageThread: () => Promise<{
@@ -349,81 +364,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,
@@ -439,6 +379,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   version,
   model,
   mcpServers,
+  onClearOutput,
 }) => {
   const { restoreSessionId, continueLastSession } = useAppConfig();
   const { stdout } = useStdout();
@@ -454,26 +395,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 +469,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   >();
   const [confirmationQueue, setConfirmationQueue] = useState<
     Array<{
+      requestId: string;
       toolName: string;
       toolInput?: Record<string, unknown>;
       suggestedPrefix?: string;
@@ -551,6 +483,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     }>
   >([]);
   const [currentConfirmation, setCurrentConfirmation] = useState<{
+    requestId: string;
     toolName: string;
     toolInput?: Record<string, unknown>;
     suggestedPrefix?: string;
@@ -563,44 +496,96 @@ 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);
 
-  // Full terminal clear + remount so Ink's append-only <Static> re-renders.
-  // Used on structural actions (/clear, /compact, rewind, ctrl-o) where stale
-  // Static output must not linger on screen.
-  const forceRemount = useCallback(() => {
-    stdout?.write("\u001b[2J\u001b[3J\u001b[0;0H", () => {
-      setRemountKey((prev) => prev + 1);
-    });
-  }, [stdout]);
+  // Remount so Ink's append-only <Static> re-renders from scratch. Used on
+  // structural actions (/clear, session switch, rewind, ctrl-o) where the
+  // already-written Static output no longer matches the message list.
+  //
+  // The re-render duplicates whatever is still on screen, so the default erases
+  // the screen *and* the terminal scrollback. `/clear` passes
+  // `preserveScrollback`: it only wants a fresh conversation, and keeping the
+  // old one scrollable above is the point of the command.
+  const forceRemount = useCallback(
+    (options?: { preserveScrollback?: boolean }) => {
+      const remount = () => setRemountKey((prev) => prev + 1);
+      if (options?.preserveScrollback && onClearOutput) {
+        // ink's own clear erases just the frame it drew, leaving scrollback
+        // intact — and resets the row bookkeeping a hand-written escape
+        // sequence cannot reach.
+        onClearOutput();
+        remount();
+        return;
+      }
+      stdout?.write("\u001b[2J\u001b[3J\u001b[0;0H", remount);
+    },
+    [onClearOutput, stdout],
+  );
 
   // Status metadata state
   const [workingDirectory, setWorkingDirectory] = useState("");
 
   const agentRef = useRef<Agent | null>(null);
 
-  // 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.
+  /**
+   * 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 — used only for structural changes (compact/clear/rewind/
+  // collapse/init). Streaming updates flow through the incremental callbacks in
+  // initializeAgent below.
   const refreshMessages = useCallback(() => {
-    if (!isExpandedRef.current && agentRef.current) {
-      // 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();
+    const agent = agentRef.current;
+    if (!isExpandedRef.current && agent) {
+      // `agent.messages` 是「最近一次压缩 + 其后消息」：CLI 屏幕只渲染最近几十
+      // 条、清屏重放也只放这些条数，压缩前的历史在这里没有任何读者，留着只是把
+      // 图片 base64 挂在堆上（spec ui/message-rendering-system.md「CLI 消息列表
+      // 只加载压缩之后」）。从未压缩过的会话这里就是整条线程。
+      const msgs = agent.messages.map(snapshotMessage);
+      // 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 +599,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 +639,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 +656,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 +682,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 +696,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 +760,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);
@@ -736,6 +774,11 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           setIsCompacting(isCompactingState);
           if (!isCompactingState) {
             setCompactionStream("");
+            // 压缩结束 = 上下文已经折叠成「摘要 + 保留轮次」：列表要跟着收缩，
+            // 否则这一轮之后仍挂着压缩前的全量（自动压缩不走 `/compact` 那条
+            // refresh 路径）。见 spec ui/message-rendering-system.md「CLI 消息
+            // 列表只加载压缩之后」。
+            refreshMessages();
           }
         },
         onCompactionContentUpdate: (content) => {
@@ -769,8 +812,9 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
         onModelChange: (model) => {
           setCurrentModelState(model);
         },
+        // CLI 的选择器只要名字，能力标识是 webview 输入卡片的事。
         onConfiguredModelsChange: (models) => {
-          setConfiguredModels(models);
+          setConfiguredModels(models.map((m) => m.name));
         },
         onLoadingChange: (loading) => {
           setIsLoading(loading);
@@ -828,6 +872,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;
@@ -847,19 +893,22 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
           agent.setWorktreeSession(session);
         }
 
-        // Get initial state — snapshot the SDK messages (never hold live
-        // references; see snapshotMessage). Uses the full display stream so a
-        // restored session shows pre-compaction history too.
+        // Get initial state — all synchronous reads, so a notification arriving
+        // mid-init cannot be overwritten by a stale read. The list is
+        // `agent.messages` (the API context): after compaction that is the
+        // summary plus the rounds the compaction kept, which is exactly what
+        // the CLI shows (spec ui/message-rendering-system.md「CLI 消息列表只加载
+        // 压缩之后」); a never-compacted session is the whole thread.
         setSessionId(agent.sessionId);
-        setMessages(agent.displayMessages.map(snapshotMessage));
-        setIsLoading(agent.isLoading);
+        setMessages(agent.messages.map(snapshotMessage));
         setLatestTotalTokens(extractLatestTotalTokens(agent.messages));
+        setIsLoading(agent.isLoading);
         setIsCommandRunning(agent.isCommandRunning);
         setIsCompacting(agent.isCompacting);
         setPermissionModeState(agent.getPermissionMode());
-        setWorkingDirectory(agent.workingDirectory);
+        setWorkingDirectory(agent.currentWorkdir);
         setCurrentModelState(agent.getModelConfig().model || "");
-        setConfiguredModels(agent.getConfiguredModels());
+        setConfiguredModels(agent.getConfiguredModels().map((m) => m.name));
         setMaxInputTokens(agent.getMaxInputTokens());
 
         // Get initial MCP servers state
@@ -910,8 +959,8 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       originalCwd,
       model,
       initialPermissionMode,
-      updateMessages,
       mcpServers,
+      refreshMessages,
     ],
   );
 
@@ -968,7 +1017,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 +1030,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
         agentRef.current.destroy();
       }
     };
-  }, [updateMessages]);
+  }, []);
 
   // Send message function (including judgment logic)
   const sendMessage = useCallback(
@@ -1044,7 +1092,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   const clearMessages = useCallback(async () => {
     await agentRef.current?.clearMessages();
     refreshMessages();
-    forceRemount();
+    forceRemount({ preserveScrollback: true });
   }, [refreshMessages, forceRemount]);
 
   const compact = useCallback(
@@ -1178,7 +1226,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
       }
 
       setSessionId(agent.sessionId);
-      setWorkingDirectory(agent.workingDirectory);
+      setWorkingDirectory(agent.currentWorkdir);
       setIsLoading(agent.isLoading);
       refreshMessages();
       forceRemount();
@@ -1280,6 +1328,19 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     agentRef.current?.stopWorkflowRun(runId);
   }, []);
 
+  const saveWorkflowScript = useCallback(
+    async (
+      runId: string,
+      options: { name: string; scope: "project" | "user"; overwrite?: boolean },
+    ) => {
+      if (!agentRef.current) {
+        throw new Error("Agent not available");
+      }
+      return agentRef.current.saveWorkflowScript(runId, options);
+    },
+    [],
+  );
+
   const hasSlashCommand = useCallback((commandId: string) => {
     if (!agentRef.current) return false;
     return agentRef.current.hasSlashCommand(commandId);
@@ -1334,6 +1395,97 @@ 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(),
+    // 会话身份取 agent 的会话起点（不随 bash `cd` 漂移），不是上面那个会动的 workdir。
+    sessionCwd: () =>
+      agentRef.current?.sessionWorkdir ?? 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() ?? [],
+    // 手机页取首屏尾段 / 补差都读 agent 手上那份列表（压缩后的上下文），不去
+    // 转录里找压缩前的历史。
+    messagePage: (window) =>
+      Promise.resolve(
+        agentRef.current?.getMessagePage(window) ?? { messages: [] },
+      ),
+    currentThread: () =>
+      Promise.resolve([...(agentRef.current?.messages ?? [])]),
+    threadSummary: () =>
+      agentRef.current?.getThreadSummary() ?? { messageCount: 0 },
+  });
+
+  // `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;
+
   const backgroundCurrentTask = useCallback(() => {
     agentRef.current?.backgroundCurrentTask();
   }, []);
@@ -1378,7 +1530,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     if (!agentRef.current) {
       return [];
     }
-    return agentRef.current.getConfiguredModels();
+    return agentRef.current.getConfiguredModels().map((m) => m.name);
   }, []);
 
   const setModel = useCallback((model: string) => {
@@ -1452,6 +1604,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     backgroundTasks,
     workflowRuns,
     stopWorkflowRun,
+    saveWorkflowScript,
     tasks,
     getBackgroundTaskOutput,
     stopBackgroundTask,
@@ -1462,6 +1615,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     hooks,
     permissionMode,
     setPermissionMode,
+    remoteControl,
     planView,
     setPlanView,
     handlePlanCommand,