🤖 feat: VS Code extension prefers oRPC with fallback (#1269)

This updates the VS Code extension to prefer a locally running mux
server (localhost oRPC) for listing workspaces.

If it can't connect, it prompts the user to either fix connection config
or fall back to direct local-file reads.

Adds:
- `mux: Configure Connection` command
- Settings: `mux.connectionMode` and `mux.serverUrl`
- Auth token override stored in VS Code SecretStorage

Validation:
- `bun run --cwd vscode compile`
- `make typecheck`
- `make static-check`

---

<details>
<summary>📋 Implementation Plan</summary>

# 🤖 Plan: VS Code extension → oRPC-first with safe local-file fallback

## Goal
Make the VS Code extension prefer talking to a locally running mux
instance over **localhost + oRPC** instead of reading mux’s
config/session files directly. If the extension **cannot connect**, it
should:
1) show a small prompt explaining why, and
2) let the user either **fix connection config** or **continue with
local file access** (with a warning about possible conflicts).

Net new product code: **~+250 LoC** (recommended approach).

---

## What exists today (repo facts)
- Extension entrypoint: `vscode/src/extension.ts` registers
`mux.openWorkspace`.
- Workspace listing currently uses direct disk reads via shared node
modules:
- `vscode/src/muxConfig.ts` → `new Config().getAllWorkspaceMetadata()`
(reads `~/.mux/config.json` etc)
- `vscode/src/muxConfig.ts` → `readExtensionMetadata()` (reads
`~/.mux/extensionMetadata.json`)
- mux already exposes a local oRPC server:
  - HTTP: `POST {baseUrl}/orpc`
  - WS: `{baseUrl}/orpc/ws`
  - Health: `GET {baseUrl}/health`
- mux server discovery already exists via:
  - Env: `MUX_SERVER_URL`, `MUX_SERVER_AUTH_TOKEN`
- Lockfile: `~/.mux/server.lock` via
`src/node/services/serverLockfile.ts`
- Needed API calls are already defined:
  - `workspace.list -> FrontendWorkspaceMetadata[]`
- `workspace.activity.list -> Record<workspaceId,
WorkspaceActivitySnapshot>` (recency/streaming/lastModel)

---

## Recommended approach (oRPC-first + guided fallback)
### High-level behavior
1. On `mux.openWorkspace`, try to create an oRPC client using server
discovery (settings/env/lockfile/default).
2. If connection succeeds, list workspaces via oRPC:
   - `workspace.list()` for metadata
   - `workspace.activity.list()` for recency/streaming
   - merge + sort by recency (same UX as today)
3. If connection fails, show a **single warning prompt per VS Code
session**:
- **Fix connection config** → launches a small configuration flow
(settings + secret)
- **Use local file access** → fall back to existing disk-based behavior
for the rest of the session
   - **Cancel** → abort the command
4. Auth failures (server reachable but 401/unauthorized) still offer
local-file fallback, but with a **strong warning**.

### Configuration storage (per your answers)
- Add VS Code settings:
- `mux.connectionMode`: `"auto" | "server-only" | "file-only"` (default:
`"auto"`)
  - `mux.serverUrl`: optional string (overrides discovery)
- Store auth token override in **VS Code SecretStorage**:
  - secret key: `mux.serverAuthToken`

### Discovery precedence
Base URL:
1) VS Code setting `mux.serverUrl` (if set)
2) `process.env.MUX_SERVER_URL`
3) `~/.mux/server.lock` (`ServerLockfile.read()`)
4) `http://localhost:3000`

Auth token:
1) SecretStorage override `mux.serverAuthToken`
2) `process.env.MUX_SERVER_AUTH_TOKEN`
3) lockfile token **only if** lockfile baseUrl matches selected baseUrl

### Connection test (fast + classified)
- `GET {baseUrl}/health` with a short timeout (e.g. 750–1000ms)
  - If this fails: classify as **not running / unreachable**.
- If health passes, call `orpc.general.ping("vscode")` (also timeout)
- If this fails with unauthorized/401: classify as **auth
misconfigured**.

---

## Implementation steps (files + concrete changes)
### 1) Add connection + client utilities
**New:** `vscode/src/orpc/client.ts`
- `createVscodeOrpcClient({ baseUrl, authToken }): ORPCClient`
- Use `RPCLink` from `@orpc/client/fetch` and inject `Authorization:
Bearer <token>`.
- Defensive asserts on `baseUrl` shape.

