@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/providers/speech-to-text/provider-catalog.ts

@@ -14,6 +14,7 @@ import type {
   ConversationStreamingMode,
   SttBoundaryId,
   SttProviderId,
+  SttTurnDetectionMode,
   TelephonySttMode,
 } from "../../stt/types.js";
 import { baseLanguageSubtag } from "../../util/language-subtag.js";
@@ -87,6 +88,14 @@ interface SttProviderEntry {
    */
   readonly conversationStreamingMode: ConversationStreamingMode;
 
+  /**
+   * Whether the provider decides end-of-turn itself, in-band with the audio
+   * it transcribes, or leaves the boundary to the session's local silence
+   * timer. A live-voice session reads this to decide whether to arm its
+   * provider turn-end path; it never names a provider directly.
+   */
+  readonly turnDetection: SttTurnDetectionMode;
+
   /**
    * Whether the provider can attribute transcribed speech to distinct
    * speakers (speaker diarization). When `true`, callers may opt in to
@@ -105,8 +114,9 @@ interface SttProviderEntry {
    *
    * - `"manual"`: the provider accepts an explicit language parameter and
    *   defaults to English when omitted; a language picker is meaningful.
-   * - `"auto"`: the provider detects language natively and accepts no
-   *   language parameter; a picker would be a no-op, so clients must hide it.
+   * - `"auto"`: the provider takes no language parameter, either because it
+   *   detects the language natively or because its model is monolingual; a
+   *   picker would be a no-op, so clients must hide it.
    */
   readonly languageSelection: "manual" | "auto";
 
@@ -118,6 +128,17 @@ interface SttProviderEntry {
 // Catalog data
 // ---------------------------------------------------------------------------
 
+/**
+ * Shared by every provider that authenticates against a Deepgram account.
+ * The key is the same one, so the instructions must not drift apart.
+ */
+const DEEPGRAM_CREDENTIALS_GUIDE: SttCredentialsGuide = {
+  description:
+    "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
+  url: "https://console.deepgram.com/",
+  linkLabel: "Open Deepgram Console",
+};
+
 /**
  * Provider catalog entries, keyed by provider ID.
  *
@@ -147,14 +168,41 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "realtime-ws",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: true,
       languageSelection: "manual",
-      credentialsGuide: {
-        description:
-          "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
-        url: "https://console.deepgram.com/",
-        linkLabel: "Open Deepgram Console",
-      },
+      credentialsGuide: DEEPGRAM_CREDENTIALS_GUIDE,
+    },
+  ],
+  [
+    "deepgram-flux",
+    {
+      id: "deepgram-flux",
+      displayName: "Deepgram Flux",
+      subtitle:
+        "Conversational speech-to-text with model-native turn detection. Uses your Deepgram API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your Deepgram API key. Flux shares the same key as Deepgram.",
+      // Shared with the `deepgram` provider: Flux is a model on the same
+      // account, not a separate credential.
+      credentialProvider: "deepgram",
+      // Streaming only: Flux has no batch endpoint.
+      supportedBoundaries: new Set<SttBoundaryId>(["daemon-streaming"]),
+      // Telephony is out of scope for the spike. Nothing reroutes a call to
+      // another provider, so a Flux-configured assistant does not transcribe
+      // calls at all.
+      telephonyMode: "none",
+      conversationStreamingMode: "realtime-ws",
+      // Flux emits turn lifecycle events on its transcript stream and numbers
+      // them, so a live-voice session may let them commit the turn.
+      turnDetection: "provider",
+      supportsDiarization: false,
+      // "no picker", not native detection: the Flux model is English-only and
+      // takes no language parameter, so audio in another language transcribes
+      // as English rather than being detected.
+      languageSelection: "auto",
+      credentialsGuide: DEEPGRAM_CREDENTIALS_GUIDE,
     },
   ],
   [
@@ -174,6 +222,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: false,
       languageSelection: "auto",
       credentialsGuide: {
@@ -200,6 +249,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "incremental-batch",
+      turnDetection: "none",
       supportsDiarization: false,
       languageSelection: "auto",
       credentialsGuide: {
@@ -226,6 +276,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "realtime-ws",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: false,
       // The relay dials Deepgram nova-3 server-side, which takes an explicit
       // language parameter.
@@ -248,6 +299,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: true,
       languageSelection: "manual",
       credentialsGuide: {
@@ -342,6 +394,32 @@ export function supportsBoundary(
   return CATALOG.get(id)?.supportedBoundaries.has(boundary) ?? false;
 }
 
+/**
+ * Message explaining why a provider cannot serve the `daemon-batch` boundary.
+ *
+ * Streaming-only providers are selected through the same
+ * `services.stt.provider` key as batch-capable ones, so a batch caller that
+ * reports only "nothing is configured" points the operator at the wrong
+ * problem. This names the provider and, where one exists, the batch-capable
+ * provider on the same credential, so acting on it needs no catalog reading.
+ */
+export function batchBoundaryGapReason(id: SttProviderId): string {
+  const entry = CATALOG.get(id);
+  const label = entry?.displayName ?? id;
+  const alternative = entry
+    ? [...CATALOG.values()].find(
+        (candidate) =>
+          candidate.id !== entry.id &&
+          candidate.credentialProvider === entry.credentialProvider &&
+          candidate.supportedBoundaries.has("daemon-batch"),
+      )
+    : undefined;
+  const remedy = alternative
+    ? `Batch transcription requires the ${alternative.id} provider: set services.stt.provider to "${alternative.id}".`
+    : "Set services.stt.provider to a provider that supports batch transcription.";
+  return `${label} is streaming-only. ${remedy}`;
+}
+
 /**
  * Check whether a provider supports speaker diarization.
  *
@@ -353,6 +431,19 @@ export function supportsDiarization(id: SttProviderId): boolean {
   return CATALOG.get(id)?.supportsDiarization ?? false;
 }
 
+/**
+ * Check whether a provider decides end-of-turn itself.
+ *
+ * Returns `false` for unknown provider IDs, which keeps an unrecognized
+ * provider on the local silence boundary rather than waiting for turn events
+ * that will never arrive. A live-voice session reads this instead of naming a
+ * provider, so a new turn-detecting provider is a catalog entry rather than a
+ * session change.
+ */
+export function supportsProviderTurnDetection(id: SttProviderId): boolean {
+  return CATALOG.get(id)?.turnDetection === "provider";
+}
+
 /**
  * Return all canonical provider IDs in deterministic (insertion) order.
  */

package/src/providers/speech-to-text/resolve.ts

@@ -6,8 +6,10 @@ import type {
   StreamingTranscriber,
   SttProviderId,
 } from "../../stt/types.js";
+import { SttError } from "../../stt/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
+  batchBoundaryGapReason,
   getCredentialProvider,
   getProviderEntry,
   supportsBoundary,
@@ -88,8 +90,13 @@ export function effectiveSttLanguage(
  *
  * Returns `null` when:
  * - The configured provider is not in the catalog.
- * - The configured provider doesn't support the `daemon-batch` boundary.
  * - No credentials are configured for the resolved provider.
+ *
+ * Throws an {@link SttError} when the configured provider is in the catalog
+ * but has no `daemon-batch` boundary. That is a configuration mismatch the
+ * resolver can name, and returning `null` for it would reach the user as the
+ * "no speech-to-text provider is configured" copy every caller pairs with
+ * `null`, which is the opposite of what happened.
  */
 export async function resolveBatchTranscriber(): Promise<BatchTranscriber | null> {
   // Snapshot the stt config once, before any await, so a concurrent config
@@ -111,7 +118,9 @@ export async function resolveBatchTranscriber(): Promise<BatchTranscriber | null
 
   // Verify the provider supports the daemon-batch boundary.
   if (!supportsBoundary(provider as SttProviderId, "daemon-batch")) {
-    return null;
+    const reason = batchBoundaryGapReason(provider as SttProviderId);
+    log.warn({ providerId: provider }, reason);
+    throw new SttError("provider-error", reason, { userFacing: true });
   }
 
   if (provider === "vellum") {
@@ -632,6 +641,20 @@ async function createStreamingTranscriber(
           : {}),
       });
     }
+    case "deepgram-flux": {
+      // Flux is streaming-only and dials Deepgram's /v2/listen conversational
+      // endpoint. Turn-detection tuning comes from `liveVoice.flux`, which
+      // the adapter reads itself, so only the transport-level sample rate is
+      // passed here. No language is forwarded: the spike pins the
+      // English-only `flux-general-en`, and `language_hint` means nothing to
+      // a monolingual model. Diarization is off in the catalog, so a
+      // `"required"` caller never reaches this case.
+      const { DeepgramFluxRealtimeTranscriber } =
+        await import("./deepgram-flux-realtime.js");
+      return new DeepgramFluxRealtimeTranscriber(apiKey, {
+        sampleRate: options.sampleRate,
+      });
+    }
     default: {
       const _exhaustive: never = providerId;
       return null;

package/src/routes/control.ts

@@ -68,6 +68,7 @@ export async function spawnRouteHostWorkerProcess(
     return await spawnWorkerProcess({
       pidPath: routeHostPidPath(),
       entry: new URL("./worker.ts", import.meta.url),
+      packagedEntry: "routes",
       workerLabel: "Route host",
       options: opts,
     });

package/src/routes/route-host-client.ts

@@ -149,6 +149,7 @@ export class RouteHostClient {
       ({ pid } = await spawnWorkerProcess({
         pidPath: this.pidPath,
         entry: this.workerEntryUrl,
+        packagedEntry: "routes",
         workerLabel: "Route host",
         // Owned by the daemon (appears in its process tree, torn down with it);
         // kill it if it hangs during startup so a failed spawn leaves nothing.

package/src/routes/route-host-protocol.ts

@@ -33,6 +33,13 @@ export interface RouteInvokeParams {
   readonly url: string;
   /** Request header entries as `[name, value]` pairs (preserves duplicates). */
   readonly headers: ReadonlyArray<readonly [string, string]>;
+  /**
+   * Manifest name of the plugin whose namespace the route falls in, absent for
+   * a workspace route. The host marks it as the plugin in context for the
+   * handler's execution, so plugin-scoped host APIs behave the same whether the
+   * handler runs in the host or in-thread on the daemon.
+   */
+  readonly pluginName?: string;
 }
 
 /**

package/src/routes/worker.ts

@@ -24,7 +24,13 @@ import { createServer, type Server, type Socket } from "node:net";
 import type { IpcEnvelope } from "@vellumai/ipc-server-utils";
 import { IpcFrameReader, writeMessage } from "@vellumai/ipc-server-utils";
 
+import { runInPluginContext } from "../plugins/plugin-execution-context.js";
 import { disableStreamSeqStamping } from "../runtime/assistant-stream-state.js";
+import {
+  evictRouteSourceTree,
+  importRouteModule,
+  sourceRootForHandler,
+} from "../runtime/routes/user-route-import.js";
 import { getLogger } from "../util/logger.js";
 import {
   ensureProcDir,
@@ -43,6 +49,9 @@ import {
 
 const log = getLogger("route-host");
 
+/** Last entry-file mtime imported in this process, keyed by handler path. */
+const lastHandlerMtime = new Map<string, number>();
+
 const socketPath = getProcSocketPath(ROUTE_HOST_PROC_NAME);
 const pidPath = getProcPidPath(ROUTE_HOST_PROC_NAME);
 
@@ -110,30 +119,54 @@ async function handleInvoke(
   params: RouteInvokeParams,
   body: Uint8Array | undefined,
 ): Promise<void> {
-  // Each worker has its own module cache; cache-bust per mtime so an edited
-  // handler is re-imported.
-  const mod = (await import(
-    `${params.filePath}?t=${params.mtimeMs}`
-  )) as Record<string, unknown>;
-
-  const handler = mod[params.method];
-  if (typeof handler !== "function") {
-    const allowed = HTTP_METHODS.filter((m) => typeof mod[m] === "function");
+  // Each worker has its own module cache. When the entry file's mtime
+  // moves, evict the whole source tree so a new handler cannot bind to a
+  // stale helper, then re-import.
+  const lastMtime = lastHandlerMtime.get(params.filePath);
+  if (lastMtime !== params.mtimeMs) {
+    evictRouteSourceTree(sourceRootForHandler(params.filePath));
+    lastHandlerMtime.set(params.filePath, params.mtimeMs);
+  }
+
+  // A plugin's own routes execute as that plugin, matching the daemon's
+  // in-thread path, so plugin-scoped host APIs a handler reaches
+  // (`resolveCredential`, `indexDocument`) scope to the owning plugin rather
+  // than falling through to their unscoped branch. The context covers the
+  // import as well as the call: a route module can reach a scoped API at
+  // evaluation time, and it is imported once per mtime.
+  const serve = async (): Promise<
+    { ok: true; response: Response } | { ok: false; allowed: string[] }
+  > => {
+    const mod = await importRouteModule(params.filePath);
+    const handler = mod[params.method];
+    if (typeof handler !== "function") {
+      return {
+        ok: false,
+        allowed: HTTP_METHODS.filter((m) => typeof mod[m] === "function"),
+      };
+    }
+    const request = reconstructRequest(params, body);
+    const response = (await (handler as (req: Request) => unknown)(
+      request,
+    )) as Response;
+    return { ok: true, response };
+  };
+  const outcome = await (params.pluginName
+    ? runInPluginContext(params.pluginName, serve)
+    : serve());
+
+  if (!outcome.ok) {
     replyResult(
       socket,
       id,
       405,
-      allowed.length ? [["allow", allowed.join(", ")]] : [],
+      outcome.allowed.length ? [["allow", outcome.allowed.join(", ")]] : [],
       null,
     );
     return;
   }
 
-  const request = reconstructRequest(params, body);
-  const response = (await (handler as (req: Request) => unknown)(
-    request,
-  )) as Response;
-
+  const { response } = outcome;
   const buffer = new Uint8Array(await response.arrayBuffer());
   const headers: [string, string][] = [];
   response.headers.forEach((value, name) => {

package/src/runtime/AGENTS.md

@@ -93,39 +93,38 @@ Host app-control allows the assistant to proxy app-control actions (target a spe
   - `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)
+### `chrome-extension` interface
 
 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).
 
-For **self-hosted** deployments, `host_browser_request` frames are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches. For **cloud/platform-hosted** deployments, the chrome extension connects via SSE (`GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`) and `host_browser_request` frames travel through `assistantEventHub` to the SSE stream. The extension POSTs results back to `POST /v1/host-browser-result`. Transport selection is handled by `HostBrowserProxy`, which publishes events to the `assistantEventHub` with `targetCapability: "host_browser"` — the hub delivers to whichever subscriber (chrome-extension or macOS client) has the `host_browser` capability. For macOS, `host_browser_request` frames travel through `assistantEventHub` (SSE) by default; when the guardian also has an active extension connection, the registry-routed WebSocket sender takes precedence.
+The extension reaches the daemon over the same two doors every client uses. Self-hosted, it pairs once through the gateway's `POST /v1/pair` (`gateway/src/http/routes/pair.ts`: loopback-only, rate-limited, mints an `actor_client_v1` JWT for the `X-Vellum-Interface-Id: chrome-extension` caller); cloud deployments issue the guardian-bound JWT through the gateway's WorkOS-backed flow. It then subscribes to `GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`, which registers it on `assistantEventHub` with the single `host_browser` capability, and it answers work by POSTing to `POST /v1/host-browser-result`.
 
-A single guardian may have multiple parallel extension installs connected at once (two Chrome profiles, two desktops sharing a sync identity). Each install generates a stable `clientInstanceId` on first run, persists it in `chrome.storage.local`, and sends it on every WebSocket handshake as a query param (`clientInstanceId=...`) or header (`x-client-instance-id`). The registry keys inner entries by that id so sibling installs don't evict each other on register/unregister. The default `send(guardianId, msg)` path routes to whichever instance has the most recent activity (`lastActiveAt`); `sendToInstance(guardianId, clientInstanceId, msg)` pins a specific install. Older extension builds that omit the id get a connection-scoped `legacy:<connectionId>` fallback key so they degrade gracefully to single-instance semantics.
+`HostBrowserProxy` (`daemon/host-browser-proxy.ts`, a lazily-created singleton) is the only sender: it publishes `host_browser_request` frames to the hub with `targetCapability: "host_browser"` and an explicit target client, choosing that client at send time from the hub's live roster (`resolveTargetClient`). Both the extension and the macOS desktop bridge register `host_browser`, so ordering is method-aware rather than pure recency: `Vellum.*` pseudo-methods (tabs, attach, detach) go only to a chrome-extension client, the only transport that implements them; raw CDP methods prefer a chrome-extension client over the macOS bridge, most recently active first within each group; an explicit `targetClientId` pins one client; and when a `sourceActorPrincipalId` is supplied only that actor's clients are eligible. Several extension installs for one guardian are simply several `host_browser` clients on the roster. A dispatch that lands during a brief MV3 service-worker reconnect waits up to `EXTENSION_RECONNECT_GRACE_MS` before failing.
 
-`Conversation.hostBrowserSenderOverride` is the integration point between the turn layer and the proxy. When any turn enters the routes layer and the guardian has an active extension connection in the `ChromeExtensionRegistry`, `conversation-routes.ts` resolves the registry entry and sets the override to a sender that writes to that WebSocket. This applies to chrome-extension turns (where the registry is the only transport) and macOS turns (where the extension connection lets browser tools route through the user's real Chrome session instead of cdp-inspect/local). `Conversation.restoreBrowserProxyAvailability()` re-threads the override on queue drain — without this, the drain path would clobber the registry-routed sender with the default `sendToClient` (pointed at the SSE hub) and `host_browser_request` frames would stop reaching the extension mid-queue.
+Nothing in the turn layer wires the proxy: it reads the roster on every send, and the conversation's own event sink is fixed for its life (see `assistant/AGENTS.md`, "Conversation event delivery and turn presence"), so a queued or drained turn reaches the extension exactly like a live one.
 
-Capability token bootstrap for self-hosted deployments is handled by the gateway (`gateway/src/http/routes/browser-extension-pair.ts`) which mints a guardian-bound HMAC capability token. The daemon delegates token verification to the gateway via IPC (`verify_capability_token`) — it must never read secrets from `GATEWAY_SECURITY_DIR` or any other gateway-owned directory. Cloud deployments issue guardian-bound JWTs via the gateway's WorkOS-backed flow.
-
-See `docs/browser-use-architecture-phase2.md` for the full wire diagram and component inventory.
+See `docs/browser-use-architecture-phase2.md` for the backend scenarios and the manual QA checklist.
 
 ### Canonical browser backend precedence (macOS)
 
 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** | Two candidates from the always-present `HostBrowserProxy` singleton: `extension` when `hasExtensionClient(actor)` finds a chrome-extension client on the hub; otherwise `host-bridge` when `isAvailable(actor)` finds any `host_browser` client (the macOS desktop bridge) and that actor's host-bridge cooldown is not active | SSE via `assistantEventHub` with `targetCapability: "host_browser"`, to the chosen client |
+| 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:**
 
-The "extension" backend label is a misnomer inherited from the original Phase 2 design where only the Chrome Extension provided host-browser access. In the current architecture, two transports can power this backend:
+The "extension" backend label predates the macOS bridge; two SSE transports power it, both through the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline:
+
+- **Chrome extension**: `HostBrowserProxy.send()` publishes to `assistantEventHub` with `targetCapability: "host_browser"`, targeting the chrome-extension client `resolveTargetClient` chose (see the interface section above); the extension executes the CDP command via `chrome.debugger` and POSTs the result to `/v1/host-browser-result`.
+- **macOS SSE bridge**: when no chrome-extension client is eligible, the same publish targets the macOS subscriber (which registers every host-proxy capability); the desktop client executes the command against the local Chrome and POSTs the result the same way.
 
-- **Extension WebSocket** (self-hosted): When the `ChromeExtensionRegistry` has an active entry for the guardian, the registry-routed sender delivers frames over the `/v1/browser-relay` WebSocket to the Chrome extension, which executes CDP commands via `chrome.debugger`.
-- **Extension SSE** (cloud/platform): When no WebSocket entry exists, `HostBrowserProxy.send()` publishes to `assistantEventHub` with `targetCapability: "host_browser"`. The hub delivers the event to the chrome-extension subscriber (which registered with that capability via SSE). The extension POSTs results back to `/v1/host-browser-result`. This path is used for any `canServiceSseBrowser()` interface (`web`, `chrome-extension`, `macos`).
-- **macOS SSE bridge**: When the macOS desktop client is connected but no extension is present, the same hub publish with `targetCapability: "host_browser"` delivers to the macOS subscriber (which has all host-proxy capabilities). The desktop client executes CDP commands against the local Chrome and POSTs results back to `/v1/host-browser-result`.
+In the CDP factory the bridge is the internal `"host-bridge"` candidate kind (`InternalBrowserMode`, never a caller-pinnable `browser_mode`). `browser_status` labels the extension path `details.transport: "extension-ws"`; the label predates the SSE transport and is kept as-is.
 
-All three transports use the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline. The `browser_status` output distinguishes the transport via the `details.transport` field: `"extension-ws"` or `"macos-sse"`.
+**Host-bridge cooldown:** a `host-bridge` transport failure records a per-actor cooldown (`recordHostBridgeCooldown`, keyed by `sourceActorPrincipalId`, `__default__` when unresolved) for the same `desktopAuto.cooldownMs` window; while it is active the factory skips the bridge candidate (log `CDP factory: host-bridge skipped (cooldown active)`) and the turn drops straight to cdp-inspect/local. Per-actor because on a multi-actor cloud daemon the bridge reaches a different desktop per actor, so one actor's missing debug port must not suppress another's only route to their Chrome. Never applies to the `extension` candidate.
 
 **Fallback criteria for cdp-inspect (desktop-auto):**
 

package/src/runtime/access-request-helper.ts

@@ -29,6 +29,7 @@ import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.j
 import { IntegrityError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { resolveAnchoredGuardian } from "./anchored-guardian.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
 import { CHALLENGE_TTL_MS } from "./channel-verification-service.js";
 import {
   type AccessRequestTrigger,
@@ -46,7 +47,6 @@ const log = getLogger("access-request-helper");
 export type { AccessRequestTrigger } from "./introduction-policy.js";
 
 export interface AccessRequestParams {
-  canonicalAssistantId: string;
   sourceChannel: ChannelId;
   conversationExternalId: string;
   actorExternalId?: string;
@@ -93,15 +93,18 @@ export type AccessRequestResult =
 // ---------------------------------------------------------------------------
 
 /**
- * Assistant-scoped conversation id for an actor's access requests. Stable key
- * that dedupes pending prompts for the same (assistant, channel, actor).
+ * Conversation id for an actor's access requests. Stable key that dedupes
+ * pending prompts for the same (channel, actor).
+ *
+ * The `self` segment is part of a persisted id format: guardian request rows
+ * carry these ids, so the shape is fixed even though the daemon scopes all its
+ * storage to the one assistant (`DAEMON_INTERNAL_ASSISTANT_ID`).
  */
 export function accessRequestConversationId(
-  canonicalAssistantId: string,
   sourceChannel: string,
   actorExternalId: string,
 ): string {
-  return `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}`;
+  return `access-req-${DAEMON_INTERNAL_ASSISTANT_ID}-${sourceChannel}-${actorExternalId}`;
 }
 
 /**
@@ -126,7 +129,6 @@ export function accessRequestConversationId(
  * fail-closed.
  */
 export async function isApprovalHandshakeInProgress(params: {
-  canonicalAssistantId: string;
   sourceChannel: string;
   actorExternalId: string;
 }): Promise<boolean> {
@@ -134,7 +136,6 @@ export async function isApprovalHandshakeInProgress(params: {
     return false;
   }
   const conversationId = accessRequestConversationId(
-    params.canonicalAssistantId,
     params.sourceChannel,
     params.actorExternalId,
   );
@@ -171,7 +172,6 @@ export async function notifyGuardianOfAccessRequest(
   params: AccessRequestParams,
 ): Promise<AccessRequestResult> {
   const {
-    canonicalAssistantId,
     sourceChannel,
     conversationExternalId,
     actorExternalId,
@@ -219,7 +219,6 @@ export async function notifyGuardianOfAccessRequest(
   // from assistant A could be returned for assistant B, allowing the caller
   // to piggyback on A's guardian approval.
   const conversationId = accessRequestConversationId(
-    canonicalAssistantId,
     sourceChannel,
     actorExternalId,
   );
@@ -270,7 +269,6 @@ export async function notifyGuardianOfAccessRequest(
   // re-prompting is allowed again.
   if (
     await isApprovalHandshakeInProgress({
-      canonicalAssistantId,
       sourceChannel,
       actorExternalId,
     })
@@ -283,7 +281,7 @@ export async function notifyGuardianOfAccessRequest(
   }
 
   const senderIdentifier = actorDisplayName || actorUsername || actorExternalId;
-  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}-${Date.now()}`;
+  const requestId = `access-req-${DAEMON_INTERNAL_ASSISTANT_ID}-${sourceChannel}-${actorExternalId}-${Date.now()}`;
 
   // Access requests are decisionable: without a bound principal nobody could
   // ever decide them (mirrors the gateway create's integrity guard).
@@ -461,7 +459,6 @@ export async function maybeNotifyGuardianOfAdmittedContact(
   }
 
   const conversationId = accessRequestConversationId(
-    params.canonicalAssistantId,
     params.sourceChannel,
     params.actorExternalId,
   );

package/src/runtime/agent-wake.ts

@@ -360,7 +360,7 @@ export interface WakeOptions {
    * the conversation belongs to. Used by fork-based memory retrospectives to
    * render the SOURCE conversation's persona sections — both for review
    * quality and for byte-parity with the source's cached system-prompt
-   * prefix. May also pin `hasNoClient` for the prompt build (see
+   * prefix. May also pin presence for the prompt build (see
    * {@link SystemPromptPersonaOverride}). Prompt-build selection only; trust
    * class and approval semantics are governed solely by `trustContext`.
    */
@@ -400,14 +400,14 @@ export interface WakeOptions {
    */
   cronRunId?: string;
   /**
-   * Run the woken turn clientless: pin `hasNoClient = true` for the duration of
-   * the agent-loop run (restored after). Wakes bypass the orchestrator's
-   * turn-start interactivity setup, so a wake on a conversation with no client
-   * attached otherwise derives `isInteractive: true` (the default
-   * `hasNoClient = false`). Pinning it makes `conversation-tool-setup` derive
-   * `isInteractive: false`, which `policy-context` maps to `background`
-   * (guardian) / `headless` (unknown) — so a side-effecting tool that would
-   * prompt is denied instead of stalling on a client that isn't there.
+   * Run the woken turn clientless: pin the per-turn presence
+   * (`currentTurnIsNonInteractive = true`, which `hasNoClient` reads) for the
+   * duration of the agent-loop run (restored after). Wakes bypass the
+   * orchestrator's turn-start interactivity setup, so the pin is what makes
+   * `conversation-tool-setup` derive `isInteractive: false`, which
+   * `policy-context` maps to `background` (guardian) / `headless` (unknown),
+   * so a side-effecting tool that would prompt is denied instead of stalling
+   * on a client that isn't there.
    */
   clientless?: boolean;
 }
@@ -718,9 +718,9 @@ export async function wakeAgentForOpportunity(
   return runWakeSingleFlight(conversationId, async () => {
     // Snapshot the conversation's resting trust before the resolver runs, so
     // it can be restored after. The resolver leaves the wake's trust on the
-    // conversation, and a following no-trust wake would otherwise read it via
-    // tool setup's `currentTurnTrustContext ?? trustContext` fallback. Null
-    // when the conversation isn't resident yet (a fresh hydrate or a fork).
+    // conversation, and a following no-trust wake would otherwise pick it up
+    // from the resting trust its consumers fall back to. Null when the
+    // conversation isn't resident yet (a fresh hydrate or a fork).
     let priorPersistentTrust: TrustContext | null = null;
     if (opts.trustContext) {
       const { findConversation } =
@@ -1454,7 +1454,8 @@ export async function wakeAgentForOpportunity(
       const priorCallSite = conversation.currentCallSite;
       const priorTurnOverrideProfile = conversation.currentTurnOverrideProfile;
       const priorTurnCronRunId = conversation.currentTurnCronRunId;
-      const priorHasNoClient = conversation.hasNoClient;
+      const priorTurnIsNonInteractive =
+        conversation.currentTurnIsNonInteractive;
       const priorTurnTrust = conversation.currentTurnTrustContext;
       conversation.currentCallSite = callSite;
       conversation.currentTurnOverrideProfile = overrideProfile;
@@ -1462,7 +1463,9 @@ export async function wakeAgentForOpportunity(
       // delegates work to subagents whose usage must attribute to that firing.
       conversation.currentTurnCronRunId = opts.cronRunId ?? null;
       if (opts.clientless) {
-        conversation.hasNoClient = true;
+        // Presence is per-turn state; a clientless wake declares no human is
+        // present for the duration of its dispatch.
+        conversation.currentTurnIsNonInteractive = true;
       }
       // Per-turn guardian elevation for the wake's tools, set after the pre-run
       // reads so a pre-run failure can't leak it; restored in the finally.
@@ -1550,7 +1553,7 @@ export async function wakeAgentForOpportunity(
         conversation.currentCallSite = priorCallSite;
         conversation.currentTurnOverrideProfile = priorTurnOverrideProfile;
         conversation.currentTurnCronRunId = priorTurnCronRunId;
-        conversation.hasNoClient = priorHasNoClient;
+        conversation.currentTurnIsNonInteractive = priorTurnIsNonInteractive;
         conversation.currentTurnTrustContext = priorTurnTrust;
       }