@vellumai/assistant 0.6.2 → 0.6.4

package/src/browser-session/__tests__/manager.test.ts

@@ -0,0 +1,297 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  type BrowserBackend,
+  BrowserSessionManager,
+  type CdpCommand,
+  type CdpResult,
+  createExtensionBackend,
+  createLocalBackend,
+} from "../index.js";
+
+interface MockBackendState {
+  available: boolean;
+  disposed: boolean;
+  lastCommand?: CdpCommand;
+  lastSignal?: AbortSignal;
+  sendImpl?: (command: CdpCommand, signal?: AbortSignal) => Promise<CdpResult>;
+}
+
+function createMockExtensionBackend(state: MockBackendState): BrowserBackend {
+  return createExtensionBackend({
+    isAvailable: () => state.available,
+    sendCdp: async (command, signal) => {
+      state.lastCommand = command;
+      state.lastSignal = signal;
+      if (state.sendImpl) return state.sendImpl(command, signal);
+      return { result: { ok: true } };
+    },
+    dispose: () => {
+      state.disposed = true;
+    },
+  });
+}
+
+function createMockLocalBackend(state: MockBackendState): BrowserBackend {
+  return createLocalBackend({
+    isAvailable: () => state.available,
+    sendCdp: async (command, signal) => {
+      state.lastCommand = command;
+      state.lastSignal = signal;
+      if (state.sendImpl) return state.sendImpl(command, signal);
+      return { result: { ok: true, kind: "local" } };
+    },
+    dispose: () => {
+      state.disposed = true;
+    },
+  });
+}
+
+describe("BrowserSessionManager", () => {
+  test("selectBackend throws when no backend is available", () => {
+    const state: MockBackendState = { available: false, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    expect(() => manager.selectBackend()).toThrow(
+      "No available browser backend",
+    );
+  });
+
+  test("selectBackend returns the extension backend when available", () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const backend = createMockExtensionBackend(state);
+    const manager = new BrowserSessionManager({ backends: [backend] });
+    const selected = manager.selectBackend();
+    expect(selected.kind).toBe("extension");
+    expect(selected).toBe(backend);
+  });
+
+  test("createSession returns a session with a new uuid stored in the map", () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const session = manager.createSession();
+    expect(session.id).toBeTruthy();
+    expect(session.backendKind).toBe("extension");
+    // Lookup round-trips.
+    expect(manager.getSession(session.id)).toEqual(session);
+    // Two sessions get unique ids.
+    const another = manager.createSession();
+    expect(another.id).not.toBe(session.id);
+  });
+
+  test("send delegates to backend.send and returns the CDP result", async () => {
+    const expectedResult: CdpResult = { result: { value: 42 } };
+    const state: MockBackendState = {
+      available: true,
+      disposed: false,
+      sendImpl: async () => expectedResult,
+    };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const result = await manager.send(undefined, {
+      method: "Browser.getVersion",
+      params: { foo: "bar" },
+    });
+    expect(result).toEqual(expectedResult);
+    expect(state.lastCommand).toEqual({
+      method: "Browser.getVersion",
+      params: { foo: "bar" },
+    });
+  });
+
+  test("send with an aborted signal propagates the abort", async () => {
+    const state: MockBackendState = {
+      available: true,
+      disposed: false,
+      sendImpl: async (_command, signal) => {
+        if (signal?.aborted) {
+          throw new Error("aborted");
+        }
+        return { result: { ok: true } };
+      },
+    };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      manager.send(
+        undefined,
+        { method: "Browser.getVersion" },
+        controller.signal,
+      ),
+    ).rejects.toThrow("aborted");
+    expect(state.lastSignal).toBe(controller.signal);
+  });
+
+  test("disposeAll calls backend.dispose and clears the session map", () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const session = manager.createSession();
+    expect(manager.getSession(session.id)).toBeDefined();
+    manager.disposeAll();
+    expect(state.disposed).toBe(true);
+    expect(manager.getSession(session.id)).toBeUndefined();
+  });
+
+  test("send with a known sessionId routes through the matching backend", async () => {
+    const expectedResult: CdpResult = { result: { routed: true } };
+    const state: MockBackendState = {
+      available: true,
+      disposed: false,
+      sendImpl: async () => expectedResult,
+    };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const session = manager.createSession();
+    const result = await manager.send(session.id, {
+      method: "Browser.getVersion",
+    });
+    expect(result).toEqual(expectedResult);
+    expect(state.lastCommand).toEqual({ method: "Browser.getVersion" });
+  });
+
+  test("send with an unknown sessionId throws", async () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    await expect(
+      manager.send("does-not-exist", { method: "Browser.getVersion" }),
+    ).rejects.toThrow("Unknown browser session: does-not-exist");
+    // The mock backend should not have received the command.
+    expect(state.lastCommand).toBeUndefined();
+  });
+
+  test("send with a sessionId of a disposed session throws", async () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockExtensionBackend(state)],
+    });
+    const session = manager.createSession();
+    manager.disposeSession(session.id);
+    await expect(
+      manager.send(session.id, { method: "Browser.getVersion" }),
+    ).rejects.toThrow(`Unknown browser session: ${session.id}`);
+    expect(state.lastCommand).toBeUndefined();
+  });
+
+  test("selectBackend returns a local backend when it is the only registration", () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const backend = createMockLocalBackend(state);
+    const manager = new BrowserSessionManager({ backends: [backend] });
+    const selected = manager.selectBackend();
+    expect(selected.kind).toBe("local");
+    expect(selected).toBe(backend);
+  });
+
+  test("createSession tags sessions with the local backend kind", () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockLocalBackend(state)],
+    });
+    const session = manager.createSession();
+    expect(session.backendKind).toBe("local");
+  });
+
+  test("send routes through local backend when its session is used", async () => {
+    const state: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [createMockLocalBackend(state)],
+    });
+    const session = manager.createSession();
+    const result = await manager.send(session.id, {
+      method: "Runtime.evaluate",
+      params: { expression: "1+1" },
+    });
+    expect(result).toEqual({ result: { ok: true, kind: "local" } });
+    expect(state.lastCommand).toEqual({
+      method: "Runtime.evaluate",
+      params: { expression: "1+1" },
+    });
+  });
+
+  test("selectBackend falls back to the first available backend when earlier ones are unavailable", () => {
+    const extState: MockBackendState = { available: false, disposed: false };
+    const localState: MockBackendState = { available: true, disposed: false };
+    const ext = createMockExtensionBackend(extState);
+    const local = createMockLocalBackend(localState);
+    const manager = new BrowserSessionManager({ backends: [ext, local] });
+    const selected = manager.selectBackend();
+    expect(selected.kind).toBe("local");
+    expect(selected).toBe(local);
+  });
+
+  test("selectBackend prefers the first available backend", () => {
+    const extState: MockBackendState = { available: true, disposed: false };
+    const localState: MockBackendState = { available: true, disposed: false };
+    const ext = createMockExtensionBackend(extState);
+    const local = createMockLocalBackend(localState);
+    const manager = new BrowserSessionManager({ backends: [ext, local] });
+    const selected = manager.selectBackend();
+    expect(selected.kind).toBe("extension");
+    expect(selected).toBe(ext);
+  });
+
+  test("send routes to the backend matching the session's backendKind when multiple backends are registered", async () => {
+    const extState: MockBackendState = {
+      available: true,
+      disposed: false,
+      sendImpl: async () => ({ result: { from: "extension" } }),
+    };
+    const localState: MockBackendState = {
+      available: true,
+      disposed: false,
+      sendImpl: async () => ({ result: { from: "local" } }),
+    };
+    const ext = createMockExtensionBackend(extState);
+    const local = createMockLocalBackend(localState);
+    const manager = new BrowserSessionManager({ backends: [ext, local] });
+
+    // createSession picks the first available backend (extension), but we
+    // can also force the local one by passing a backendKind via direct
+    // session construction. To keep this test self-contained we verify the
+    // default path and then mark the extension unavailable to force the
+    // local backend for a new session.
+    const extSession = manager.createSession();
+    expect(extSession.backendKind).toBe("extension");
+    const extResult = await manager.send(extSession.id, {
+      method: "Browser.getVersion",
+    });
+    expect(extResult).toEqual({ result: { from: "extension" } });
+    expect(extState.lastCommand).toEqual({ method: "Browser.getVersion" });
+    expect(localState.lastCommand).toBeUndefined();
+
+    extState.available = false;
+    const localSession = manager.createSession();
+    expect(localSession.backendKind).toBe("local");
+    const localResult = await manager.send(localSession.id, {
+      method: "Runtime.evaluate",
+    });
+    expect(localResult).toEqual({ result: { from: "local" } });
+    expect(localState.lastCommand).toEqual({ method: "Runtime.evaluate" });
+  });
+
+  test("disposeAll disposes every registered backend", () => {
+    const extState: MockBackendState = { available: true, disposed: false };
+    const localState: MockBackendState = { available: true, disposed: false };
+    const manager = new BrowserSessionManager({
+      backends: [
+        createMockExtensionBackend(extState),
+        createMockLocalBackend(localState),
+      ],
+    });
+    manager.createSession();
+    manager.disposeAll();
+    expect(extState.disposed).toBe(true);
+    expect(localState.disposed).toBe(true);
+  });
+});