**New:** `vscode/src/orpc/discovery.ts`
- `discoverServerConfig(): Promise<{ baseUrl: string; authToken?:
string; source: ... }>`
- Reads settings/env/lockfile, plus SecretStorage token.
- Keep this mostly pure; isolate VS Code IO to small helpers.

**New:** `vscode/src/orpc/connectionCheck.ts`
- `checkServerReachable(baseUrl): Promise<"ok" | "unreachable">`
- `checkAuth(client): Promise<"ok" | "unauthorized" | "error">`
- Implement timeouts via `AbortController`.

### 2) Wire “oRPC workspace list” into the extension
**Edit:** `vscode/src/muxConfig.ts`
- Split existing logic into:
  - `getAllWorkspacesFromFiles()` (keep current disk behavior)
  - `getAllWorkspacesFromOrpc()`:
    - `client.workspace.list()`
    - `client.workspace.activity.list()`
    - map activity → `ExtensionMetadata` shape
    - merge onto workspace objects and sort by recency
- `getAllWorkspaces()` becomes a mode switch:
  - `file-only` → always `getAllWorkspacesFromFiles()`
  - `server-only` → error if cannot connect
  - `auto` → prefer orpc; on failure show prompt; obey session choice

### 3) Add UX for “fix config vs file access”
**Edit:** `vscode/src/extension.ts`
- Add session-level state:
  - `let sessionPreferredMode: "orpc" | "file" | null = null;`
  - `let didShowFallbackPrompt = false;`
- If orpc fails and `auto`:
  - `showWarningMessage` with actions:
    - **Fix connection config**
    - **Use local file access**
    - **Cancel**
- When auth failure: adjust message text to include strong warning about
conflicts.

### 4) Add a command to fix config
**Edit:** `vscode/src/extension.ts` + `vscode/package.json`
- Register new command: `mux.configureConnection`
- Implementation:
  - Prompt for server URL (pre-filled from current setting).
  - Prompt for token (password input) and store in SecretStorage.
  - Optionally offer “Clear token” / “Clear URL override” via QuickPick.
- From the fallback prompt, invoke this command.
- After configuration, retry connection once.

### 5) Add VS Code settings contributions
**Edit:** `vscode/package.json`
- Add `contributes.configuration` section:
  - `mux.connectionMode` (enum)
  - `mux.serverUrl` (string)
- Scope settings to **application/machine** (avoid workspace check-in
risk).

---

## Validation plan
- Build + typecheck:
  - `bun run -C vscode compile`
  - `make typecheck`
- Manual scenarios:
1) mux running (lockfile present): extension uses oRPC and lists
workspaces.
  2) mux not running: prompt appears once; choosing file access works.
3) mux running but token wrong (set bad secret): prompt shows auth
warning; file fallback still works.
  4) `mux.connectionMode=file-only`: never attempts network.
  5) `mux.connectionMode=server-only`: fails fast with actionable error.

---

<details>
<summary>Alternatives considered</summary>

### A) Server-side change: include activity in `workspace.list`
- Add `includeActivity` param so VS Code makes a single RPC call.
- Pros: fewer roundtrips.
- Cons: touches server API + backwards-compat; more surface area than
needed for first iteration.

### B) Don’t add VS Code settings
- Only env vars + lockfile discovery.
- “Fix config” would just open docs / show instructions.
- Pros: minimal change.
- Cons: doesn’t actually let users *fix* misconfig from within VS Code.

</details>

</details>

---
_Generated with `mux` • Model: `openai:gpt-5.2` • Thinking: `xhigh`_

---------

Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

vscode/package.json

@@ -22,16 +22,43 @@
     "development"
   ],
   "activationEvents": [
-    "onCommand:mux.openWorkspace"
+    "onCommand:mux.openWorkspace",
+    "onCommand:mux.configureConnection"
   ],
   "main": "./out/extension.js",
   "contributes": {
     "commands": [
       {
         "command": "mux.openWorkspace",
         "title": "mux: Open Workspace"
+      },
+      {
+        "command": "mux.configureConnection",
+        "title": "mux: Configure Connection"
+      }
+    ],
+    "configuration": {
+      "title": "mux",
+      "properties": {
+        "mux.connectionMode": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "server-only",
+            "file-only"
+          ],
+          "default": "auto",
+          "scope": "machine",
+          "description": "How the mux VS Code extension connects to mux (prefer server, require server, or use local files)."
+        },
+        "mux.serverUrl": {
+          "type": "string",
+          "default": "",
+          "scope": "machine",
+          "description": "Override the mux server URL (leave empty to auto-discover). Example: http://127.0.0.1:3000"
+        }
       }
