wave-code 1.3.0 → 1.4.0

package/src/stdio/agentBridge.ts

@@ -58,28 +58,54 @@ import {
   type SubagentConfiguration,
   type SkillMetadata,
   type PluginReloadResult,
+  type RemoteControlSnapshot,
+  normalizeEntrypoint,
 } from "wave-agent-sdk";
 import {
+  type ClientNotificationMethod,
   type JsonRpcError,
+  type RequestMethod,
+  type ServerNotificationMethod,
   INVALID_PARAMS as PROTOCOL_INVALID_PARAMS,
   INTERNAL_ERROR as PROTOCOL_INTERNAL_ERROR,
   METHOD_NOT_FOUND as PROTOCOL_METHOD_NOT_FOUND,
 } from "./protocol.js";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  realpathSync,
+} from "node:fs";
 import { mkdir, open, readFile, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import {
   createWorktree,
+  deriveWorktreeInfo,
   getWorktreeChanges,
   removeWorktree,
 } from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
+import {
+  InvalidMessageWindowError,
+  sliceMessageWindow,
+  type MessageWindowResult,
+} from "../remote/messageWindow.js";
+import {
+  percentOf,
+  remoteWire,
+  toBackgroundTaskSummaries,
+} from "../remote/remoteNotifications.js";
 import { isUserCheckpointMessage } from "../utils/rewindCheckpoints.js";
+import { getWorkspaceDiff } from "../utils/workspaceDiff.js";
+import { installGitCredentialHelper } from "../utils/gitCredentialHelper.js";
+import type { RemoteControlController } from "../remote/remoteControlService.js";
 
 export type NotificationEmitter = (
-  method: string,
+  method: ServerNotificationMethod,
   params: unknown,
   sessionId?: string,
 ) => void;
@@ -91,6 +117,17 @@ export interface AgentBridgeOptions {
    * down its socket and exits. stdio mode leaves it unset, so `shutdown` is
    * "Method not found" there. */
   onShutdownRequest?: () => void;
+  /** Daemon transport only. Remote control is a daemon-level concern (it owns
+   * an outbound socket and a relay session); the bridge owns nothing here and
+   * only routes the three `remoteControl*` RPCs to it, exactly as it routes
+   * `shutdown` to `onShutdownRequest`. Unset ⇒ those RPCs report that remote
+   * control is not enabled, which is the state on every stdio-mode process.
+   *
+   * Resolved on demand rather than passed as an object: the controller needs
+   * this bridge to route the phone's requests back in, so the two are built in
+   * a circle. Reading it when an RPC arrives — long after both exist — keeps
+   * that circle from having to be broken with a placeholder. */
+  remoteControl?: () => RemoteControlController | undefined;
 }
 
 interface InitializeParams {
@@ -110,6 +147,13 @@ interface InitializeParams {
   mcpServers?: Record<string, McpServerConfig>;
   worktreeName?: string;
   isNewWorktree?: boolean;
+  /**
+   * Which host the session belongs to → the `app.entrypoint` attribute. A raw
+   * string: it arrives over the wire, from hosts this process does not compile
+   * against (the JetBrains plugin builds its own frames). Narrowed to the known
+   * table below before it reaches the SDK.
+   */
+  entrypoint?: string;
 }
 
 // 会话级覆盖项：用户偏好（语言 / 上下文长度 / 自动记忆开关与频率）不在此层——
@@ -189,14 +233,26 @@ export class AgentBridge {
     }
   >();
   private permissionCounter = 0;
+  /**
+   * In-flight completion calls, keyed by envelope sessionId. Completion answers
+   * a keystroke pause, so a newer request makes the previous one worthless —
+   * superseding it here is what keeps "one in-flight request per editor" true
+   * even when the host cannot cancel (spec
+   * docs/specs/ui/code-completion.md: 同一时刻只允许一个补全请求在途).
+   */
+  private inFlightCompletions = new Map<string, AbortController>();
   private emit: NotificationEmitter;
   private onShutdownRequest: (() => void) | undefined;
+  private remoteControl:
+    | (() => RemoteControlController | undefined)
+    | undefined;
   private pluginCore: PluginCore | undefined;
   private pluginCoreWorkdir: string | undefined;
 
   constructor(options: AgentBridgeOptions) {
     this.emit = options.emit;
     this.onShutdownRequest = options.onShutdownRequest;
+    this.remoteControl = options.remoteControl;
     // Mirror the user-level settings env WAVE_SERVER_URL into process.env
     // before any agent initializes. getAuthStatus (webviewReady →
     // pushInitialState) can run before the first agent, and AuthService falls
@@ -211,7 +267,7 @@ export class AgentBridge {
   // ── Public API ────────────────────────────────────────────────
 
   async handleRequest(
-    method: string,
+    method: RequestMethod,
     params: unknown,
     sessionId?: string,
   ): Promise<unknown> {
@@ -221,7 +277,9 @@ export class AgentBridge {
       case "initialize":
         return this.initialize(p as unknown as InitializeParams);
       case "destroy":
-        return this.destroy(sessionId);
+        return this.destroy(sessionId, {
+          removeWorktree: p.removeWorktree === true,
+        });
       case "restoreSession":
         return this.restoreSession(p.sessionId as string, sessionId);
       case "listSessions":
@@ -311,10 +369,21 @@ export class AgentBridge {
       case "deleteQueuedMessageById":
         return this.deleteQueuedMessageById(p.id as string, sessionId);
       case "getMessages":
-        return this.getMessages(sessionId);
+        return this.getMessages(sessionId, {
+          before: p.before as string | undefined,
+          since: p.since as string | undefined,
+          limit: p.limit as number | undefined,
+        });
       case "getFullMessageThread":
         return this.getFullMessageThread(sessionId);
 
+      // ── Remote control (daemon-level) ──
+      // The daemon owns the outbound relay socket; the bridge only routes.
+      case "remoteControlStatus":
+      case "remoteControlConnect":
+      case "remoteControlDisconnect":
+        return this.remoteControlRequest(method, p);
+
       // ── Permissions ──
       case "setPermissionMode":
         return this.setPermissionMode(p.mode as PermissionMode, sessionId);
@@ -390,6 +459,8 @@ export class AgentBridge {
         return this.login(p.serverUrl as string | undefined);
       case "logout":
         return this.logout();
+      case "installGitCredentialHelper":
+        return installGitCredentialHelper();
 
       // ── Memory files (settings UI — user-level ~/.wave/AGENTS.md and
       //    project-level <workdir>/AGENTS.md) ──
@@ -527,7 +598,9 @@ export class AgentBridge {
       case "stopWorkflowRun":
         return this.stopWorkflowRun(p.runId as string, sessionId);
 
-      // ── Git / worktree (global — no session required) ──
+      // ── Filesystem / Git / worktree (global — no session required) ──
+      case "listDirectories":
+        return this.listDirectories(p.dir as string | undefined);
       case "listGitBranches":
         return this.listGitBranches(p.workdir as string | undefined);
       case "createWorktree":
@@ -542,6 +615,8 @@ export class AgentBridge {
         return this.getWorktreeChanges(
           p as unknown as { path?: string; baseBranch?: string },
         );
+      case "getSessionWorktreeChanges":
+        return this.getSessionWorktreeChanges(sessionId);
       case "removeWorktree":
         return this.removeWorktreeSession(
           p as unknown as {
@@ -551,16 +626,42 @@ export class AgentBridge {
             hookBased?: boolean;
           },
         );
+      case "getWorkspaceDiff":
+        return this.getWorkspaceDiff(
+          p.workdir as string | undefined,
+          p.commit as string | undefined,
+          p.scope as string | undefined,
+        );
+      case "getCompletion":
+        return this.getCompletion(
+          p as unknown as {
+            prefix?: string;
+            suffix?: string;
+            language?: string;
+            filePath?: string;
+          },
+          sessionId,
+        );
 
-      default:
+      default: {
+        // Type-level exhaustiveness, both directions: a union member without a
+        // `case` lands here as a non-`never` and fails to compile, and a `case`
+        // naming something outside the union fails to compile at the `case`
+        // itself. Runtime behaviour is unchanged — `method` can still be an
+        // arbitrary string once the transport boundary cast it.
+        const _exhaustive: never = method;
+        // Kept referenced so the witness isn't an unused-variable lint error;
+        // it is never read at runtime.
+        void _exhaustive;
         throw new RpcError(
           PROTOCOL_METHOD_NOT_FOUND,
           `Method not found: ${method}`,
         );
+      }
     }
   }
 
-  handleNotification(method: string, params: unknown): void {
+  handleNotification(method: ClientNotificationMethod, params: unknown): void {
     if (method === "permissionResponse") {
       const p = params as {
         requestId: string;
@@ -601,6 +702,16 @@ export class AgentBridge {
     const ctx: SessionContext = {};
     const callbacks = this.createCallbacks(ctx);
 
+    const entrypoint = normalizeEntrypoint(params.entrypoint);
+    if (params.entrypoint !== undefined && entrypoint === undefined) {
+      // A host that ships a value this version does not know (an older client,
+      // a hand-written frame) is treated as if it had declared nothing: an
+      // unrecognised value must not mint a series of its own.
+      logger?.warn(
+        `Unknown entrypoint: ${String(params.entrypoint)}, ignoring`,
+      );
+    }
+
     const options: AgentOptions = {
       callbacks,
       logger,
@@ -619,6 +730,7 @@ export class AgentBridge {
       mcpServers: params.mcpServers,
       worktreeName: params.worktreeName,
       isNewWorktree: params.isNewWorktree,
+      entrypoint,
       canUseTool: (context: ToolPermissionContext) =>
         this.canUseTool(context, ctx),
     };
@@ -660,7 +772,42 @@ export class AgentBridge {
     };
   }
 
-  private async destroy(sessionId?: string): Promise<null> {
+  /**
+   * Destroy one hosted session (idempotent: an unknown id is a no-op).
+   *
+   * `params.removeWorktree` (optional, default false) additionally removes the
+   * git worktree the session was **created** in — the intent the remote page
+   * sends when the user confirms 「删除会话与工作树」. Two rules make it safe to
+   * offer over the remote channel, where the caller must never be able to name a
+   * path:
+   *
+   * 1. The worktree is resolved here, from `entry.createdWorkdir` — the same
+   *    anchor `wave daemon destroy --remove-worktree` resolves from (and for the
+   *    same reason: an in-session `cd` must not move the target). Nothing in the
+   *    request is trusted as a path, which is why the raw `removeWorktree`
+   *    method stays off the remote whitelist.
+   * 2. It runs **after** `agent.destroy()` resolves. The agent's cwd is the
+   *    worktree path and destroy flushes the session file (resolving that path
+   *    via realpath); deleting the directory first makes the save fail ENOENT
+   *    and drops the trailing messages — the desktop host carries the identical
+   *    ordering note in `handleDeleteSession`.
+   *
+   * "Cannot resolve a worktree" is never a reason to fail the delete: the
+   * session is still destroyed and the reply says `worktreeRemoved: false`. That
+   * covers a plain (non-worktree) session, a worktree that is already gone, and
+   * a removal that threw — the caller only ever needs to know whether the
+   * directory is gone.
+   *
+   * The return shape grew from `null` to `{worktreeRemoved}`; callers that pass
+   * no params (the CLI's own `wave daemon destroy`) read nothing and are
+   * unaffected. The CLI's `--remove-worktree` keeps its own client-side path
+   * (getSessionInfo + removeWorktree + destroy) — deliberately unchanged.
+   */
+  private async destroy(
+    sessionId?: string,
+    params?: { removeWorktree?: boolean },
+  ): Promise<{ worktreeRemoved: boolean }> {
+    let createdWorkdir: string | undefined;
     if (sessionId) {
       const entry = this.sessions.get(sessionId);
       if (entry) {
@@ -687,10 +834,71 @@ export class AgentBridge {
         // half-destroyed agent listed (destroyAll() below clears the map first
         // for the same reason).
         this.sessions.delete(sessionId);
+        createdWorkdir = entry.createdWorkdir;
         await entry.agent.destroy();
       }
     }
-    return null;
+
+    let worktreeRemoved = false;
+    if (params?.removeWorktree === true && createdWorkdir) {
+      worktreeRemoved = await this.removeSessionWorktree(createdWorkdir);
+    }
+    return { worktreeRemoved };
+  }
+
+  /**
+   * Remove the linked worktree a session was created in. Returns whether the
+   * directory is actually gone (not whether we asked): `removeWorktree` is
+   * best-effort and leaves the directory behind when git and the fs fallback
+   * both fail, and for a hook-based worktree with no WorktreeRemove hook it
+   * deliberately leaves it in place. Never throws — the caller has already
+   * deleted the session.
+   */
+  private async removeSessionWorktree(sessionDir: string): Promise<boolean> {
+    const worktree = deriveWorktreeInfo(sessionDir);
+    if (!worktree) return false;
+    try {
+      await removeWorktree({
+        name: "",
+        path: worktree.path,
+        branch: worktree.branch,
+        repoRoot: worktree.repoRoot,
+        hasUncommittedChanges: false,
+        hasNewCommits: false,
+        isNew: false,
+        hookBased: worktree.hookBased,
+      });
+    } catch (e) {
+      logger.warn(
+        `removeSessionWorktree: failed to remove ${worktree.path}: ${(e as Error).message}`,
+      );
+      return false;
+    }
+    return !existsSync(worktree.path);
+  }
+
+  /**
+   * What deleting a session's worktree would throw away (uncommitted files and
+   * commits not on the base branch) — the counts the delete confirmation names
+   * on the remote page.
+   *
+   * Session-scoped on purpose: the path comes from the session's own
+   * `createdWorkdir`, never from the caller. The remote channel carries this
+   * instead of the path-taking `getWorktreeChanges`, for the same reason it
+   * carries `destroy {removeWorktree}` instead of `removeWorktree` — a phone may
+   * only name a session it was given, not an arbitrary directory on the machine.
+   *
+   * `null` means "could not inspect" (not a worktree, already deleted, git
+   * failed), which the page renders as the generic warning rather than as
+   * "clean".
+   */
+  private async getSessionWorktreeChanges(
+    sessionId?: string,
+  ): Promise<{ files: number; commits: number } | null> {
+    const entry = this.requireSessionForRead(sessionId);
+    const worktree = deriveWorktreeInfo(entry.createdWorkdir);
+    if (!worktree) return null;
+    return getWorktreeChanges(worktree.path);
   }
 
   /**
@@ -713,13 +921,23 @@ export class AgentBridge {
   ): Promise<null> {
     const entry = this.requireSessionForRead(sessionId);
     // Re-attach to a live session: the SDK restore would no-op (target is
-    // already current). Emit the current messages so the freshly attached
-    // client — whose router registered only after initialize returned and so
-    // missed any earlier notifications — gets a snapshot without replay.
+    // already current). Re-send the state the freshly attached client missed —
+    // its router registered only after initialize returned.
+    //
+    // `messagesChange` carries **no payload here, only the fact that the list
+    // changed**. Nobody ever read a full snapshot from it: the remote relay
+    // needs the emission to produce the phone's signal and then the phone pulls
+    // `getMessages({ since })` itself, while every IDE host ignores the method
+    // and calls `getMessages` after restore. So building one — a multi-MB list
+    // on a long session, serialized on a hot re-attach path — was pure cost, and
+    // this is why the bridge sends the signal shape instead.
+    //
+    // This is also the ONLY place the bridge emits `messagesChange`, and only on
+    // this re-attach branch — never as the message stream progresses.
     if (entry.agent.sessionId === restoreId) {
       this.emit(
         "messagesChange",
-        { messages: entry.agent.displayMessages },
+        remoteWire.messagesChangeSignal(),
         entry.agent.sessionId,
       );
       // The re-attached client also missed the loading state that settled
@@ -775,9 +993,14 @@ export class AgentBridge {
    * usage to report; the host keeps the empty ring until the first push.
    */
   private emitContextUsage(agent: Agent): void {
-    const percent = this.contextUsagePercentOf(agent);
-    if (percent !== undefined) {
-      this.emit("contextUsage", { percent }, agent.sessionId);
+    const tokens = agent.latestTotalTokens;
+    const max = agent.getMaxInputTokens();
+    if (tokens > 0 && max > 0) {
+      this.emit(
+        "contextUsage",
+        remoteWire.contextUsage(tokens, max),
+        agent.sessionId,
+      );
     }
   }
 
@@ -792,7 +1015,7 @@ export class AgentBridge {
     const tokens = agent.latestTotalTokens;
     const max = agent.getMaxInputTokens();
     if (tokens > 0 && max > 0) {
-      return Math.min(100, Math.round((tokens / max) * 100));
+      return percentOf(tokens, max);
     }
     return undefined;
   }
@@ -841,6 +1064,50 @@ export class AgentBridge {
 
   // ── Git / worktree ────────────────────────────────────────────
 
+  /**
+   * List the subdirectories of a directory on the machine this CLI runs on —
+   * host-agnostic like `listGitBranches`: whichever wave process receives the
+   * request lists its own filesystem. Serves the new-session directory pickers
+   * (the desktop's remote host browser and the Web page now share this one
+   * implementation; the desktop's ssh shell one-liner retires into it).
+   *
+   * `~` / `~/…` expand against the service process user's home. `resolvedPath`
+   * is the realpath so the picker shows where the user actually is (symlinked
+   * parents normalized). Symlinked subdirectories are NOT listed — the shell
+   * `find -type d` this replaces didn't list them either, and the two paths
+   * must stay interchangeable. A missing or unreadable directory is an explicit
+   * error, never an empty list (an empty list would read as "no subdirs" and
+   * strand the user on a path they can't leave).
+   */
+  private listDirectories(dir?: string): {
+    resolvedPath: string;
+    dirs: string[];
+  } {
+    if (!dir) {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, "dir is required");
+    }
+    const expanded =
+      dir === "~" || dir.startsWith("~/") ? join(homedir(), dir.slice(1)) : dir;
+    let resolvedPath: string;
+    try {
+      resolvedPath = realpathSync(expanded);
+    } catch {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, `目录不存在或不可读：${dir}`);
+    }
+    let dirs: string[];
+    try {
+      dirs = readdirSync(resolvedPath, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort((a, b) => a.localeCompare(b));
+    } catch {
+      // realpath succeeded (the path exists) but reading it didn't — same
+      // verdict as missing: the picker cannot descend into either.
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, `目录不存在或不可读：${dir}`);
+    }
+    return { resolvedPath, dirs };
+  }
+
   private listGitBranches(workdir?: string): {
     branches: string[];
     current: string | null;
@@ -887,6 +1154,66 @@ export class AgentBridge {
     return { branches, current };
   }
 
+  /**
+   * Read-only workspace diff for the desktop diff panel. Runs wherever this
+   * CLI runs, so a remote session answers it inside the remote daemon instead
+   * of the desktop shelling out over ssh per git command.
+   *
+   * `scope` selects the viewing range: omitted / "all" = the fork-point base,
+   * "uncommitted" = `HEAD` (the panel's "未提交改动"). A `commit` outranks it.
+   */
+  private getWorkspaceDiff(workdir?: string, commit?: string, scope?: string) {
+    if (!workdir) {
+      throw new RpcError(PROTOCOL_INTERNAL_ERROR, "workdir is required");
+    }
+    return getWorkspaceDiff(workdir, {
+      ...(commit ? { commit } : {}),
+      ...(scope === "uncommitted" ? { uncommitted: true } : {}),
+    });
+  }
+
+  /**
+   * One inline (ghost-text) completion for the editor plugins.
+   *
+   * Session-scoped on purpose: the completion model and the gateway credentials
+   * are resolved inside that session (the CLI owns the model configuration —
+   * the plugin never holds a second source of truth). Read-only, so it keeps
+   * working while `updateConfig` is rebuilding the session.
+   */
+  private async getCompletion(
+    params: {
+      prefix?: string;
+      suffix?: string;
+      language?: string;
+      filePath?: string;
+    },
+    sessionId?: string,
+  ): Promise<{ text: string; model: string }> {
+    const entry = this.requireSessionForRead(sessionId);
+    const key = sessionId as string;
+
+    // Supersede the session's previous request: its answer would land at a
+    // cursor position that no longer exists.
+    this.inFlightCompletions.get(key)?.abort();
+    const controller = new AbortController();
+    this.inFlightCompletions.set(key, controller);
+
+    try {
+      return await entry.agent.getCompletion({
+        prefix: params.prefix ?? "",
+        suffix: params.suffix ?? "",
+        ...(params.language ? { language: params.language } : {}),
+        ...(params.filePath ? { filePath: params.filePath } : {}),
+        abortSignal: controller.signal,
+      });
+    } finally {
+      // Only clear our own slot — a newer request may already own it.
+      if (this.inFlightCompletions.get(key) === controller) {
+        this.inFlightCompletions.delete(key);
+      }
+    }
+  }
+
   private async createWorktreeSession(params: {
     workdir: string;
     baseBranch?: string;
@@ -972,13 +1299,18 @@ export class AgentBridge {
     return { ok: true };
   }
 
-  private getSessionInfo(sessionId?: string): {
+  private async getSessionInfo(sessionId?: string): Promise<{
     sessionId: string;
     workingDirectory: string;
     latestTotalTokens: number;
     permissionMode: PermissionMode;
     availableTools: string[];
-  } {
+    tasks: Task[];
+    isCompacting: boolean;
+    isCommandRunning: boolean;
+    queuedMessages: QueuedMessage[];
+    backgroundTasks: BackgroundTaskSummary[];
+  }> {
     const entry = this.requireSessionForRead(sessionId);
     return {
       sessionId: entry.agent.sessionId,
@@ -989,6 +1321,23 @@ export class AgentBridge {
       latestTotalTokens: entry.agent.latestTotalTokens,
       permissionMode: entry.agent.getPermissionMode(),
       availableTools: entry.agent.getAvailableToolNames(),
+      // The session-state family the remote page re-reads (spec
+      // remote-control「Web 页作为第五种宿主」场景 26): the todo list —
+      // file-backed in the SDK, hence the await — plus compaction, command
+      // running and the outbound queue, all read off the agent itself so the
+      // reply is the current value, never a transition the page may have
+      // missed.
+      tasks: await entry.agent.getTasks(),
+      isCompacting: entry.agent.isCompacting,
+      isCommandRunning: entry.agent.isCommandRunning,
+      queuedMessages: entry.agent.queuedMessages,
+      // Background tasks join the family for the same reason the todo list is
+      // here: the phone's `/tasks` dialog opens on whatever the machine holds, and
+      // `backgroundTasksChange` only reports *changes* — a task that started
+      // before the page attached would otherwise be invisible until it finished.
+      backgroundTasks: toBackgroundTaskSummaries(
+        entry.agent.getBackgroundTasks(),
+      ),
     };
   }
 
@@ -1039,6 +1388,9 @@ export class AgentBridge {
         // Keep worktree context (permission safety) across recreation, but never
         // re-fire WorktreeCreate — the hook ran at initial creation.
         worktreeName: entry.storedConfig.worktreeName,
+        // The declaration outlives the rebuild: an `updateConfig` replaces the
+        // agent, not the host that asked for the session.
+        entrypoint: normalizeEntrypoint(entry.storedConfig.entrypoint),
         canUseTool: (context: ToolPermissionContext) =>
           this.canUseTool(context, ctx),
       };
@@ -1339,15 +1691,64 @@ export class AgentBridge {
     return null;
   }
 
-  private getMessages(sessionId?: string): {
+  /**
+   * Read a session's display messages.
+   *
+   * With no window this returns the whole list — that is the contract every
+   * existing host relies on (VS Code / JetBrains / desktop call `getMessages`
+   * with no parameters and must keep seeing the full thread, byte for byte).
+   * The window exists for remote clients on a phone, which only ever want the
+   * tail of a long conversation and must not be handed 13 MB on every cold
+   * start:
+   *
+   * - `limit`  — page size.
+   * - `before` — the page that ends immediately before the given message id
+   *              (paging *backwards* into history).
+   * - `since`  — everything appended after the given message id (catching up
+   *              after a reconnect).
+   *
+   * `since` is a position, not a version number: message ids are stable, so a
+   * caller can name its last known message without the list carrying a
+   * sequence number. The one failure that matters is the anchor having been
+   * truncated away (rewind / clear) — there is no seq/version in the store that
+   * could detect it otherwise — and that comes back as `reset: true` so the
+   * caller re-pulls the tail instead of guessing.
+   *
+   * Ids can repeat in the display list (a compacted message is re-added), so
+   * anchors are resolved to their **last** occurrence: "after `since`" means
+   * after the newest copy the caller could have seen.
+   */
+  private getMessages(
+    sessionId?: string,
+    window?: { before?: string; since?: string; limit?: number },
+  ): {
     messages: Message[];
     contextUsagePercent?: number;
+    /** Older messages exist before the returned page. */
+    hasMore?: boolean;
+    /** The `since` anchor is gone — rebuild from the tail. */
+    reset?: boolean;
+    /** Total display messages held for the session. */
+    total?: number;
   } {
     const entry = this.requireSessionForRead(sessionId);
-    return {
-      messages: entry.agent.displayMessages,
-      contextUsagePercent: this.contextUsagePercentOf(entry.agent),
-    };
+    const all = entry.agent.displayMessages;
+    const contextUsagePercent = this.contextUsagePercentOf(entry.agent);
+
+    // The slicing is shared with the CLI front end (`RemoteControlCliHost`): the
+    // phone's reconciliation rules belong to the wire contract, not to this
+    // registry, and the two hosts must answer identically.
+    let sliced: MessageWindowResult | undefined;
+    try {
+      sliced = sliceMessageWindow(all, window);
+    } catch (err) {
+      if (err instanceof InvalidMessageWindowError) {
+        throw new RpcError(PROTOCOL_INVALID_PARAMS, err.message);
+      }
+      throw err;
+    }
+    if (!sliced) return { messages: all, contextUsagePercent };
+    return { ...sliced, contextUsagePercent };
   }
 
   private async getFullMessageThread(sessionId?: string): Promise<{
@@ -1654,7 +2055,7 @@ export class AgentBridge {
       });
       this.emit(
         "permissionRequest",
-        { requestId, context },
+        remoteWire.permissionRequest(requestId, context),
         ctx.registeredSessionId,
       );
     });
@@ -1701,7 +2102,15 @@ export class AgentBridge {
    * reading only `isLoading` reports "done" in both cases. They are read from the
    * live agent here rather than tracked separately, and mirror it as-is: the
    * rebuild window above is already covered by `isLoading`, so there is no need
-   * to also claim a `transitioning` session owns background work it doesn't. */
+   * to also claim a `transitioning` session owns background work it doesn't.
+   *
+   * The three label fields are additive (an older CLI simply ignores them) and
+   * exist for the remote-control page: it lists **this process's** sessions —
+   * the only ones it can actually open — and cannot read the machine's disk, so
+   * the title material and the ordering key have to come off the live agent
+   * rather than from `listSessions`, which reads jsonl and would offer it
+   * sessions that are not loaded here (spec remote-control「Web 页作为第五种宿主」
+   * 场景 2）。 */
   private listDaemonSessions(): {
     sessions: Array<{
       sessionId: string;
@@ -1710,22 +2119,122 @@ export class AgentBridge {
       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;
+      /**
+       * The linked git worktree this session was created in, when it was.
+       * Present only for worktree sessions — absent means "not a worktree, or
+       * cannot tell", and the remote page reads it as "deleting this session
+       * will not touch a worktree". Change counts are deliberately NOT here:
+       * they cost git calls per row, and the list is rebuilt on every reconnect
+       * / snapshot / page open. The page asks for them on demand instead, via
+       * `getSessionWorktreeChanges`.
+       */
+      worktree?: {
+        path: string;
+        branch: string;
+        repoRoot: string;
+        hookBased: boolean;
+      };
     }>;
   } {
     return {
-      sessions: [...this.sessions.entries()].map(([sessionId, entry]) => ({
-        sessionId,
-        workingDirectory: entry.createdWorkdir,
-        isLoading: entry.transitioning === true || entry.agent.isLoading,
-        hasRunningBackgroundWork: entry.agent.hasRunningBackgroundWork,
-        hasPendingMessages: entry.agent.hasPendingMessages,
-        messageCount: entry.agent.displayMessages.length,
-      })),
+      sessions: [...this.sessions.entries()].map(([sessionId, entry]) => {
+        const messages = entry.agent.displayMessages;
+        const customTitle = entry.agent.customTitle;
+        const firstMessage = firstUserText(messages);
+        const lastActiveAt = messages[messages.length - 1]?.timestamp;
+        // Derived from the creation workdir (not the live one) and fs-only —
+        // see `deriveWorktreeInfo` for why this must not shell out to git.
+        const worktree = deriveWorktreeInfo(entry.createdWorkdir);
+        return {
+          sessionId,
+          workingDirectory: entry.createdWorkdir,
+          isLoading: entry.transitioning === true || entry.agent.isLoading,
+          hasRunningBackgroundWork: entry.agent.hasRunningBackgroundWork,
+          hasPendingMessages: entry.agent.hasPendingMessages,
+          messageCount: messages.length,
+          ...(customTitle ? { customTitle } : {}),
+          ...(firstMessage ? { firstMessage } : {}),
+          ...(lastActiveAt ? { lastActiveAt } : {}),
+          ...(worktree ? { worktree } : {}),
+        };
+      }),
     };
   }
 
-  // ── Auth (global) ────────────────────────────────────────────
+  /**
+   * Route the `remoteControl*` RPCs to the daemon's controller.
+   *
+   * `connect` / `disconnect` change the relay session; all three return the
+   * same snapshot so a caller can render the result without a second round
+   * trip (and a caller that only wanted to read gets `remoteControlStatus`).
+   *
+   * `connect` carries the optional label the user gave this machine
+   * (`wave remote-control on <name>`), which the relay hands to the phone so
+   * its computer list can tell two of the user's computers apart.
+   */
+  private remoteControlRequest(
+    method: string,
+    params: Record<string, unknown>,
+  ): RemoteControlSnapshot {
+    const controller = this.remoteControl?.();
+    if (!controller) {
+      throw new RpcError(
+        PROTOCOL_INVALID_PARAMS,
+        "Remote control is not enabled on this process (set enableRemoteControl: true).",
+      );
+    }
+    if (method === "remoteControlConnect") {
+      const name = typeof params.name === "string" ? params.name : undefined;
+      controller.connect(name);
+    } else if (method === "remoteControlDisconnect") {
+      controller.disconnect();
+    }
+    return controller.getSnapshot();
+  }
 
+  /**
+   * Per-session status for the remote-control signal.
+   *
+   * The relay forwards bytes without looking inside them, so it can never
+   * discover that somebody is waiting on an approval — and "push to the phone
+   * when a session is stuck on the user" is the whole point of the feature.
+   * The machine therefore reports one word per session, carrying no content:
+   * ids and a status, nothing else.
+   *
+   * `running` includes background work: read from a phone there is no terminal
+   * to glance at, so "something is still in flight" is the useful meaning of
+   * busy rather than the narrower "a model turn is streaming".
+   */
+  listSessionStatuses(): Array<{
+    sessionId: string;
+    status: "running" | "idle" | "requires_action";
+  }> {
+    const awaiting = new Set<string>();
+    for (const entry of this.pendingPermissions.values()) {
+      if (entry.sessionId) awaiting.add(entry.sessionId);
+    }
+    return [...this.sessions.entries()].map(([sessionId, entry]) => {
+      let status: "running" | "idle" | "requires_action" = "idle";
+      if (awaiting.has(sessionId)) {
+        status = "requires_action";
+      } else if (
+        entry.transitioning === true ||
+        entry.agent.isLoading ||
+        entry.agent.hasRunningBackgroundWork
+      ) {
+        status = "running";
+      }
+      return { sessionId, status };
+    });
+  }
+
+  // ── Auth (global) ────────────────────────────────────────────
   private async getAuthStatus(): Promise<{
     isAuthenticated: boolean;
     user: { id: string; email?: string } | undefined;
@@ -2165,26 +2674,29 @@ export class AgentBridge {
             ctx.registeredSessionId,
           );
       },
+      onAssistantMessageDiscarded: (messageId: string) => {
+        // A streamed attempt died mid-body and was re-issued without streaming,
+        // so its half message is void: tell the host to drop it instead of
+        // leaving a partial answer above the real one (spec: 流式响应正文中途
+        // 断连时降级为非流式重发).
+        this.emit(
+          "assistantMessageDiscarded",
+          { messageId },
+          ctx.registeredSessionId,
+        );
+      },
       onAssistantContentUpdated: (params) => {
         // Wire carries only the delta; consumers accumulate (spec: 流式通知纯增量负载).
         this.emit(
           "assistantContentUpdated",
-          {
-            messageId: params.messageId,
-            chunk: params.chunk,
-            stage: params.stage,
-          },
+          remoteWire.assistantContentUpdated(params),
           ctx.registeredSessionId,
         );
       },
       onAssistantReasoningUpdated: (params) => {
         this.emit(
           "assistantReasoningUpdated",
-          {
-            messageId: params.messageId,
-            chunk: params.chunk,
-            stage: params.stage,
-          },
+          remoteWire.assistantReasoningUpdated(params),
           ctx.registeredSessionId,
         );
       },
@@ -2192,21 +2704,23 @@ export class AgentBridge {
         // Streaming stages carry only the parametersChunk delta; start/running
         // (one-time snapshots) and end (authoritative full value) keep
         // `parameters` (spec: 流式通知纯增量负载).
-        const { parameters, ...rest } = params;
-        void parameters;
-        const wireParams = params.stage === "streaming" ? rest : params;
-        this.emit("toolBlockUpdated", wireParams, ctx.registeredSessionId);
+        this.emit(
+          "toolBlockUpdated",
+          remoteWire.toolBlockUpdated(params),
+          ctx.registeredSessionId,
+        );
       },
       onErrorBlockAdded: (error: string) => {
-        this.emit("errorBlockAdded", { error }, ctx.registeredSessionId);
+        this.emit(
+          "errorBlockAdded",
+          remoteWire.errorBlockAdded(error),
+          ctx.registeredSessionId,
+        );
       },
       onLoadingChange: (loading: boolean) => {
         this.emit(
           "loadingChange",
-          {
-            loading,
-            latestTotalTokens: ctx.agent?.latestTotalTokens,
-          },
+          remoteWire.loadingChange(loading, ctx.agent?.latestTotalTokens),
           ctx.registeredSessionId,
         );
       },
@@ -2218,8 +2732,11 @@ export class AgentBridge {
         // aligned with the CLI, which reads the same callback (spec 场景 5/6).
         const max = ctx.agent?.getMaxInputTokens() ?? 0;
         if (max > 0) {
-          const percent = Math.min(100, Math.round((tokens / max) * 100));
-          this.emit("contextUsage", { percent }, ctx.registeredSessionId);
+          this.emit(
+            "contextUsage",
+            remoteWire.contextUsage(tokens, max),
+            ctx.registeredSessionId,
+          );
         }
       },
       onCommandRunningChange: (running: boolean) => {
@@ -2236,21 +2753,9 @@ export class AgentBridge {
         this.emit("tasksChange", { tasks }, ctx.registeredSessionId);
       },
       onBackgroundTasksChange: (tasks: BackgroundTask[]) => {
-        const summaries: BackgroundTaskSummary[] = tasks.map((t) => ({
-          id: t.id,
-          type: t.type,
-          status: t.status,
-          startTime: t.startTime,
-          endTime: t.endTime,
-          command: t.command,
-          description: t.description,
-          exitCode: t.exitCode,
-          runtime: t.runtime,
-          outputPath: t.outputPath,
-        }));
         this.emit(
           "backgroundTasksChange",
-          { tasks: summaries },
+          { tasks: toBackgroundTaskSummaries(tasks) },
           ctx.registeredSessionId,
         );
       },
@@ -2269,7 +2774,11 @@ export class AgentBridge {
         ctx.registeredSessionId = newSessionId;
       },
       onPermissionModeChange: (mode: PermissionMode) => {
-        this.emit("permissionModeChange", { mode }, ctx.registeredSessionId);
+        this.emit(
+          "permissionModeChange",
+          remoteWire.permissionModeChange(mode),
+          ctx.registeredSessionId,
+        );
       },
       onWorkdirChange: (newCwd: string) => {
         this.emit(
@@ -2282,7 +2791,11 @@ export class AgentBridge {
         this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
       },
       onNotificationMessageAdded: (params) => {
-        const msg = ctx.agent?.displayMessages.find(
+        // The LAST matching message, not the first: one task can notify more
+        // than once under the same task id (a workflow warns about its size
+        // mid-run, then notifies again when it finishes), and this callback
+        // fires for the message that was just appended — the newest one.
+        const matches = (ctx.agent?.displayMessages ?? []).filter(
           (m) =>
             m.role === "user" &&
             m.blocks.some(
@@ -2291,14 +2804,19 @@ export class AgentBridge {
                 (b as { taskId: string }).taskId === params.taskId,
             ),
         );
+        const msg = matches[matches.length - 1];
         this.emit(
           "notificationMessageAdded",
           { ...params, message: msg },
           ctx.registeredSessionId,
         );
       },
-      onCompactBlockAdded: (content: string) => {
-        this.emit("compactBlockAdded", { content }, ctx.registeredSessionId);
+      onCompactBlockAdded: (content: string, message?: Message) => {
+        this.emit(
+          "compactBlockAdded",
+          { content, message },
+          ctx.registeredSessionId,
+        );
       },
       onCompactionStateChange: (isCompacting: boolean) => {
         this.emit(
@@ -2405,6 +2923,22 @@ function isSessionRecoveryError(error: unknown): boolean {
   );
 }
 
+/**
+ * The label a session list shows when no custom title is set: the first real
+ * user message. Same rule as the webview's `firstUserMessageText` — meta messages
+ * (task notifications and other injected turns) are skipped, because they are not
+ * what the user typed — so the phone labels a conversation the way the IDE hosts
+ * do.
+ */
+function firstUserText(messages: Message[]): string | undefined {
+  for (const message of messages) {
+    if (message.role !== "user" || message.isMeta) continue;
+    const text = getMessageContent(message).trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
 /** Read a text file, returning "" when it does not exist. */
 async function readTextFileSafe(filePath: string): Promise<string> {
   try {