package/src/browser-session/backends/cdp-inspect.ts

@@ -0,0 +1,30 @@
+import type { BrowserBackend, CdpCommand, CdpResult } from "../types.js";
+
+/**
+ * cdp-inspect backend for BrowserSessionManager. Wraps a
+ * caller-provided `sendCdp` transport that talks to an already-running
+ * Chrome via DevTools JSON discovery + a raw WebSocket transport
+ * (see `assistant/src/tools/browser/cdp-client/cdp-inspect-client.ts`).
+ *
+ * The factory in
+ * `assistant/src/tools/browser/cdp-client/factory.ts` constructs
+ * one per tool invocation, paralleling the existing extension
+ * and local backend wiring.
+ */
+export interface CdpInspectBackendDeps {
+  /** Sends a CDP command to the user's Chrome via cdp-inspect and returns the CDP result. */
+  sendCdp(command: CdpCommand, signal?: AbortSignal): Promise<CdpResult>;
+  isAvailable(): boolean;
+  dispose(): void;
+}
+
+export function createCdpInspectBackend(
+  deps: CdpInspectBackendDeps,
+): BrowserBackend {
+  return {
+    kind: "cdp-inspect",
+    isAvailable: deps.isAvailable,
+    send: deps.sendCdp,
+    dispose: deps.dispose,
+  };
+}

