@vellumai/assistant 0.7.3 → 0.8.1

package/src/providers/registry.ts

@@ -1,24 +1,35 @@
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { type LLMConfig } from "../config/schemas/llm.js";
 import { getProviderKeyAsync } from "../security/secure-keys.js";
 import { ProviderNotConfiguredError } from "../util/errors.js";
-import { AnthropicProvider } from "./anthropic/client.js";
-import { FireworksProvider } from "./fireworks/client.js";
-import { GeminiProvider } from "./gemini/client.js";
+import { getLogger } from "../util/logger.js";
+import {
+  buildProviderAdapter,
+  createAdapterFromConnection,
+} from "./inference/adapter-factory.js";
+// ---------------------------------------------------------------------------
+// Per-connection provider cache (mix-and-match support)
+// ---------------------------------------------------------------------------
+import type { ProviderConnection } from "./inference/auth.js";
+import { resolveAuth } from "./inference/resolve-auth.js";
 import {
   buildManagedBaseUrl,
   resolveManagedProxyContext,
 } from "./managed-proxy/context.js";
-import { isModelInCatalog } from "./model-catalog.js";
+import { isModelInCatalog, PROVIDER_CATALOG } from "./model-catalog.js";
 import { getProviderDefaultModel } from "./model-intents.js";
-import { OllamaProvider } from "./ollama/client.js";
-import { OpenAIResponsesProvider } from "./openai/client.js";
-import { OpenRouterProvider } from "./openrouter/client.js";
 import { RetryProvider } from "./retry.js";
 import type { Provider } from "./types.js";
 import { UsageTrackingProvider } from "./usage-tracking.js";
 
+const log = getLogger("provider-registry");
+
 const providers = new Map<string, Provider>();
 const routingSources = new Map<string, "user-key" | "managed-proxy">();
 
+/** Per-connection provider cache, keyed by connection name. */
+const connectionProviders = new Map<string, Provider>();
+
 function registerProvider(name: string, provider: Provider): void {
   providers.set(name, new UsageTrackingProvider(provider));
 }
