@vellumai/assistant 0.6.2 → 0.6.3

package/src/browser-session/events.ts

@@ -0,0 +1,164 @@
+/**
+ * Module-level event bus for out-of-band browser-session signals.
+ *
+ * The `host_browser_event` and `host_browser_session_invalidated`
+ * envelopes (see `assistant/src/daemon/message-types/host-browser.ts`)
+ * carry unsolicited CDP events and detach notifications from the
+ * chrome extension to the daemon. Unlike `host_browser_result`, these
+ * frames are not tied to a specific in-flight request and cannot be
+ * routed through `pending-interactions`. Instead they publish into
+ * this bus, where tool-side consumers subscribe to react to the signal.
+ *
+ * Two distinct surfaces:
+ *
+ *   1. **CDP event listeners** — free-form subscribers that observe
+ *      every incoming `host_browser_event`. Primarily a seam for
+ *      future work (event-driven session tracking, lifecycle
+ *      instrumentation, tool-side reactive hooks) and for tests that
+ *      need to assert that events were routed.
+ *
+ *   2. **Invalidated target registry** — a short-lived set of target
+ *      ids that the extension has reported as detached. The
+ *      `BrowserSessionManager` checks this set on its next `send()`
+ *      and evicts any matching session before dispatch so the
+ *      extension dispatcher can re-attach fresh. Entries are
+ *      consumed on first lookup to keep the set from growing
+ *      unbounded across long-running processes.
+ *
+ * Both surfaces are intentionally transport-agnostic — the WS and
+ * HTTP paths both publish through the same module so the routing
+ * semantics stay in lockstep.
+ */
+
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("browser-session-events");
+
+// ---------------------------------------------------------------------------
+// CDP event listener surface
+// ---------------------------------------------------------------------------
+
+/**
+ * A forwarded CDP event as consumed by runtime-side subscribers. The
+ * wire shape comes from `HostBrowserEvent` in
+ * `assistant/src/daemon/message-types/host-browser.ts` and is stripped
+ * of its `type` discriminator here for ergonomic subscriber code.
+ */
+export interface ForwardedCdpEvent {
+  /** CDP event method name, e.g. "Page.frameNavigated". */
+  method: string;
+  /** CDP event params forwarded verbatim. Opaque to the bus. */
+  params?: unknown;
+  /**
+   * Optional CDP session id — present for flat child sessions routed
+   * through `Target.attachToTarget` with `flatten: true`.
+   */
+  cdpSessionId?: string;
+}
+
+export type CdpEventListener = (event: ForwardedCdpEvent) => void;
+
+const cdpEventListeners = new Set<CdpEventListener>();
+
+/**
+ * Subscribe to forwarded CDP events. Returns an unsubscribe function;
+ * callers MUST invoke it at end-of-lifecycle to avoid leaking closures
+ * into the module-level set. Listener errors are caught and logged so
+ * a broken subscriber cannot take down the WS dispatch path.
+ */
+export function onCdpEvent(listener: CdpEventListener): () => void {
+  cdpEventListeners.add(listener);
+  return () => {
+    cdpEventListeners.delete(listener);
+  };
+}
+
+/**
+ * Fan an incoming CDP event out to all registered listeners. Called
+ * by the WS frame dispatcher in
+ * `assistant/src/runtime/routes/host-browser-routes.ts` after a
+ * `host_browser_event` envelope has been validated.
+ */
+export function publishCdpEvent(event: ForwardedCdpEvent): void {
+  for (const listener of cdpEventListeners) {
+    try {
+      listener(event);
+    } catch (err) {
+      log.warn(
+        { err, method: event.method },
+        "CDP event listener threw — suppressing to protect dispatcher",
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Invalidated target registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Short-lived set of target ids the chrome extension has reported as
+ * detached since the last `consumeInvalidatedTargetId` lookup. The
+ * `BrowserSessionManager.invalidateByTargetId` path reads entries
+ * out of this set on each `send()` and evicts any matching session
+ * before dispatch.
+ *
+ * Entries are consumed on first read so the set never grows
+ * unbounded. If a future consumer needs multiple reads of the same
+ * invalidation, a separate long-lived registry should be introduced
+ * — this set is scoped to the minimum viable behaviour for
+ * "next command forces reattach".
+ */
+const invalidatedTargetIds = new Set<string>();
+
+/**
+ * Record that the chrome extension has reported a target as
+ * detached. Idempotent — re-marking a target is a no-op. Logs at
+ * debug because the signal is benign (just a lifecycle notification)
+ * and noisy in high-churn workloads.
+ */
+export function markTargetInvalidated(targetId: string, reason?: string): void {
+  invalidatedTargetIds.add(targetId);
+  log.debug({ targetId, reason }, "browser-session target invalidated");
+}
+
+/**
+ * Peek at whether a given target id is currently marked invalidated
+ * without consuming the entry. Primarily used by tests — production
+ * consumers should call {@link consumeInvalidatedTargetId} so the
+ * set stays bounded.
+ */
+export function isTargetInvalidated(targetId: string): boolean {
+  return invalidatedTargetIds.has(targetId);
+}
+
+/**
+ * Test-only helper: snapshot the current invalidated set without
+ * draining it. Exported so unit tests can assert exact set contents
+ * across multiple frames; production code must not rely on this.
+ */
+export function __peekInvalidatedTargetIdsForTests(): string[] {
+  return Array.from(invalidatedTargetIds);
+}
+
+/**
+ * Atomically remove and return a target id from the invalidated set.
+ * Returns `true` when the id was present (and has now been removed),
+ * `false` otherwise. Designed to be called by
+ * `BrowserSessionManager.send()` so the first dispatch after a
+ * detach forces a reattach and subsequent dispatches proceed normally.
+ */
+export function consumeInvalidatedTargetId(targetId: string): boolean {
+  return invalidatedTargetIds.delete(targetId);
+}
+
+/**
+ * Test-only helper: clear the entire invalidated set. Not exported
+ * from any public index — used by unit tests that need a clean slate
+ * between cases. Not safe to call from production code because it
+ * would race against concurrent invalidations.
+ */
+export function __resetBrowserSessionEventsForTests(): void {
+  cdpEventListeners.clear();
+  invalidatedTargetIds.clear();
+}

package/src/browser-session/index.ts

@@ -0,0 +1,27 @@
+/**
+ * BrowserSessionManager — multi-backend session router for host_browser.
+ *
+ * This module is the single CDP backend selector for browser tools. The
+ * `cdp-client` factory (`assistant/src/tools/browser/cdp-client/factory.ts`)
+ * constructs a BrowserSessionManager per tool invocation, registers the
+ * appropriate backend from a three-way selection:
+ *
+ *  1. **Extension** — selected when `hostBrowserProxy` is present (macOS
+ *     desktop / cloud-hosted with a chrome-extension bound to the
+ *     conversation).
+ *  2. **cdp-inspect** — selected when the extension is absent and
+ *     `hostBrowser.cdpInspect.enabled` is `true` in config. Attaches to
+ *     an already-running Chrome via `--remote-debugging-port`.
+ *  3. **Local** — default when neither of the above applies.
+ *     Drives a Playwright-backed sacrificial-profile Chromium.
+ *
+ * The factory exposes a `ScopedCdpClient` that routes `send()` through
+ * the manager. This gives every call site a single choke point for
+ * session invalidation and future multi-tab routing.
+ */
+export * from "./backends/cdp-inspect.js";
+export * from "./backends/extension.js";
+export * from "./backends/local.js";
+export * from "./events.js";
+export * from "./manager.js";
+export * from "./types.js";

package/src/browser-session/manager.ts

@@ -0,0 +1,159 @@
+import { v4 as uuid } from "uuid";
+
+import { consumeInvalidatedTargetId } from "./events.js";
+import type {
+  BrowserBackend,
+  BrowserSession,
+  CdpCommand,
+  CdpResult,
+} from "./types.js";
+
+export interface BrowserSessionManagerOptions {
+  /** Ordered list of backends to try; first available wins. */
+  backends: BrowserBackend[];
+}
+
+export class BrowserSessionManager {
+  private backends: BrowserBackend[];
+  private sessions = new Map<string, BrowserSession>();
+
+  constructor(opts: BrowserSessionManagerOptions) {
+    this.backends = opts.backends;
+  }
+
+  /** Pick an available backend or throw. */
+  selectBackend(): BrowserBackend {
+    const b = this.backends.find((x) => x.isAvailable());
+    if (!b) throw new Error("No available browser backend");
+    return b;
+  }
+
+  createSession(): BrowserSession {
+    const backend = this.selectBackend();
+    const session: BrowserSession = { id: uuid(), backendKind: backend.kind };
+    this.sessions.set(session.id, session);
+    return session;
+  }
+
+  getSession(id: string): BrowserSession | undefined {
+    return this.sessions.get(id);
+  }
+
+  /**
+   * Dispatch a CDP command.
+   *
+   * - If `sessionId` is provided, the session must exist in the manager; otherwise this throws.
+   *   The command is routed through the backend whose `kind` matches the session's `backendKind`,
+   *   ensuring per-session backend isolation and making `disposeSession()` an actual enforcement
+   *   boundary against stale ids. If the session has an opaque `targetId` and the command does
+   *   not already carry its own CDP `sessionId`, the manager injects the session's `targetId`
+   *   as the CDP `sessionId` so backends can multiplex commands across multiple tabs/targets.
+   * - If `sessionId` is `undefined`, the first available backend is selected for one-off
+   *   commands without a session handle (e.g. transport health probes).
+   */
+  async send(
+    sessionId: string | undefined,
+    command: CdpCommand,
+    signal?: AbortSignal,
+  ): Promise<CdpResult> {
+    let backend: BrowserBackend;
+    let outgoing = command;
+    if (sessionId !== undefined) {
+      const session = this.sessions.get(sessionId);
+      if (!session) {
+        throw new Error(`Unknown browser session: ${sessionId}`);
+      }
+      // If the chrome extension has reported this session's target
+      // as detached since the last dispatch, evict the session and
+      // throw so the caller can create a fresh one. Reading (and
+      // consuming) the invalidation flag here keeps the "next
+      // command forces reattach" semantics in lockstep with the
+      // host_browser_session_invalidated envelope handler — without
+      // this check the manager would happily forward a CDP command
+      // against a torn-down target and hit a permanent failure.
+      if (
+        session.targetId !== undefined &&
+        consumeInvalidatedTargetId(session.targetId)
+      ) {
+        this.sessions.delete(sessionId);
+        throw new Error(
+          `Browser session ${sessionId} was invalidated (target ${session.targetId} detached)`,
+        );
+      }
+      const matched = this.backends.find((b) => b.kind === session.backendKind);
+      if (!matched) {
+        throw new Error(
+          `No backend available for session kind: ${session.backendKind}`,
+        );
+      }
+      backend = matched;
+      // If the session has an opaque targetId and the command does not
+      // carry its own CDP sessionId, inject the session's targetId as
+      // the CDP sessionId. Backends that support multi-target routing
+      // will forward it; backends that ignore it will treat the call
+      // as "most-recent-tab" as before.
+      if (session.targetId !== undefined && command.sessionId === undefined) {
+        outgoing = { ...command, sessionId: session.targetId };
+      }
+    } else {
+      backend = this.selectBackend();
+    }
+    return backend.send(outgoing, signal);
+  }
+
+  disposeSession(id: string): void {
+    this.sessions.delete(id);
+  }
+
+  /**
+   * Evict a session that the backend has informed us is no longer
+   * valid — e.g. the chrome extension dispatched a
+   * `host_browser_session_invalidated` envelope after Chrome detached
+   * the debugger from the underlying tab/target.
+   *
+   * Functionally equivalent to {@link disposeSession} today (both
+   * remove the session from the manager's map so a subsequent
+   * `send()` throws "Unknown browser session") but preserved as a
+   * distinct method so call sites can stay explicit about intent.
+   * Callers that receive a detach/invalidated signal should use this
+   * method; callers that are cleaning up at end-of-lifecycle should
+   * use {@link disposeSession}.
+   *
+   * Returns `true` when a session was actually removed, `false` when
+   * no session with that id was tracked. Returning a boolean lets
+   * transport-level dispatchers (see
+   * `resolveHostBrowserSessionInvalidated`) log at the right level
+   * based on whether the invalidation had any effect.
+   */
+  invalidateSession(id: string): boolean {
+    return this.sessions.delete(id);
+  }
+
+  /**
+   * Evict every session whose opaque `targetId` matches the supplied
+   * id. Used by the WS dispatcher when a `host_browser_session_invalidated`
+   * envelope arrives without a manager-level session id: the
+   * extension-side dispatcher only knows its own `tabId` / `targetId`
+   * and does not carry our uuid session handle.
+   *
+   * Returns the number of sessions removed. A zero return does not
+   * necessarily indicate an error — the target may not have a
+   * runtime-side session attached to it yet, or the session may
+   * already have been disposed by its owning tool.
+   */
+  invalidateByTargetId(targetId: string): number {
+    let removed = 0;
+    for (const [id, session] of this.sessions) {
+      if (session.targetId === targetId) {
+        this.sessions.delete(id);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  disposeAll(): void {
+    for (const b of this.backends) b.dispose();
+    this.sessions.clear();
+  }
+}

package/src/browser-session/types.ts

@@ -0,0 +1,28 @@
+export type BrowserBackendKind = "extension" | "local" | "cdp-inspect";
+
+export interface CdpCommand {
+  method: string;
+  params?: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface CdpResult {
+  /** Raw CDP result object; opaque to the manager. */
+  result?: unknown;
+  /** CDP error envelope if the command failed. */
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface BrowserSession {
+  id: string;
+  backendKind: BrowserBackendKind;
+  /** Opaque target/sessionId from the backend. Omitted for "most-recent-tab" commands. */
+  targetId?: string;
+}
+
+export interface BrowserBackend {
+  kind: BrowserBackendKind;
+  isAvailable(): boolean;
+  send(command: CdpCommand, signal?: AbortSignal): Promise<CdpResult>;
+  dispose(): void;
+}

package/src/channels/__tests__/types.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  INTERACTIVE_INTERFACES,
+  INTERFACE_IDS,
+  isInterfaceId,
+  supportsHostProxy,
+} from "../types.js";
+
+describe("INTERFACE_IDS", () => {
+  test("includes chrome-extension", () => {
+    expect(
+      (INTERFACE_IDS as readonly string[]).includes("chrome-extension"),
+    ).toBe(true);
+  });
+
+  test("still includes macos and other existing interfaces", () => {
+    for (const id of [
+      "macos",
+      "ios",
+      "cli",
+      "telegram",
+      "phone",
+      "vellum",
+      "whatsapp",
+      "slack",
+      "email",
+    ]) {
+      expect((INTERFACE_IDS as readonly string[]).includes(id)).toBe(true);
+    }
+  });
+});
+
+describe("INTERACTIVE_INTERFACES", () => {
+  test("does NOT include chrome-extension", () => {
+    // Chrome extensions don't render SSE-backed prompter UI, so they must
+    // stay out of the interactive set even though they have an InterfaceId.
+    expect(INTERACTIVE_INTERFACES.has("chrome-extension" as never)).toBe(false);
+  });
+
+  test("still includes macos", () => {
+    expect(INTERACTIVE_INTERFACES.has("macos")).toBe(true);
+  });
+});
+
+describe("isInterfaceId", () => {
+  test("returns true for chrome-extension", () => {
+    expect(isInterfaceId("chrome-extension")).toBe(true);
+  });
+
+  test("returns true for macos", () => {
+    expect(isInterfaceId("macos")).toBe(true);
+  });
+
+  test("returns false for unknown interface", () => {
+    expect(isInterfaceId("safari-extension")).toBe(false);
+  });
+});
+
+describe("supportsHostProxy", () => {
+  // ── macOS: supports host_bash / host_file / host_cu, but NOT host_browser. ──
+  test("macos returns true (no capability)", () => {
+    expect(supportsHostProxy("macos")).toBe(true);
+  });
+
+  test("macos returns true for host_bash", () => {
+    expect(supportsHostProxy("macos", "host_bash")).toBe(true);
+  });
+
+  test("macos returns true for host_file", () => {
+    expect(supportsHostProxy("macos", "host_file")).toBe(true);
+  });
+
+  test("macos returns true for host_cu", () => {
+    expect(supportsHostProxy("macos", "host_cu")).toBe(true);
+  });
+
+  test("macos returns false for host_browser", () => {
+    expect(supportsHostProxy("macos", "host_browser")).toBe(false);
+  });
+
+  // ── chrome-extension: only host_browser. ──
+  test("chrome-extension returns false (no capability)", () => {
+    // Chrome extension does not support "any host proxy at all" — it only
+    // supports host_browser, so the no-arg form must return false to keep
+    // existing call sites that guard desktop-only behavior unchanged.
+    expect(supportsHostProxy("chrome-extension")).toBe(false);
+  });
+
+  test("chrome-extension returns true for host_browser", () => {
+    expect(supportsHostProxy("chrome-extension", "host_browser")).toBe(true);
+  });
+
+  test("chrome-extension returns false for host_bash", () => {
+    expect(supportsHostProxy("chrome-extension", "host_bash")).toBe(false);
+  });
+
+  test("chrome-extension returns false for host_file", () => {
+    expect(supportsHostProxy("chrome-extension", "host_file")).toBe(false);
+  });
+
+  test("chrome-extension returns false for host_cu", () => {
+    expect(supportsHostProxy("chrome-extension", "host_cu")).toBe(false);
+  });
+
+  // ── Non-supporting interfaces: false in all forms. ──
+  test("cli returns false (no capability)", () => {
+    expect(supportsHostProxy("cli")).toBe(false);
+  });
+
+  test("cli returns false for host_bash", () => {
+    expect(supportsHostProxy("cli", "host_bash")).toBe(false);
+  });
+
+  test("cli returns false for host_browser", () => {
+    expect(supportsHostProxy("cli", "host_browser")).toBe(false);
+  });
+
+  test("telegram returns false (no capability)", () => {
+    expect(supportsHostProxy("telegram")).toBe(false);
+  });
+
+  test("telegram returns false for host_browser", () => {
+    expect(supportsHostProxy("telegram", "host_browser")).toBe(false);
+  });
+
+  test("vellum returns false (no capability)", () => {
+    expect(supportsHostProxy("vellum")).toBe(false);
+  });
+
+  test("email returns false for host_browser", () => {
+    expect(supportsHostProxy("email", "host_browser")).toBe(false);
+  });
+});

package/src/channels/types.ts

@@ -48,6 +48,7 @@ export const INTERFACE_IDS = [
   "whatsapp",
   "slack",
   "email",
+  "chrome-extension",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];
@@ -90,9 +91,58 @@ export function isInteractiveInterface(id: InterfaceId): boolean {
   return INTERACTIVE_INTERFACES.has(id);
 }
 
-/** Whether the interface supports host proxies (bash, file, computer-use). */
-export function supportsHostProxy(id: InterfaceId): boolean {
-  return id === "macos";
+/**
+ * Host proxy capabilities that an interface can support. The macOS client
+ * supports all four; the chrome-extension interface only supports
+ * host_browser (via the Chrome DevTools Protocol proxy).
+ */
+export type HostProxyCapability =
+  | "host_bash"
+  | "host_file"
+  | "host_cu"
+  | "host_browser";
+
+/**
+ * Interfaces that support the full desktop host-proxy set (all four
+ * `HostProxyCapability` values). This is the capability-level identity used
+ * by the discriminated transport metadata union and by the
+ * `supportsHostProxy(id)` type predicate.
+ *
+ * Extend this literal type AND the `supportsHostProxy` implementation
+ * below in lock-step when adding a new host-capable client (e.g. a native
+ * Linux or Windows desktop).
+ */
+export type HostProxyInterfaceId = "macos";
+
+/**
+ * Whether the interface supports a host proxy capability.
+ *
+ * The no-arg form `supportsHostProxy(id)` asks "is this interface a desktop
+ * host-proxy client?" — it returns `true` only for macOS and is the type
+ * predicate that narrows `InterfaceId` to `HostProxyInterfaceId`. It returns
+ * `false` for chrome-extension because chrome-extension only supports
+ * `host_browser`, and the no-arg form is the gate that legacy desktop-only
+ * call sites use (e.g. preactivating computer-use, restoring host proxies
+ * in the drain queue). Callers that want to check a single capability —
+ * for example, to decide whether to keep `hostBrowserProxy` available for
+ * chrome-extension — should pass the capability explicitly:
+ * `supportsHostProxy(id, "host_browser")`.
+ */
+export function supportsHostProxy(id: InterfaceId): id is HostProxyInterfaceId;
+export function supportsHostProxy(
+  id: InterfaceId,
+  capability: HostProxyCapability,
+): boolean;
+export function supportsHostProxy(
+  id: InterfaceId,
+  capability?: HostProxyCapability,
+): boolean {
+  // host_browser is excluded for macos because the proxy path requires a
+  // Chrome extension that isn't guaranteed to be attached; browser tools
+  // fall back to the local Playwright Chromium instead.
+  if (id === "macos") return capability !== "host_browser";
+  if (id === "chrome-extension" && capability === "host_browser") return true;
+  return false;
 }
 
 export interface TurnInterfaceContext {