package/src/browser-session/backends/extension.ts

@@ -0,0 +1,26 @@
+import type { BrowserBackend, CdpCommand, CdpResult } from "../types.js";
+
+/**
+ * Extension backend for BrowserSessionManager. Wraps a caller-provided
+ * `sendCdp` transport that routes CDP commands through the daemon's
+ * HostBrowserProxy to an attached chrome extension. The factory in
+ * `assistant/src/tools/browser/cdp-client/factory.ts` constructs one
+ * per tool invocation using the conversation's `hostBrowserProxy`.
+ */
+export interface ExtensionBackendDeps {
+  /** Sends a CDP command to an attached chrome extension and returns the CDP result. */
+  sendCdp(command: CdpCommand, signal?: AbortSignal): Promise<CdpResult>;
+  isAvailable(): boolean;
+  dispose(): void;
+}
+
+export function createExtensionBackend(
+  deps: ExtensionBackendDeps,
+): BrowserBackend {
+  return {
+    kind: "extension",
+    isAvailable: deps.isAvailable,
+    send: deps.sendCdp,
+    dispose: deps.dispose,
+  };
+}

package/src/browser-session/backends/local.ts

@@ -0,0 +1,24 @@
+import type { BrowserBackend, CdpCommand, CdpResult } from "../types.js";
+
+/**
+ * Local backend for BrowserSessionManager. Wraps a caller-provided
+ * `sendCdp` transport that drives a Playwright CDPSession against the
+ * sacrificial-profile Chromium managed by `browserManager`. The factory
+ * in `assistant/src/tools/browser/cdp-client/factory.ts` constructs one
+ * per tool invocation using the per-conversation LocalCdpClient.
+ */
+export interface LocalBackendDeps {
+  /** Sends a CDP command to a Playwright CDPSession and returns the CDP result. */
+  sendCdp(command: CdpCommand, signal?: AbortSignal): Promise<CdpResult>;
+  isAvailable(): boolean;
+  dispose(): void;
+}
+
+export function createLocalBackend(deps: LocalBackendDeps): BrowserBackend {
+  return {
+    kind: "local",
+    isAvailable: deps.isAvailable,
+    send: deps.sendCdp,
+    dispose: deps.dispose,
+  };
+}

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";