-    ]
+    }
   },
   "scripts": {
     "vscode:prepublish": "bun run compile",
@@ -54,3 +81,4 @@
   "license": "AGPL-3.0-only",
   "packageManager": "[email protected]"
 }
+

vscode/src/api/client.ts

@@ -0,0 +1,52 @@
+import { RPCLink } from "@orpc/client/fetch";
+import type { RouterClient } from "@orpc/server";
+import assert from "node:assert";
+
+import { createClient } from "mux/common/orpc/client";
+import type { AppRouter } from "mux/node/orpc/router";
+
+export type ApiClient = RouterClient<AppRouter>;
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  authToken?: string | undefined;
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  assert(baseUrl.length > 0, "baseUrl must be non-empty");
+
+  const parsed = new URL(baseUrl);
+  assert(
+    parsed.protocol === "http:" || parsed.protocol === "https:",
+    `Unsupported baseUrl protocol: ${parsed.protocol}`
+  );
+
+  // URL.toString() includes a trailing slash for naked origins.
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function createApiClient(config: ApiClientConfig): ApiClient {
+  assert(typeof config.baseUrl === "string", "baseUrl must be a string");
+
+  const normalizedBaseUrl = normalizeBaseUrl(config.baseUrl);
+
+  const link = new RPCLink({
+    url: `${normalizedBaseUrl}/orpc`,
+    async fetch(request, init) {
+      const headers = new Headers(request.headers);
+      if (config.authToken) {
+        headers.set("Authorization", `Bearer ${config.authToken}`);
+      }
+
+      return fetch(request.url, {
+        body: await request.blob(),
+        headers,
+        method: request.method,
+        signal: request.signal,
+        ...init,
+      });
+    },
+  });
+
+  return createClient(link);
+}

