wave-code 1.3.0 → 1.5.0

package/src/stdio/agentBridge.ts

@@ -37,6 +37,8 @@ import {
   isValidHookEvent,
   listSessions,
   listAllSessions,
+  readRecentWorkdirs,
+  rememberRecentWorkdir,
   setSessionCustomTitle,
   searchFiles,
   generateRandomName,
@@ -46,7 +48,9 @@ import {
   AuthService,
   PluginCore,
   validateWorktreeRemovalPath,
-  type SlashCommand,
+  type HostSurface,
+  type SlashCommandInfo,
+  type ConfiguredModel,
   loadUserConfigEnv,
   loadWaveConfigFromFile,
   getUserConfigPaths,
@@ -58,28 +62,72 @@ import {
   type SubagentConfiguration,
   type SkillMetadata,
   type PluginReloadResult,
+  type RemoteControlSnapshot,
+  type CompletionSnippet,
+  type NextEditExcerpt,
+  type NextEditHistoryEntry,
+  type NextEditRegion,
+  type NextEditSuggestion,
+  normalizeEntrypoint,
+  fetchArtifactGalleryList,
+  fetchArtifactShareView,
+  saveArtifactShare,
+  revokeArtifact,
+  searchArtifactMembers,
+  type ArtifactShareMode,
 } 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,
+  normalizeMessageWindow,
+  type MessageWindow,
+  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";
+import {
+  hostSlashCommandsFor,
+  parseHostSurface,
+  toSlashCommandInfo,
+} from "./hostSlashCommands.js";
+import { messageForUi, messagesForUi } from "./uiPayload.js";
 
 export type NotificationEmitter = (
-  method: string,
+  method: ServerNotificationMethod,
   params: unknown,
   sessionId?: string,
 ) => void;
@@ -91,6 +139,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 +169,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;
 }
 
 // 会话级覆盖项：用户偏好（语言 / 上下文长度 / 自动记忆开关与频率）不在此层——
@@ -135,7 +201,7 @@ interface SessionEntry {
   storedConfig: Partial<InitializeParams>;
   /**
    * The workdir the session was CREATED in — an immutable identity, unlike the
-   * live `agent.workingDirectory`, which drifts as the session `cd`s (bash tool
+   * live `agent.currentWorkdir`, which drifts as the session `cd`s (bash tool
    * / worktree switches). Hosted-session consumers (destroy --remove-worktree's
    * worktree resolution, list) read this instead of the live value so a session
    * that moved out of its worktree into the main repo is still cleaned up at
@@ -189,14 +255,34 @@ 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>();
+  /**
+   * In-flight next-edit calls, same one-per-session rule and same reason as
+   * completions. It also participates in the cross-capability exclusion from
+   * `docs/specs/ui/next-edit-suggestion.md`: completion and next-edit never hold
+   * an in-flight request at the same time, so one of them cannot answer into a
+   * buffer the other has already rewritten.
+   */
+  private inFlightNextEdits = 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 +297,7 @@ export class AgentBridge {
   // ── Public API ────────────────────────────────────────────────
 
   async handleRequest(
-    method: string,
+    method: RequestMethod,
     params: unknown,
     sessionId?: string,
   ): Promise<unknown> {
@@ -221,7 +307,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 +399,20 @@ export class AgentBridge {
       case "deleteQueuedMessageById":
         return this.deleteQueuedMessageById(p.id as string, sessionId);
       case "getMessages":
-        return this.getMessages(sessionId);
+        return this.getMessages(sessionId, {
+          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);
@@ -341,7 +439,7 @@ export class AgentBridge {
 
       // ── Commands ──
       case "getSlashCommands":
-        return this.getSlashCommands(sessionId);
+        return this.getSlashCommands(sessionId, parseHostSurface(p.surface));
       case "getSubagentConfigurations":
         return this.getSubagentConfigurations(sessionId);
       case "getSkillMetadata":
@@ -390,6 +488,30 @@ export class AgentBridge {
         return this.login(p.serverUrl as string | undefined);
       case "logout":
         return this.logout();
+      case "installGitCredentialHelper":
+        return installGitCredentialHelper();
+
+      // ── 创作集（global — 账号级读写，无 session 要求）──
+      // 桌面端整页与右侧预览面板共用这一组；HTTP 与 token 只留在本进程
+      // （services/artifactGallery.ts），宿主不直连网络。
+      case "artifactGalleryList":
+        return fetchArtifactGalleryList();
+      case "artifactShareView":
+        return fetchArtifactShareView(p.slug as string);
+      case "artifactShareSave":
+        return saveArtifactShare({
+          slug: p.slug as string,
+          mode: p.mode as ArtifactShareMode,
+          userIds: p.userIds as string[] | undefined,
+          pinnedVersion: p.pinnedVersion as number | null | undefined,
+        });
+      case "artifactRevoke":
+        return revokeArtifact(p.slug as string);
+      case "artifactMembersSearch":
+        return searchArtifactMembers(
+          (p.search as string | undefined) ?? "",
+          p.limit as number | undefined,
+        );
 
       // ── Memory files (settings UI — user-level ~/.wave/AGENTS.md and
       //    project-level <workdir>/AGENTS.md) ──
@@ -527,7 +649,17 @@ 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);
+      // ── 最近打开的工作目录（spec core/recent-workdirs.md）──
+      // 机器级、与会话无关：文件就在这台机器上，谁问就回谁的。桌面端按主机
+      // 各问一次，远控 Web 页问它连着的那个进程。
+      case "getRecentWorkdirs":
+        return { dirs: readRecentWorkdirs() };
+      case "rememberRecentWorkdir":
+        rememberRecentWorkdir(p.workdir as string);
+        return null;
       case "listGitBranches":
         return this.listGitBranches(p.workdir as string | undefined);
       case "createWorktree":
@@ -542,6 +674,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 +685,64 @@ 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;
+            snippets?: CompletionSnippet[];
+          },
+          sessionId,
+        );
+      case "reportCompletionOutcome":
+        return this.reportCompletionOutcome(
+          p.outcome as "displayed" | "accepted",
+          sessionId,
+        );
+      case "reportNextEditOutcome":
+        return this.reportNextEditOutcome(
+          p.outcome as "displayed" | "accepted",
+          sessionId,
+        );
+      case "getNextEdit":
+        return this.getNextEdit(
+          p as unknown as {
+            edits?: NextEditHistoryEntry[];
+            region?: NextEditRegion;
+            excerpt?: NextEditExcerpt;
+            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;
@@ -579,7 +761,9 @@ export class AgentBridge {
 
   private async initialize(params: InitializeParams): Promise<{
     sessionId: string;
-    workingDirectory: string;
+    currentWorkdir: string;
+    sessionCwd: string;
+    repoRoot?: string;
     permissionMode: PermissionMode;
     latestTotalTokens: number;
   }> {
@@ -589,18 +773,23 @@ export class AgentBridge {
     if (params.restoreSessionId) {
       const live = this.sessions.get(params.restoreSessionId);
       if (live) {
-        return {
-          sessionId: live.agent.sessionId,
-          workingDirectory: live.agent.workingDirectory,
-          permissionMode: live.agent.getPermissionMode(),
-          latestTotalTokens: live.agent.latestTotalTokens,
-        };
+        return this.initializeReply(live.agent, live.createdWorkdir);
       }
     }
 
     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 +808,7 @@ export class AgentBridge {
       mcpServers: params.mcpServers,
       worktreeName: params.worktreeName,
       isNewWorktree: params.isNewWorktree,
+      entrypoint,
       canUseTool: (context: ToolPermissionContext) =>
         this.canUseTool(context, ctx),
     };
@@ -639,9 +829,9 @@ export class AgentBridge {
       createdWorkdir =
         (await readTranscriptWorkdir(agent.sessionFilePath)) ??
         params.workdir ??
-        agent.workingDirectory;
+        agent.currentWorkdir;
     } else {
-      createdWorkdir = params.workdir ?? agent.workingDirectory;
+      createdWorkdir = params.workdir ?? agent.currentWorkdir;
     }
 
     this.sessions.set(agent.sessionId, {
@@ -652,15 +842,84 @@ export class AgentBridge {
       createdWorkdir,
     });
 
+    return this.initializeReply(agent, createdWorkdir);
+  }
+
+  /**
+   * The `initialize` reply.
+   *
+   * The current cwd and the session root travel as two separate facts on
+   * purpose. A re-attached session may have bash-`cd`'d away from where it was
+   * created, so `agent.currentWorkdir` answers "where is it now" while
+   * `createdWorkdir` answers "which project does this conversation belong to".
+   * Hosts key durable things (sidebar grouping, project-scoped config, `@file`
+   * scope) off the latter — the desktop used to derive both from one
+   * `workingDirectory` field and moved a resumed conversation into a
+   * subdirectory group.
+   *
+   * `repoRoot` closes the worktree case: a session created inside a linked git
+   * worktree belongs to the repo it was forked from. It is derived the same way
+   * `listDaemonSessions` derives each row's `worktree`, i.e. from the
+   * filesystem, without shelling out to git.
+   */
+  private initializeReply(
+    agent: Agent,
+    sessionCwd: string,
+  ): {
+    sessionId: string;
+    currentWorkdir: string;
+    sessionCwd: string;
+    repoRoot?: string;
+    permissionMode: PermissionMode;
+    latestTotalTokens: number;
+  } {
+    const worktree = deriveWorktreeInfo(sessionCwd);
     return {
       sessionId: agent.sessionId,
-      workingDirectory: agent.workingDirectory,
+      currentWorkdir: agent.currentWorkdir,
+      sessionCwd,
+      ...(worktree ? { repoRoot: worktree.repoRoot } : {}),
       permissionMode: agent.getPermissionMode(),
       latestTotalTokens: agent.latestTotalTokens,
     };
   }
 
-  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 +946,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 +1033,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 +1105,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 +1127,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 +1176,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 +1266,122 @@ 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;
+      snippets?: CompletionSnippet[];
+    },
+    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. A next-edit suggestion in flight is
+    // dropped too — both rewrite the same buffer (spec ui/next-edit-suggestion.md).
+    this.inFlightCompletions.get(key)?.abort();
+    this.inFlightNextEdits.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 } : {}),
+        // `undefined` (host cannot collect snippets) and `[]` (tried, found
+        // nothing) stay distinguishable here and both mean "no snippets" to
+        // the model; only an absent field is left out of the call.
+        ...(params.snippets ? { snippets: params.snippets } : {}),
+        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);
+      }
+    }
+  }
+
+  /**
+   * One next-edit suggestion for the editor plugins (spec
+   * ui/next-edit-suggestion.md).
+   *
+   * Session-scoped for the same reason as completion: the model, the switch and
+   * the credentials all live in that session. Read-only, so a suggestion still
+   * resolves while `updateConfig` rebuilds the session.
+   */
+  private async getNextEdit(
+    params: {
+      edits?: NextEditHistoryEntry[];
+      region?: NextEditRegion;
+      excerpt?: NextEditExcerpt;
+      language?: string;
+      filePath?: string;
+    },
+    sessionId?: string,
+  ): Promise<{ suggestion: NextEditSuggestion | null; model: string }> {
+    const entry = this.requireSessionForRead(sessionId);
+    const key = sessionId as string;
+
+    // A region and its excerpt are the whole basis of the answer; without them
+    // there is nothing to predict into, so this is a no-op rather than an error.
+    if (!params.region || !params.excerpt) {
+      return { suggestion: null, model: "" };
+    }
+
+    // Same exclusion as the completion path, from this side.
+    this.inFlightNextEdits.get(key)?.abort();
+    this.inFlightCompletions.get(key)?.abort();
+    const controller = new AbortController();
+    this.inFlightNextEdits.set(key, controller);
+
+    try {
+      return await entry.agent.getNextEdit({
+        edits: params.edits ?? [],
+        region: params.region,
+        excerpt: params.excerpt,
+        ...(params.language ? { language: params.language } : {}),
+        ...(params.filePath ? { filePath: params.filePath } : {}),
+        abortSignal: controller.signal,
+      });
+    } finally {
+      if (this.inFlightNextEdits.get(key) === controller) {
+        this.inFlightNextEdits.delete(key);
+      }
+    }
+  }
+
   private async createWorktreeSession(params: {
     workdir: string;
     baseBranch?: string;
@@ -972,23 +1467,45 @@ export class AgentBridge {
     return { ok: true };
   }
 
-  private getSessionInfo(sessionId?: string): {
+  private async getSessionInfo(sessionId?: string): Promise<{
     sessionId: string;
-    workingDirectory: string;
+    sessionCwd: 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,
-      // The recorded creation workdir, not the live agent.workingDirectory:
+      // The recorded creation workdir, not the live agent.currentWorkdir:
       // destroy --remove-worktree resolves the session's worktree from this
       // value, and it must not drift when the session cd'd out of the worktree.
-      workingDirectory: entry.createdWorkdir,
+      sessionCwd: entry.createdWorkdir,
       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 +1556,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),
       };
@@ -1095,7 +1615,7 @@ export class AgentBridge {
   }
 
   private getConfiguredModels(sessionId?: string): {
-    models: string[];
+    models: ConfiguredModel[];
     currentModel: string | undefined;
   } {
     const entry = this.requireSessionForRead(sessionId);
@@ -1167,20 +1687,31 @@ export class AgentBridge {
     sessionId?: string,
   ): Promise<null> {
     const entry = this.requireSession(sessionId);
-    if (params.force) {
-      entry.agent.abortMessage();
-    }
     // Save prompt to history (mirrors VSCE chatSession.ts:236-242)
     try {
       await PromptHistoryManager.addEntry(
         params.text,
         entry.agent.sessionId,
         {},
-        entry.agent.workingDirectory,
+        entry.agent.currentWorkdir,
       );
     } catch {
       // Best-effort; don't block message sending on history save failure
     }
+    if (params.force) {
+      // "Send now" for one queued item: interrupt the running turn but keep the
+      // rest of the queue — the host removes the picked item separately, and
+      // everything it did not touch must still be delivered afterwards.
+      //
+      // The abort must be immediately followed by `sendMessage` with nothing
+      // awaited in between: the abort resets the loading flag, which is the gate
+      // a queued item waits behind, so any await here lets the *next* queued
+      // message start a turn first — the picked one would then be enqueued at
+      // the tail instead of going out now (realhost smoke: with the history
+      // write above the abort, a `deleteQueuedMessageById` landing in that gap
+      // started the remaining message immediately).
+      entry.agent.abortMessage({ keepQueue: true });
+    }
     await entry.agent.sendMessage(
       params.text,
       this.persistDataUrlImages(params.images),
@@ -1339,14 +1870,74 @@ export class AgentBridge {
     return null;
   }
 
-  private getMessages(sessionId?: string): {
-    messages: Message[];
-    contextUsagePercent?: number;
-  } {
+  /**
+   * Read a session's display messages.
+   *
+   * With no parameters this returns the whole list the agent holds, read once
+   * and cached nowhere (spec ui/message-rendering-system.md「首屏就是整份列表，
+   * 不分页」). Two parameters narrow it, both for the remote page:
+   *
+   * - `limit` — the newest `limit` messages (that page's frame budget).
+   * - `since` — everything appended after the given message id (catching up
+   *             after a reconnect).
+   *
+   * The list starts at the last compaction, so its earliest entry is the
+   * earliest any UI can reach; there is nothing older to read back.
+   *
+   * `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 instead of guessing.
+   *
+   * Ids can repeat (old transcripts re-appended the preserved rounds at each
+   * compact point), so anchors are resolved to their **last** occurrence:
+   * "after `since`" means after the newest copy the caller could have seen.
+   */
+  private async getMessages(
+    sessionId?: string,
+    window?: MessageWindow,
+  ): Promise<MessageWindowResult> {
     const entry = this.requireSessionForRead(sessionId);
+    const contextUsagePercent = this.contextUsagePercentOf(entry.agent);
+
+    // The validation 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 normalized: MessageWindow | undefined;
+    try {
+      normalized = normalizeMessageWindow(window);
+    } catch (err) {
+      if (err instanceof InvalidMessageWindowError) {
+        throw new RpcError(PROTOCOL_INVALID_PARAMS, err.message);
+      }
+      throw err;
+    }
+    // The totals ride along with the window: the list starts at the last
+    // compaction, so this reply is the only place a host can learn the
+    // thread's size and its first user message (the session-title fallback).
+    const threadSummary = entry.agent.getThreadSummary();
+    // Trimmed on the way out, never in the agent's own list: no UI renders tool
+    // pictures, and the agent has to keep them for the next request
+    // (specs/ui/stdio-transport.md「工具图片的字节不下发 UI」). The trim is
+    // copy-on-write, so a message with no picture keeps its identity.
+    if (!normalized) {
+      return {
+        // `Agent.messages` already hands back a copy, so this reply is a
+        // single-pass view for the host that asked once — do not copy again
+        // (a long session makes this O(n) per call).
+        messages: messagesForUi(entry.agent.messages),
+        contextUsagePercent,
+        threadSummary,
+      };
+    }
+    const page = entry.agent.getMessagePage(normalized);
     return {
-      messages: entry.agent.displayMessages,
-      contextUsagePercent: this.contextUsagePercentOf(entry.agent),
+      ...page,
+      messages: messagesForUi(page.messages),
+      contextUsagePercent,
+      threadSummary,
     };
   }
 
@@ -1355,7 +1946,8 @@ export class AgentBridge {
     sessionIds: string[];
   }> {
     const entry = this.requireSessionForRead(sessionId);
-    return entry.agent.getFullMessageThread();
+    const thread = await entry.agent.getFullMessageThread();
+    return { ...thread, messages: messagesForUi(thread.messages) };
   }
 
   private async compact(
@@ -1431,6 +2023,43 @@ export class AgentBridge {
     return { mode: entry.agent.getPermissionMode() };
   }
 
+  /**
+   * Records what the editor host saw happen to the last suggestion —
+   * `displayed` when it rendered the ghost text, `accepted` when the user took
+   * it. The outcome is the only thing the host reports: the model and the
+   * language stay on this side, derived when the completion was produced.
+   */
+  private reportCompletionOutcome(
+    outcome: "displayed" | "accepted",
+    sessionId?: string,
+  ): { ok: true } {
+    const entry = this.requireSessionForRead(sessionId);
+    if (outcome !== "displayed" && outcome !== "accepted") {
+      throw new RpcError(
+        PROTOCOL_INTERNAL_ERROR,
+        "outcome must be 'displayed' or 'accepted'",
+      );
+    }
+    entry.agent.reportCompletionOutcome(outcome);
+    return { ok: true };
+  }
+
+  /** The next-edit twin: same validation, its own metric series in the SDK. */
+  private reportNextEditOutcome(
+    outcome: "displayed" | "accepted",
+    sessionId?: string,
+  ): { ok: true } {
+    const entry = this.requireSessionForRead(sessionId);
+    if (outcome !== "displayed" && outcome !== "accepted") {
+      throw new RpcError(
+        PROTOCOL_INTERNAL_ERROR,
+        "outcome must be 'displayed' or 'accepted'",
+      );
+    }
+    entry.agent.reportNextEditOutcome(outcome);
+    return { ok: true };
+  }
+
   /**
    * Returns the current plan file path and its contents for the session.
    * When the path generation is still in flight (e.g. the host just switched
@@ -1505,9 +2134,28 @@ export class AgentBridge {
 
   // ── Commands ──────────────────────────────────────────────────
 
-  private getSlashCommands(sessionId?: string): { commands: SlashCommand[] } {
+  /**
+   * The popup's rows: the agent's own commands (skills / custom / plugin) plus
+   * the host-local table for the front end that asked.
+   *
+   * `surface` is optional on purpose: a client that predates the field asks
+   * without it and gets exactly what it got before (the SDK half), instead of
+   * being handed rows it has no handling for. Unknown values are dropped the
+   * same way by `parseHostSurface`.
+   */
+  private getSlashCommands(
+    sessionId?: string,
+    surface?: HostSurface,
+  ): { commands: SlashCommandInfo[] } {
     const entry = this.requireSessionForRead(sessionId);
-    return { commands: entry.agent.getSlashCommands() };
+    const agentCommands = entry.agent
+      .getSlashCommands()
+      .map((command) => toSlashCommandInfo(command));
+    return {
+      commands: surface
+        ? [...agentCommands, ...hostSlashCommandsFor(surface)]
+        : agentCommands,
+    };
   }
 
   private getSubagentConfigurations(sessionId?: string): {
@@ -1654,7 +2302,7 @@ export class AgentBridge {
       });
       this.emit(
         "permissionRequest",
-        { requestId, context },
+        remoteWire.permissionRequest(requestId, context),
         ctx.registeredSessionId,
       );
     });
@@ -1701,31 +2349,142 @@ 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;
-      workingDirectory: string;
+      sessionCwd: string;
       isLoading: boolean;
       hasRunningBackgroundWork: boolean;
       hasPendingMessages: boolean;
       messageCount: number;
+      /** User-set title; wins over `firstMessage` in the UI. */
+      customTitle?: string;
+      /** First real user message — the label when no custom title is set. */
+      firstMessage?: string;
+      /** Last display message's timestamp: the session list's ordering key. */
+      lastActiveAt?: string;
+      /**
+       * 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 customTitle = entry.agent.customTitle;
+        // Totals come from the agent's counters, not from `displayMessages`:
+        // that is only the resident tail now, so its length and its first
+        // message are no longer the thread's.
+        const summary = entry.agent.getThreadSummary();
+        const firstMessage = summary.firstUserText;
+        const lastActiveAt = summary.lastActiveAt;
+        // 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,
+          sessionCwd: entry.createdWorkdir,
+          isLoading: entry.transitioning === true || entry.agent.isLoading,
+          hasRunningBackgroundWork: entry.agent.hasRunningBackgroundWork,
+          hasPendingMessages: entry.agent.hasPendingMessages,
+          messageCount: summary.messageCount,
+          ...(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;
@@ -1811,7 +2570,7 @@ export class AgentBridge {
       return { content: await readTextFileSafe(path), path };
     }
     const resolvedWorkdir =
-      workdir || (agent?.workingDirectory as string | undefined);
+      workdir || (agent?.currentWorkdir as string | undefined);
     if (!resolvedWorkdir) {
       throw new RpcError(
         PROTOCOL_INVALID_PARAMS,
@@ -1850,7 +2609,7 @@ export class AgentBridge {
       return { ok: true };
     }
     const resolvedWorkdir =
-      workdir || (agent?.workingDirectory as string | undefined);
+      workdir || (agent?.currentWorkdir as string | undefined);
     if (!resolvedWorkdir) {
       throw new RpcError(
         PROTOCOL_INVALID_PARAMS,
@@ -2152,7 +2911,7 @@ export class AgentBridge {
         if (msg)
           this.emit(
             "userMessageAdded",
-            { message: msg },
+            { message: messageForUi(msg) },
             ctx.registeredSessionId,
           );
       },
@@ -2161,30 +2920,33 @@ export class AgentBridge {
         if (msg)
           this.emit(
             "assistantMessageAdded",
-            { message: msg },
+            { message: messageForUi(msg) },
             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 +2954,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 +2982,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 +3003,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 +3024,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 +3041,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?.messages ?? []).filter(
           (m) =>
             m.role === "user" &&
             m.blocks.some(
@@ -2291,14 +3054,19 @@ export class AgentBridge {
                 (b as { taskId: string }).taskId === params.taskId,
             ),
         );
+        const msg = matches[matches.length - 1];
         this.emit(
           "notificationMessageAdded",
-          { ...params, message: msg },
+          { ...params, message: msg ? messageForUi(msg) : undefined },
           ctx.registeredSessionId,
         );
       },
-      onCompactBlockAdded: (content: string) => {
-        this.emit("compactBlockAdded", { content }, ctx.registeredSessionId);
+      onCompactBlockAdded: (content: string, message?: Message) => {
+        this.emit(
+          "compactBlockAdded",
+          { content, message: message ? messageForUi(message) : undefined },
+          ctx.registeredSessionId,
+        );
       },
       onCompactionStateChange: (isCompacting: boolean) => {
         this.emit(
@@ -2373,7 +3141,7 @@ export class AgentBridge {
 
   private getSessionWorkdir(sessionId?: string): string | undefined {
     if (!sessionId) return undefined;
-    return this.sessions.get(sessionId)?.agent.workingDirectory;
+    return this.sessions.get(sessionId)?.agent.currentWorkdir;
   }
 }