feat(browser-bridge): offer the extension this build speaks to, and report a stale one honestly

The browser will not install an extension for the person: a store install needs their
own click, and an unpacked install needs developer mode and a folder they pick. What
the host can do is make sure the package they get is the one this build produces — a
stale extension is the failure that reads like a network timeout and costs an
afternoon.

The host rebuilds the extension when its sources are newer than its build, packs it
as a zip, and serves it at GET /browser-extension behind the per-start credential.
Settings → 浏览器 → 下载最新扩展包 links it; the link carries the token because the
route is admitted like every other document the host serves. A host that carries no
extension answers 404 rather than an empty archive, because an empty package reads
like a download that worked.

The other half is the report. A session that goes away while a command is in flight
is a disconnection, not a timeout: nothing was late, the peer hung up, and the two
call for opposite responses. The peer announces its build in the handshake and the
host knows the build it ships, so the message names the versions instead of leaving
the reader to look for a network problem that is not there. The extension's version
follows its protocol (0.2.0): the open-tab frame is a protocol change, and a host
that speaks it has to be able to tell an older extension from a current one.

Author: Fectivnfy112357

packages/agent-tools/src/desktop/local-browser.ts

@@ -596,7 +596,9 @@ async function executeBrowserAction(
             errorCode === 'background_render_operation_timeout' ||
             errorCode === 'background_render_queue_timeout'
           ? 'BROWSER_OPERATION_TIMEOUT'
-          : errorCode;
+          : errorCode === 'browser_extension_disconnected'
+            ? 'BROWSER_EXTENSION_DISCONNECTED'
+            : errorCode;
     const structuredCode = normalizedErrorCode ?? /^([A-Z][A-Z0-9_]+):/u.exec(message)?.[1];
     const label =
       isRecord(error) && typeof error.label === 'string'

packages/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "MiniMax Code Browser Bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pairs this browser with a local MiniMax Code WebUI host so the person and the Agent can operate the same browser session.",
   "minimum_chrome_version": "116",
   "background": {

packages/browser-extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mavis/browser-extension",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Edge/Chrome extension that bridges a person's own browser to the local WebUI browser bridge.",
   "license": "MIT",
   "type": "module",

packages/webui/docs/browser-use/02-bridge-protocol.md

@@ -324,6 +324,19 @@ effect the user already sees.
 On deadline expiry the operation reports `browser_operation_timeout` from the pinned error-code set
 (`packages/webui/src/shared/contracts/browser.ts`).
 
+**A disconnect is not a timeout.** When the session goes away while a command is in flight, the
+command did not run out of time — the peer hung up. The host reports that as its own code,
+`browser_extension_disconnected`, because the two call for opposite responses: a timeout is worth
+retrying and a disconnect is not. The usual cause of a disconnect is an extension older than the
+host it is talking to — it cannot read the frames this build sends, so it closes the socket rather
+than refusing them, and the host used to read that as a timeout.
+
+The peer announces its build in the `hello` frame (`extensionVersion`), and the host knows the
+build it ships (`expectedExtensionVersion`, read from the extension's own `manifest.json` by the
+composition root). When the two disagree the message names both versions, so "your extension is
+behind" is a fact rather than a guess; when the host does not know its own build, the message says
+the extension *may* be out of date and points at the download in Settings.
+
 **`measured`, in part.** A real Chrome and a real Edge had the extension's service worker
 terminated while an image stream was running: the host saw the session drop, the surface went
 down, and the bridge was usable again as soon as the worker woke. The 250 ms → 4 s ladder and the

packages/webui/docs/browser-use/03-extension-admission.md

@@ -239,6 +239,25 @@ path.
 | **The peer is authenticated against a local process** | `implemented` — the `Origin` header still selects the allowlisted extension id, and it is no longer the thing that decides. A peer must additionally prove possession of the **installation key** before the host hands over a pairing credential, and a peer that proves only a credential this host already issued receives no credential at all. A local process can spoof the origin and supply its own ECDH key, but it holds neither secret, so no `pair` frame is sent to it. See [`04-pairing-credentials.md`](04-pairing-credentials.md) |
 | **The specific refusal says what is missing** | `implemented` — `BrowserBridgeProofRefusal` distinguishes `switched_off`, `unknown_nonce`, `unknown_key_id`, `installation_key_mismatch`, `pairing_credential_mismatch` and `no_peer_public_key`, and each maps to its own stable `closed`-frame reason text in `describeRefusal` (`session.ts`). A generic "pairing proof failed" would leave the person unable to tell "paste your installation key" from "your host rotated". |
 
+## Updating the extension, and what loading a new build costs
+
+**`implemented`.** The browser does not install an extension for the person: a store install needs
+their own click in the store, and an unpacked install needs developer mode and a folder they pick.
+What the host can do is make sure the package they get is the one this build speaks to, because a
+stale extension is the failure that reads like a network timeout and costs an afternoon.
+
+| Element | State |
+| --- | --- |
+| The host builds the extension when its sources are newer than its build | `implemented` — `ensureCurrentBuild`, `packages/webui/src/server/browser-bridge/extension-package.ts` |
+| The package is served as a download, behind the per-start credential | `implemented` — `GET /browser-extension`, `packages/webui/src/server/http/browser-extension.ts`; the name carries the version, so two packages are told apart |
+| The person is offered it in one place | `implemented` — 浏览器 → 下载最新扩展包, `packages/webui/src/client/features/browser/ui/BrowserSettingsPage.public.tsx` |
+| A host with no extension says so | `implemented` — the route answers `404`, never an empty archive, because an empty package reads like a download that worked |
+
+Loading the package costs one thing, and the Settings page says so: an unpacked extension's id is
+derived from the folder it is loaded from, so a new folder is a **new identity**. The person pairs
+it again with the installation key from the same Settings page, and the development host learns the
+new identity from that proof rather than from a configuration the person cannot know.
+
 ## Related
 
 | Concern | Document |

packages/webui/src/client/application/port-slices.ts

@@ -161,6 +161,7 @@ const BROWSER_KEYS = [
   "closeBrowserWebTab",
   "listBrowserCapabilities",
   "getBrowserInstallationKey",
+  "browserExtensionPackageUrl",
 ] as const satisfies readonly (keyof BrowserPort)[];
 
 const COMPOSER_KEYS = [

packages/webui/src/client/features/browser/contracts/browser-port.ts

@@ -283,4 +283,15 @@ export interface BrowserPort {
   readonly getBrowserInstallationKey?: (request: {
     readonly surface: WebuiBridgeBrowserSurface;
   }) => Promise<WebuiBrowserInstallationKeyResult>;
+  /**
+   * The URL of the extension package this host produces.
+   *
+   * The browser will not install an extension for the person — a store install
+   * needs their own click, and an unpacked install needs developer mode and a
+   * folder they pick — so the host's part is to hand them the package this
+   * build speaks to. The URL is built by the transport rather than by a
+   * component, because only the transport knows the per-start token the route
+   * checks.
+   */
+  readonly browserExtensionPackageUrl?: () => string;
 }

packages/webui/src/client/features/browser/ui/BrowserSettingsPage.public.tsx

@@ -18,7 +18,9 @@
 
 import { useCallback, useEffect, type ReactElement } from "react";
 
-import { SettingsPage } from "../../../ui/settings-layout.js";
+import { SettingsPage, SettingsRow, SettingsSection } from "../../../ui/settings-layout.js";
+import { WebuiButtonLink } from "../../../ui/button.js";
+import { useWebuiPortSlice } from "../../../bindings/port-slices-context.js";
 import {
   useWebuiBrowserAuthorization,
   useWebuiBrowserAuthorizationState,
@@ -32,6 +34,9 @@ import {
 export function BrowserSettingsPage(): ReactElement {
   const owner = useWebuiBrowserAuthorization();
   const state = useWebuiBrowserAuthorizationState();
+  // The package is the host's, and the host knows where it is: the port builds
+  // the URL because only it knows the token the route checks.
+  const packageUrl = useWebuiPortSlice("browser")?.browserExtensionPackageUrl?.();
 
   // The read is the owner's, and it is asked for once per mount: a second
   // caller re-reads the same answer rather than keeping a second copy of it.
@@ -62,6 +67,61 @@ export function BrowserSettingsPage(): ReactElement {
       <BrowserInstallationKey
         readKey={state?.canReadInstallationKey && owner ? owner.readInstallationKey : undefined}
       />
+      <BrowserExtensionPackage packageUrl={packageUrl} />
     </SettingsPage>
   );
 }
+
+/**
+ * The extension package, as the settings page offers it.
+ *
+ * The browser will not install an extension for the person: a store install
+ * needs their own click, and an unpacked install needs developer mode and a
+ * folder they pick. What the host can do is hand them the package this build
+ * produces, so the extension they load is one this build can talk to — a
+ * mismatch between the two reads like a network timeout and costs an
+ * afternoon.
+ *
+ * The link opens in a new tab on purpose. A download that succeeds leaves the
+ * page alone, and one that fails opens the host's own refusal beside it
+ * rather than replacing the settings the person was reading.
+ */
+function BrowserExtensionPackage({
+  packageUrl,
+}: {
+  readonly packageUrl?: string;
+}): ReactElement {
+  return (
+    <SettingsSection
+      title="浏览器扩展包"
+      testId="browser-extension-package"
+      hint="扩展由你手动加载，浏览器不会替人安装。"
+    >
+      <SettingsRow
+        title="下载最新扩展包"
+        description={
+          packageUrl
+            ? "下载这个构建对应的扩展包，解压后在浏览器的扩展管理页用「加载已解压的扩展程序」加载它。换个目录加载会改变扩展的身份，需要用新的安装密钥重新配对。"
+            : "当前运行时没有随附浏览器扩展，没有可下载的扩展包。"
+        }
+        testId="browser-extension-package-row"
+      >
+        {packageUrl ? (
+          <WebuiButtonLink
+            href={packageUrl}
+            download
+            target="_blank"
+            rel="noreferrer"
+            variant="quiet-secondary"
+            size="inline"
+            data-testid="browser-extension-package-download"
+          >
+            下载最新扩展包
+          </WebuiButtonLink>
+        ) : (
+          <span data-testid="browser-extension-package-unavailable">不可用</span>
+        )}
+      </SettingsRow>
+    </SettingsSection>
+  );
+}

packages/webui/src/client/platform/transport.ts

@@ -218,6 +218,7 @@ export function createWebuiTransport(options: WebuiTransportOptions): Required<W
     watchMiniAppAgentTurn,
     watchMiniAppAgentObservations,
     workspaceFileUrl,
+    browserExtensionUrl,
     miniappStandaloneUrl,
     watchEvents,
   } = createWebuiWire(options);
@@ -289,6 +290,10 @@ export function createWebuiTransport(options: WebuiTransportOptions): Required<W
         operation: {...body.operation},
       }),
     workspaceFileUrl,
+    // The extension package is a download rather than an operation: the route
+    // answers with the archive itself, so the client needs the URL and not a
+    // reply to unwrap.
+    browserExtensionPackageUrl: browserExtensionUrl,
     readWorkspaceArchive: (body) => request(READ_WORKSPACE_ARCHIVE_OPERATION_NAME, body),
     extractWorkspaceArchive: (body) => request(EXTRACT_WORKSPACE_ARCHIVE_OPERATION_NAME, body),
     createTerminal: (body) => request(CREATE_TERMINAL_OPERATION_NAME, body),

packages/webui/src/client/platform/wire.ts

@@ -237,6 +237,15 @@ export interface WebuiWire {
   ): () => void;
   /** The one HTTP route, built from the same base and token as the socket. */
   workspaceFileUrl(input: { readonly workspaceDir: string; readonly path: string }): string;
+  /**
+   * The browser extension package this host produces, as a download.
+   *
+   * The route is admitted like every other document — the service checks the
+   * token on it — so the link carries it. The package is the build this host
+   * speaks to, so the person loads the extension this build can talk to
+   * rather than one they happened to download earlier.
+   */
+  browserExtensionUrl(): string;
   /**
    * The standalone Mini App's page, built from the same base and token.
    *
@@ -928,6 +937,15 @@ export function createWebuiWire({
     return `${base}/workspace-file?${query.toString()}`;
   }
 
+  function browserExtensionUrl(): string {
+    // Same base rule as `workspaceFileUrl`: the socket URL carries the token,
+    // the route checks it, and `ws:`/`wss:` share a prefix so one
+    // substitution reaches `http:`/`https:`.
+    const base = baseWebsocketUrl.replace(/\/$/u, "").replace(/^ws/iu, "http");
+    const query = new URLSearchParams({ token });
+    return `${base}/browser-extension?${query.toString()}`;
+  }
+
   return {
     request,
     stream,
@@ -941,6 +959,7 @@ export function createWebuiWire({
     watchMiniAppAgentTurn,
     watchMiniAppAgentObservations,
     workspaceFileUrl,
+    browserExtensionUrl,
     miniappStandaloneUrl,
     watchEvents: createWebuiEventChannel({ websocketUrl, webSocket }),
   };