vscode/src/api/connectionCheck.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert";
+
+import type { ApiClient } from "./client";
+
+export type ServerReachabilityResult =
+  | { status: "ok" }
+  | {
+      status: "unreachable";
+      error: string;
+    };
+
+export type AuthCheckResult =
+  | { status: "ok" }
+  | {
+      status: "unauthorized";
+      error: string;
+    }
+  | {
+      status: "error";
+      error: string;
+    };
+
+function normalizeBaseUrl(baseUrl: string): string {
+  assert(baseUrl.length > 0, "baseUrl must be non-empty");
+  return baseUrl.replace(/\/$/, "");
+}
+
+async function promiseWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  label: string
+): Promise<T> {
+  assert(timeoutMs > 0, "timeoutMs must be positive");
+
+  return new Promise<T>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    promise
+      .then(resolve, reject)
+      .finally(() => {
+        clearTimeout(timeout);
+      });
+  });
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isUnauthorizedError(error: unknown): boolean {
+  const msg = formatError(error).toLowerCase();
+  return (
+    msg.includes("unauthorized") ||
+    msg.includes("401") ||
+    msg.includes("auth token") ||
+    msg.includes("authentication")
+  );
+}
+
+export async function checkServerReachable(
+  baseUrl: string,
+  options?: { timeoutMs?: number }
+): Promise<ServerReachabilityResult> {
+  const timeoutMs = options?.timeoutMs ?? 1_000;
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const resp = await fetch(`${normalizedBaseUrl}/health`, {
+      method: "GET",
+      signal: controller.signal,
+    });
+
+    if (!resp.ok) {
+      return { status: "unreachable", error: `HTTP ${resp.status} from /health` };
+    }
+
+    const data = (await resp.json()) as { status?: unknown };
+    if (data.status !== "ok") {
+      return {
+        status: "unreachable",
+        error: "Unexpected /health response",
+      };
+    }
+
+    return { status: "ok" };
+  } catch (error) {
+    return {
+      status: "unreachable",
+      error: formatError(error),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function checkAuth(
+  client: ApiClient,
+  options?: { timeoutMs?: number }
+): Promise<AuthCheckResult> {
+  const timeoutMs = options?.timeoutMs ?? 1_000;
+
+  try {
+    // Used both as an auth check and a basic liveness check.
+    await promiseWithTimeout(client.general.ping("vscode"), timeoutMs, "API ping");
+    return { status: "ok" };
+  } catch (error) {
+    if (isUnauthorizedError(error)) {
+      return { status: "unauthorized", error: formatError(error) };
+    }
+
+    return { status: "error", error: formatError(error) };
+  }
+}

vscode/src/api/discovery.ts

@@ -0,0 +1,115 @@
+import * as vscode from "vscode";
+import assert from "node:assert";
+
+import { getMuxHome } from "mux/common/constants/paths";
+import { ServerLockfile } from "mux/node/services/serverLockfile";
+
+export type ConnectionMode = "auto" | "server-only" | "file-only";
+
+export interface DiscoveredServerConfig {
+  baseUrl: string;
+  authToken?: string | undefined;
+
+  // For debugging / UX messaging.
+  baseUrlSource: "settings" | "env" | "lockfile" | "default";
+  authTokenSource: "secret" | "env" | "lockfile" | "none";
+}
+
+const SERVER_AUTH_TOKEN_SECRET_KEY = "mux.serverAuthToken";
+
+function normalizeBaseUrl(baseUrl: string): string {
+  assert(baseUrl.length > 0, "baseUrl must be non-empty");
+
+  const parsed = new URL(baseUrl);
+  assert(
+    parsed.protocol === "http:" || parsed.protocol === "https:",
+    `Unsupported baseUrl protocol: ${parsed.protocol}`
+  );
+
+  // URL.toString() includes a trailing slash for naked origins.
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function getConnectionModeSetting(): ConnectionMode {
+  const config = vscode.workspace.getConfiguration("mux");
+  const value = config.get<unknown>("connectionMode");
+
+  if (value === "auto" || value === "server-only" || value === "file-only") {
+    return value;
+  }
+
+  return "auto";
+}
+
+export async function discoverServerConfig(
+  context: vscode.ExtensionContext
+): Promise<DiscoveredServerConfig> {
+  const config = vscode.workspace.getConfiguration("mux");
+  const serverUrlOverrideRaw = config.get<string>("serverUrl")?.trim();
+
+  let lockfileData: { baseUrl: string; token: string } | null = null;
+  try {
+    const lockfile = new ServerLockfile(getMuxHome());
+    const data = await lockfile.read();
+    if (data) {
+      lockfileData = { baseUrl: data.baseUrl, token: data.token };
+    }
+  } catch {
+    // Ignore lockfile errors; we'll fall back to defaults.
+  }
+
+  // Base URL precedence: settings -> env -> lockfile -> default.
+  const envBaseUrl = process.env.MUX_SERVER_URL?.trim();
+
+  let baseUrlSource: DiscoveredServerConfig["baseUrlSource"] = "default";
+  let baseUrlRaw = "http://localhost:3000";
+
+  if (serverUrlOverrideRaw) {
+    baseUrlSource = "settings";
+    baseUrlRaw = serverUrlOverrideRaw;
+  } else if (envBaseUrl) {
+    baseUrlSource = "env";
+    baseUrlRaw = envBaseUrl;
+  } else if (lockfileData) {
+    baseUrlSource = "lockfile";
+    baseUrlRaw = lockfileData.baseUrl;
+  }
+
+  const baseUrl = normalizeBaseUrl(baseUrlRaw);
+
+  // Auth token precedence: secret storage -> env -> lockfile (only if same baseUrl).
+  const secretToken = (await context.secrets.get(SERVER_AUTH_TOKEN_SECRET_KEY))?.trim();
+  const envToken = process.env.MUX_SERVER_AUTH_TOKEN?.trim();
+
+  let authTokenSource: DiscoveredServerConfig["authTokenSource"] = "none";
+  let authToken: string | undefined;
+
+  if (secretToken) {
+    authTokenSource = "secret";
+    authToken = secretToken;
+  } else if (envToken) {
+    authTokenSource = "env";
+    authToken = envToken;
+  } else if (lockfileData && normalizeBaseUrl(lockfileData.baseUrl) === baseUrl) {
+    authTokenSource = "lockfile";
+    authToken = lockfileData.token;
+  }
+
+  return {
+    baseUrl,
+    authToken,
+    baseUrlSource,
+    authTokenSource,
+  };
+}
+
+export async function storeAuthTokenOverride(
+  context: vscode.ExtensionContext,
+  authToken: string
+): Promise<void> {
+  await context.secrets.store(SERVER_AUTH_TOKEN_SECRET_KEY, authToken);
+}
+
+export async function clearAuthTokenOverride(context: vscode.ExtensionContext): Promise<void> {
+  await context.secrets.delete(SERVER_AUTH_TOKEN_SECRET_KEY);
+}