@@ -43,9 +54,7 @@ export function getProviderRoutingSource(
 
 export interface ProvidersConfig {
   services: {
-    inference: {
-      mode: "managed" | "your-own";
-    };
+    inference: Record<string, never>;
     "image-generation": {
       mode: "managed" | "your-own";
       provider: string;
@@ -56,25 +65,15 @@ export interface ProvidersConfig {
       provider: string;
     };
   };
-  llm: {
-    default: {
-      provider: string;
-      model: string;
-    };
-  };
+  llm: LLMConfig;
   timeouts?: { providerStreamTimeoutSec?: number };
 }
 
 function resolveModel(config: ProvidersConfig, providerName: string): string {
-  const inferenceProvider = config.llm.default.provider;
-  const inferenceModel = config.llm.default.model;
+  const resolved = resolveCallSiteConfig("mainAgent", config.llm);
+  const inferenceProvider = resolved.provider;
+  const inferenceModel = resolved.model;
   if (inferenceProvider === providerName) {
-    // If a non-Anthropic provider is selected but the configured model is
-    // still an Anthropic catalog model (current or previous default), use a
-    // provider-appropriate fallback instead. Checking the full Anthropic
-    // catalog rather than only the current default prevents stale persisted
-    // defaults (e.g. claude-opus-4-6) from being sent to non-Anthropic APIs
-    // after the catalog default changes.
     if (
       providerName !== "anthropic" &&
       isModelInCatalog("anthropic", inferenceModel)
@@ -87,50 +86,27 @@ function resolveModel(config: ProvidersConfig, providerName: string): string {
 }
 
 /**
- * Resolve provider credentials using mode-aware logic.
- * In "managed" mode, routes through the platform proxy.
- * In "your-own" mode, uses the user's API key.
+ * Resolve provider credentials. User key takes precedence; managed proxy is
+ * used as a fallback when platform prerequisites are available.
+ *
+ * The routing decision is now derived from credential availability rather than
+ * the removed `services.inference.mode` config field.
  */
 async function resolveProviderCredentials(
   providerName: string,
-  mode: "managed" | "your-own",
 ): Promise<{
   apiKey: string;
   baseURL?: string;
   source: "user-key" | "managed-proxy";
 } | null> {
-  if (mode === "managed") {
-    // In managed mode, try managed proxy first, then fall back to user key
-    const managedBaseUrl = await buildManagedBaseUrl(providerName);
-    if (managedBaseUrl) {
-      const ctx = await resolveManagedProxyContext();
-      return {
-        apiKey: ctx.assistantApiKey,
-        baseURL: managedBaseUrl,
-        source: "managed-proxy",
-      };
-    }
-    // Managed proxy unavailable for this provider; fall back to user key
-    const userKey = await getProviderKeyAsync(providerName);
-    if (userKey) {
-      return { apiKey: userKey, source: "user-key" };
-    }
-    return null;
-  }
-  // "your-own" mode: check user key first, then try managed proxy fallback
   const userKey = await getProviderKeyAsync(providerName);
   if (userKey) {
     return { apiKey: userKey, source: "user-key" };
   }
-  // Fall back to managed proxy even in your-own mode (backwards compat)
   const managedBaseUrl = await buildManagedBaseUrl(providerName);
   if (managedBaseUrl) {
     const ctx = await resolveManagedProxyContext();
-    return {
-      apiKey: ctx.assistantApiKey,
-      baseURL: managedBaseUrl,
-      source: "managed-proxy",
-    };
+    return { apiKey: ctx.assistantApiKey, baseURL: managedBaseUrl, source: "managed-proxy" };
   }
   return null;
 }
@@ -140,126 +116,134 @@ export async function initializeProviders(
 ): Promise<void> {
   providers.clear();
   routingSources.clear();
+  connectionProviders.clear();
 
   const streamTimeoutMs =
     (config.timeouts?.providerStreamTimeoutSec ?? 1800) * 1000;
-  const inferenceMode = config.services.inference.mode;
   const useNativeWebSearch =
     config.services["web-search"].provider === "inference-provider-native";
+  const mainAgentProvider = resolveCallSiteConfig("mainAgent", config.llm)
+    .provider;
+
+  for (const entry of PROVIDER_CATALOG) {
+    const isKeyless = entry.setupMode === "keyless";
+
+    // Credential resolution: user key first, managed proxy second. Keyless
+    // providers (e.g. ollama) skip both — they only need to be configured as
+    // the mainAgent provider, or have a key present (rare keyed-mode), to
+    // boot. Boot order matches catalog order; routingSources tracks which
+    // credential surface served each provider.
+    let apiKey = "";
+    let baseURL: string | undefined;
+    let source: "user-key" | "managed-proxy" = "user-key";
+    if (isKeyless) {
+      const key = await getProviderKeyAsync(entry.id);
+      const isConfiguredMainAgent = mainAgentProvider === entry.id;
+      if (!key && !isConfiguredMainAgent) continue;
+      apiKey = key ?? "";
+    } else {
+      const creds = await resolveProviderCredentials(entry.id);
+      if (!creds) continue;
+      apiKey = creds.apiKey;
+      baseURL = creds.baseURL;
+      source = creds.source;
+    }
 
-  // Anthropic
-  const anthropicCreds = await resolveProviderCredentials(
-    "anthropic",
-    inferenceMode,
-  );
-  if (anthropicCreds) {
-    const model = resolveModel(config, "anthropic");
-    registerProvider(
-      "anthropic",
-      new RetryProvider(
-        new AnthropicProvider(anthropicCreds.apiKey, model, {
-          useNativeWebSearch,
-          streamTimeoutMs,
-          ...(anthropicCreds.baseURL
-            ? { baseURL: anthropicCreds.baseURL }
-            : {}),
-        }),
-        {
-          forwardUsageAttributionHeaders:
-            anthropicCreds.source === "managed-proxy",
-        },
-      ),
-    );
-    routingSources.set("anthropic", anthropicCreds.source);
-  }
+    const model = resolveModel(config, entry.id);
+    const adapter = buildProviderAdapter(entry.id, {
+      apiKey,
+      model,
+      streamTimeoutMs,
+      baseURL,
+      useNativeWebSearch,
+    });
+    if (!adapter) {
+      // Catalog declares a provider with no factory entry. The parity guard
+      // in adapter-factory.ts catches this at module load, so reaching here
+      // means a future refactor regressed the invariant.
+      log.error(
+        { providerId: entry.id },
+        "Catalog entry has no adapter factory — skipping",
+      );
+      continue;
+    }
 
-  // OpenAI
-  const openaiCreds = await resolveProviderCredentials("openai", inferenceMode);
-  if (openaiCreds) {
-    const model = resolveModel(config, "openai");
     registerProvider(
-      "openai",
-      new RetryProvider(
-        new OpenAIResponsesProvider(openaiCreds.apiKey, model, {
-          useNativeWebSearch,
-          streamTimeoutMs,
-          ...(openaiCreds.baseURL ? { baseURL: openaiCreds.baseURL } : {}),
-        }),
-        {
-          forwardUsageAttributionHeaders:
-            openaiCreds.source === "managed-proxy",
-        },
-      ),
+      entry.id,
+      new RetryProvider(adapter, {
+        forwardUsageAttributionHeaders: source === "managed-proxy",
+      }),
     );
-    routingSources.set("openai", openaiCreds.source);
+    routingSources.set(entry.id, source);
   }
+}
 
-  // Gemini
-  const geminiCreds = await resolveProviderCredentials("gemini", inferenceMode);
-  if (geminiCreds) {
-    const model = resolveModel(config, "gemini");
-    registerProvider(
-      "gemini",
-      new RetryProvider(
-        new GeminiProvider(geminiCreds.apiKey, model, {
-          streamTimeoutMs,
-          ...(geminiCreds.baseURL
-            ? { managedBaseUrl: geminiCreds.baseURL }
-            : {}),
-        }),
-        {
-          forwardUsageAttributionHeaders:
-            geminiCreds.source === "managed-proxy",
-        },
-      ),
-    );
-    routingSources.set("gemini", geminiCreds.source);
-  }
+// ---------------------------------------------------------------------------
+// Per-connection provider resolution (mix-and-match support)
+// ---------------------------------------------------------------------------
 
-  // Ollama (keyless provider — always init when configured or key present)
-  const ollamaKey = await getProviderKeyAsync("ollama");
-  if (config.llm.default.provider === "ollama" || ollamaKey) {
-    const model = resolveModel(config, "ollama");
-    registerProvider(
-      "ollama",
-      new RetryProvider(
-        new OllamaProvider(model, {
-          apiKey: ollamaKey ?? undefined,
-          streamTimeoutMs,
-        }),
-      ),
-    );
-    routingSources.set("ollama", "user-key");
+/**
+ * Resolve a provider instance for a named `provider_connection`.
+ *
+ * Results are cached in `connectionProviders` for the lifetime of the
+ * current `initializeProviders` invocation (cleared on next boot). This
+ * prevents redundant vault reads for repeated calls to the same connection.
+ *
+ * Returns null when:
+ *   - The connection doesn't exist in the DB
+ *   - Auth resolution fails (missing credential, platform unavailable, v2 type)
+ *   - The provider/auth combination yields no usable adapter
+ */
+export async function resolveProviderFromConnection(
+  connection: ProviderConnection,
+  config: ProvidersConfig,
+): Promise<Provider | null> {
+  const cached = connectionProviders.get(connection.name);
+  if (cached) return cached;
+
+  const authResult = await resolveAuth(connection.auth, connection.provider);
+  if (!authResult.ok) {
+    const err = authResult.error;
+    if (err.code === "not_implemented") {
+      log.warn(
+        { connectionName: connection.name, authType: err.authType },
+        `Auth type '${err.authType}' is not yet implemented (v2). ` +
+          "Update the connection to use 'api_key', 'platform', or 'none'.",
+      );
+    } else if (err.code === "credential_not_found") {
+      log.warn(
+        { connectionName: connection.name, credential: err.credential },
+        `Credential '${err.credential}' not found in vault for connection '${connection.name}'.`,
+      );
+    } else {
+      log.warn(
+        { connectionName: connection.name },
+        `Platform auth unavailable for connection '${connection.name}'.`,
+      );
+    }
+    return null;
   }
 
-  // Fireworks
-  const fireworksKey = await getProviderKeyAsync("fireworks");
-  if (fireworksKey) {
-    const model = resolveModel(config, "fireworks");
-    registerProvider(
-      "fireworks",
-      new RetryProvider(
-        new FireworksProvider(fireworksKey, model, {
-          streamTimeoutMs,
-        }),
-      ),
-    );
-    routingSources.set("fireworks", "user-key");
-  }
+  const streamTimeoutMs =
+    (config.timeouts?.providerStreamTimeoutSec ?? 1800) * 1000;
+  const useNativeWebSearch =
+    config.services["web-search"].provider === "inference-provider-native";
+  const model = resolveModel(config, connection.provider);
 
-  // OpenRouter
-  const openrouterKey = await getProviderKeyAsync("openrouter");
-  if (openrouterKey) {
-    const model = resolveModel(config, "openrouter");
-    registerProvider(
-      "openrouter",
-      new RetryProvider(
-        new OpenRouterProvider(openrouterKey, model, {
-          useNativeWebSearch,
-          streamTimeoutMs,
-        }),
-      ),
-    );
-    routingSources.set("openrouter", "user-key");
+  const provider = createAdapterFromConnection(connection, authResult.resolved, {
+    model,
+    streamTimeoutMs,
+    useNativeWebSearch,
+  });
+
+  if (provider) {
+    connectionProviders.set(connection.name, provider);
   }
+
+  return provider;
+}
+
+/** Clear per-connection provider cache (called by initializeProviders on boot). */
+export function clearConnectionProviderCache(): void {
+  connectionProviders.clear();
 }

package/src/providers/retry.ts

@@ -205,16 +205,8 @@ function normalizeSendMessageOptions(
     ) {
       nextConfig.temperature = resolved.temperature;
     }
-    if (nextConfig.thinking === undefined) {
-      // Convert the schema-shape `{ enabled, streamThinking }` into Anthropic's
-      // discriminated wire-format (`{ type: "adaptive" | "disabled" }`).
-      // Without this conversion, `thinking` arrives at `AnthropicProvider`
-      // with a shape the SDK doesn't accept (`ThinkingConfigParam` requires
-      // a `type` discriminator).
-      const thinking = normalizeThinkingConfigForWire(resolved.thinking);
-      if (thinking !== undefined) {
-        nextConfig.thinking = thinking;
-      }
+    if (nextConfig.thinking === undefined && resolved.thinking !== undefined) {
+      nextConfig.thinking = resolved.thinking;
     }
     // Forward OpenRouter-only routing preferences so `OpenRouterProvider` can
     // translate `openrouter.only` into the wire-format `provider: { only: [...] }`
@@ -236,6 +228,22 @@ function normalizeSendMessageOptions(
     // "Extra inputs are not permitted".
   }
 
+  // Convert schema-shape `{ enabled, streamThinking }` into Anthropic's
+  // discriminated wire-format (`{ type: "adaptive" | "disabled" }`).
+  // `AnthropicProvider`'s SDK requires a `type` discriminator, and downstream
+  // forced-tool/temperature conflict checks compare against the wire shape.
+  // Applies to both the resolver path above and pass-through callers (e.g.
+  // `host.providers.llm.complete`) that supply `thinking` directly without a
+  // `callSite`.
+  if (nextConfig.thinking !== undefined) {
+    const normalized = normalizeThinkingConfigForWire(nextConfig.thinking);
+    if (normalized === undefined) {
+      delete nextConfig.thinking;
+    } else {
+      nextConfig.thinking = normalized;
+    }
+  }
+
   // thinking is Anthropic-specific on the wire; OpenRouter reads it as a
   // signal for its unified reasoning parameter. Strip it for other providers.
   if (

package/src/providers/search-provider-catalog.ts

@@ -0,0 +1,121 @@
+/**
+ * Canonical catalog of built-in web-search providers.
+ *
+ * This is the single source of truth that drives:
+ *
+ *   1. The config-schema enum (`VALID_WEB_SEARCH_PROVIDERS` in
+ *      `assistant/src/config/schemas/services.ts`).
+ *   2. The search-provider env-var map (`SEARCH_PROVIDER_ENV_VAR_NAMES`
+ *      in `provider-env-vars.ts`).
+ *   3. The API-key provider set (`SEARCH_API_KEY_PROVIDERS` in
+ *      `provider-secret-catalog.ts`).
+ *   4. (Indirect, via `meta/web-search-provider-catalog.json` generated by
+ *      `assistant/scripts/sync-web-search-catalog.ts`) the CLI mirror in
+ *      `cli/src/shared/provider-env-vars.ts` and the web vendored catalog
+ *      in `vellum-assistant-platform`.
+ *
+ * Mirrors the pattern from `model-catalog.ts` (Provider Expansion Phase 3
+ * for LLM providers). When introducing a new built-in web-search provider,
+ * the daemon-side changes collapse to:
+ *
+ *   1. Add a new executor in `tools/network/web-search.ts`.
+ *   2. Register an adapter in the `WEB_SEARCH_ADAPTERS` table.
+ *   3. Add an entry to this catalog.
+ *   4. Run `bun run sync:web-search-catalog` to regenerate
+ *      `meta/web-search-provider-catalog.json`.
+ *
+ * The split between adapter (which carries the executor) and catalog (which
+ * carries metadata) keeps the catalog purely declarative — adding an entry
+ * never forces a code rebuild downstream and the JSON projection stays
+ * trivial.
+ */
+
+export type SearchProviderKind = "managed" | "byok";
+
+export interface SearchProviderCatalogEntry {
+  /** Stable provider identifier. Matches config + secret-catalog values. */
+  readonly id: string;
+  /** Short display name used by picker UIs. */
+  readonly displayName: string;
+  /**
+   * Optional long display name for prose contexts (marketing docs,
+   * privacy notices). Defaults to {@link displayName} when omitted.
+   */
+  readonly displayNameLong?: string;
+  /** Authentication style. `managed` providers are routed through the
+   *  inference provider; `byok` providers require a user-supplied key. */
+  readonly kind: SearchProviderKind;
+  /** Placeholder shown in the API-key input. BYOK providers only. */
+  readonly apiKeyPrefix?: string;
+  /** Environment variable name carrying the API key. BYOK providers only. */
+  readonly envVar?: string;
+  /** Secret-catalog key (the bare provider name accepted by
+   *  `getProviderKeyAsync`). BYOK providers only. */
+  readonly secretKey?: string;
+  /** Position in the daemon fallback chain (lower = earlier). BYOK only. */
+  readonly fallbackOrder?: number;
+  /** Privacy-policy URL surfaced in marketing data-sharing docs.
+   *  BYOK providers only. */
+  readonly privacyPolicyUrl?: string;
+}
+
+export const SEARCH_PROVIDER_CATALOG: readonly SearchProviderCatalogEntry[] = [
+  {
+    id: "inference-provider-native",
+    displayName: "Provider Native",
+    kind: "managed",
+  },
+  {
+    id: "perplexity",
+    displayName: "Perplexity",
+    kind: "byok",
+    apiKeyPrefix: "pplx-...",
+    envVar: "PERPLEXITY_API_KEY",
+    secretKey: "perplexity",
+    fallbackOrder: 1,
+    privacyPolicyUrl: "https://www.perplexity.ai/hub/legal/privacy-policy",
+  },
+  {
+    id: "brave",
+    displayName: "Brave",
+    displayNameLong: "Brave Search",
+    kind: "byok",
+    apiKeyPrefix: "BSA...",
+    envVar: "BRAVE_API_KEY",
+    secretKey: "brave",
+    fallbackOrder: 2,
+    privacyPolicyUrl: "https://search.brave.com/help/privacy-policy",
+  },
+  {
+    id: "tavily",
+    displayName: "Tavily",
+    kind: "byok",
+    apiKeyPrefix: "tvly-...",
+    envVar: "TAVILY_API_KEY",
+    secretKey: "tavily",
+    fallbackOrder: 3,
+    privacyPolicyUrl: "https://tavily.com/privacy",
+  },
+];
+
+/** Provider ids accepted by the web-search config schema. */
+export const SEARCH_PROVIDER_IDS: readonly string[] = SEARCH_PROVIDER_CATALOG.map(
+  (p) => p.id,
+);
+
+/** Catalog entries that store an API key under their bare provider name. */
+export const BYOK_SEARCH_PROVIDERS: readonly SearchProviderCatalogEntry[] =
+  SEARCH_PROVIDER_CATALOG.filter((p) => p.kind === "byok");
+
+/** BYOK provider ids, ordered by `fallbackOrder` (ascending). */
+export const SEARCH_PROVIDER_FALLBACK_ORDER: readonly string[] = BYOK_SEARCH_PROVIDERS
+  .slice()
+  .sort((a, b) => (a.fallbackOrder ?? 0) - (b.fallbackOrder ?? 0))
+  .map((p) => p.id);
+
+/** Look up a single catalog entry by id. Returns `undefined` if unknown. */
+export function getSearchProvider(
+  id: string,
+): SearchProviderCatalogEntry | undefined {
+  return SEARCH_PROVIDER_CATALOG.find((p) => p.id === id);
+}

package/src/runtime/AGENTS.md

@@ -12,6 +12,10 @@ The single HTTP send endpoint is `POST /v1/messages`. Key behaviors:
 
 Do NOT add new send endpoints. All message ingress should go through `POST /v1/messages` (HTTP).
 
+### SSE backpressure shedding must be observable
+
+SSE handlers built on `ReadableStream` shed slow subscribers when `controller.desiredSize <= 0` to keep daemon memory bounded. Every shed site must emit a log line + Sentry capture so the daemon-side shed can be time-correlated with the client-side idle watchdog (otherwise stalls are invisible from both sides). See [WHATWG Streams — Backpressure](https://streams.spec.whatwg.org/#pipe-chains) and [Node `monitorEventLoopDelay`](https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions).
+
 ### GET handler idempotency
 
 GET handlers must be safe and side-effect-free — they must not enqueue background jobs, mutate database state, or trigger writes. If a feature needs server-initiated work in response to a client request, use an explicit POST endpoint or a push-based flow (SSE event → client refetch). See [RFC 9110 §9.2.1 — Safe Methods](https://httpwg.org/specs/rfc9110.html#safe.methods).
@@ -65,6 +69,15 @@ Host browser allows the assistant to proxy CDP (Chrome DevTools Protocol) JSON-R
   - `POST /v1/host-browser-result` — `{ requestId, content, isError }`
 - **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_browser"`. Registration happens in `conversation-routes.ts` and the route handler is in `host-browser-routes.ts`.
 
+### Host app-control (desktop proxy native-app control)
+
+Host app-control allows the assistant to proxy app-control actions (target a specific application by bundle ID or process name, capture window screenshots, drive UI) to the desktop host via the client, following the same pattern as host bash, host file, host CU, and host browser. App-control sessions are per-conversation, so the proxy reference lives on `Conversation.hostAppControlProxy` rather than as a singleton.
+
+- **Discovery**: Clients discover pending host app-control requests via SSE events (`host_app_control_request`) which include a `requestId`.
+- **Resolution**: Clients execute the app-control action on the host and respond via:
+  - `POST /v1/host-app-control-result` — `{ requestId, state, pngBase64?, windowBounds?, executionResult?, executionError? }`. `state` is one of `"running" | "missing" | "minimized"`.
+- **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_app_control"`. The route handler is in `host-app-control-routes.ts` and forwards the payload to the owning conversation's `hostAppControlProxy.resolve()`. Late delivery is tolerated — the route returns 200 even when no pending interaction matches (e.g. the conversation was disposed before the client reported back).
+
 ### `chrome-extension` interface (Phase 2)
 
 The `chrome-extension` interface in `INTERFACE_IDS` is a non-interactive transport that supports only the `host_browser` capability — it does NOT support `host_bash`, `host_file`, or `host_cu`. This is encoded in `supportsHostProxy(id, capability)`: passing a capability argument returns `true` for `chrome-extension` only when the capability is `host_browser`; the no-arg form returns `false` for `chrome-extension` (so legacy desktop-only call sites that assume full-desktop proxy availability continue to gate correctly).
@@ -83,11 +96,11 @@ See `docs/browser-use-architecture-phase2.md` for the full wire diagram and comp
 
 On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts`) evaluates three browser backends in strict priority order. Each candidate is tried lazily; if the first command fails with a transport-level error, the factory falls over to the next candidate. CDP protocol errors (the browser understood the command but rejected it) do NOT trigger failover.
 
-| Priority | Backend                    | Condition                                                                                                                                                                                                | Transport                                                                                              |
-| -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned. On other interfaces, requires an active hub subscriber with `host_browser` capability | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` with `targetCapability: "host_browser"` (cloud extension or macOS) |
-| 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active      | Direct CDP WebSocket to `localhost:9222`                                                               |
-| 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                     | In-process Playwright CDP via `browserManager`                                                         |
+| Priority | Backend                    | Condition                                                                                                                                                                                           | Transport                                                                                                                                      |
+| -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned. On other interfaces, requires an active hub subscriber with `host_browser` capability     | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` with `targetCapability: "host_browser"` (cloud extension or macOS) |
+| 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active | Direct CDP WebSocket to `localhost:9222`                                                                                                       |
+| 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                | In-process Playwright CDP via `browserManager`                                                                                                 |
 
 **Transport selection for the extension/host-proxy backend:**