@vellumai/assistant 0.8.3 → 0.8.5

package/src/tools/browser/cdp-client/factory.ts

@@ -11,6 +11,7 @@ import { getConfig } from "../../../config/loader.js";
 import { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
 import { getLogger } from "../../../util/logger.js";
 import type { ToolContext } from "../../types.js";
+import { getPinnedTab } from "../pinned-tabs.js";
 import { createCdpInspectClient } from "./cdp-inspect-client.js";
 import { CdpError } from "./errors.js";
 import { createExtensionCdpClient } from "./extension-cdp-client.js";
@@ -22,6 +23,7 @@ import type {
   CdpClient,
   CdpClientKind,
   ScopedCdpClient,
+  TabInfo,
 } from "./types.js";
 
 const log = getLogger("cdp-factory");
@@ -222,7 +224,12 @@ export function buildPinnedCandidateList(
             const client = createExtensionCdpClient(
               hostBrowserProxy,
               conversationId,
-              undefined,
+              // Pass clientId to scope the pin lookup to this specific
+              // extension install. When a targetClientId is provided
+              // the pin is fetched for that client; otherwise falls back
+              // to the __default__ slot which is set by older callers
+              // without clientId awareness.
+              getPinnedTab(conversationId, targetClientId),
               sourceActorPrincipalId,
               targetClientId,
             );
@@ -330,10 +337,13 @@ export function buildCandidateList(context: ToolContext, targetClientId?: string
         kind: "extension",
         reason: `target_client_id override: ${targetClientId}`,
         create() {
+          // Explicit target_client_id override → look up the pin scoped
+          // to this specific client. This is safe because targetClientId
+          // and the pin were both recorded for the same extension install.
           const client = createExtensionCdpClient(
             hostBrowserProxy,
             conversationId,
-            undefined,
+            getPinnedTab(conversationId, targetClientId),
             sourceActorPrincipalId,
             targetClientId,
           );
@@ -358,7 +368,11 @@ export function buildCandidateList(context: ToolContext, targetClientId?: string
         const client = createExtensionCdpClient(
           hostBrowserProxy,
           conversationId,
-          undefined,
+          // targetClientId is always undefined here — this code path
+          // only runs when targetClientId is null (the early-return
+          // above handles the non-null case). Use the no-clientId
+          // lookup which returns the first pin for auto-routing.
+          getPinnedTab(conversationId),
           sourceActorPrincipalId,
           targetClientId,
         );
@@ -484,6 +498,16 @@ export function buildChainedClient(
     kind: CdpClientKind;
     manager: BrowserSessionManager;
     sessionId: string;
+    /**
+     * Reference to the underlying CdpClient (returned from
+     * `candidate.create()`). Held so callers can reach methods that
+     * aren't routed through `manager.send()` — specifically
+     * {@link CdpClient.setCdpSessionId}, which re-targets follow-on
+     * CDP commands at a specific tab/target. Without this we'd have
+     * no way to call setCdpSessionId on the materialised client
+     * since `backend` only exposes the send/dispose surface.
+     */
+    client: CdpClient;
   } | null = null;
 
   /** Set to true after the first successful CDP command. */
@@ -491,6 +515,17 @@ export function buildChainedClient(
 
   let disposed = false;
 
+  /**
+   * setCdpSessionId may be called BEFORE the first send (i.e. before
+   * `active` is populated). When that happens we stash the value
+   * here and apply it to `active.client` as soon as a backend becomes
+   * sticky. In the current --new-tab flow this can't trigger (the
+   * createTab send establishes sticky first, then setCdpSessionId is
+   * called), but supporting the pre-sticky case keeps the contract
+   * simple for future callers.
+   */
+  let pendingCdpSessionId: string | undefined;
+
   /**
    * Track all materialised backends so dispose() can tear them all
    * down, even ones that were tried and failed before the sticky
@@ -545,6 +580,16 @@ export function buildChainedClient(
           active = established;
           sticky = true;
           currentKind = established.kind;
+          // Flush any pre-sticky setCdpSessionId call onto the
+          // freshly-materialised client. See pendingCdpSessionId
+          // comment above for why this exists.
+          if (
+            pendingCdpSessionId !== undefined &&
+            established.client.setCdpSessionId
+          ) {
+            established.client.setCdpSessionId(pendingCdpSessionId);
+            pendingCdpSessionId = undefined;
+          }
         },
         () => disposed,
         conversationId,
@@ -561,6 +606,115 @@ export function buildChainedClient(
       materialisedManagers.length = 0;
       active = null;
     },
+
+    /**
+     * Re-target follow-on CDP commands at a specific tab/target by
+     * updating the underlying client's `cdpSessionId`. The navigate
+     * executor calls this after `Vellum.createTab` returns so the
+     * subsequent `Page.navigate` (and every command on this
+     * conversation thereafter) routes to the new tab instead of the
+     * currently-active tab.
+     *
+     * Behaviour by state:
+     * - Sticky backend already established → forward to
+     *   `active.client.setCdpSessionId` if the underlying client
+     *   implements it (extension does; local/cdp-inspect don't and
+     *   the optional chain no-ops).
+     * - No sticky backend yet → stash the value; it gets applied
+     *   in the `onEstablished` callback when the first send walks
+     *   the candidate list.
+     */
+    setCdpSessionId(cdpSessionId: string | undefined): void {
+      if (active?.client.setCdpSessionId) {
+        active.client.setCdpSessionId(cdpSessionId);
+        return;
+      }
+      pendingCdpSessionId = cdpSessionId;
+    },
+
+    async listTabs(): Promise<TabInfo[]> {
+      if (sticky && active?.client.listTabs) {
+        return active.client.listTabs();
+      }
+      if (sticky) {
+        throw new CdpError(
+          "transport_error",
+          "listTabs is not supported by the current backend (extension backend required)",
+        );
+      }
+      // Fresh client: route through the failover walk so the extension
+      // backend is selected automatically. The Vellum.listTabs pseudo-method
+      // is handled by the extension dispatcher before chrome.debugger.sendCommand.
+      const result = await scopedClient.send<{ tabs?: TabInfo[] }>("Vellum.listTabs", {});
+      if (!active?.client.listTabs) {
+        // Backend became sticky but isn't an extension client — not supported.
+        throw new CdpError(
+          "transport_error",
+          "listTabs is not supported by the current backend (extension backend required)",
+        );
+      }
+      return Array.isArray(result?.tabs) ? result.tabs : [];
+    },
+
+    async selectTab(tabId: number): Promise<{
+      tabId?: number;
+      windowId?: number;
+      url?: string;
+      title?: string;
+      clientId?: string;
+    }> {
+      if (sticky && active?.client.selectTab) {
+        return active.client.selectTab(tabId);
+      }
+      if (sticky) {
+        throw new CdpError(
+          "transport_error",
+          "selectTab is not supported by the current backend (extension backend required)",
+        );
+      }
+      const result = await scopedClient.send<{
+        tabId?: number;
+        windowId?: number;
+        url?: string;
+        title?: string;
+        clientId?: string;
+      }>("Vellum.selectTab", { tabId });
+      if (!active?.client.selectTab) {
+        throw new CdpError(
+          "transport_error",
+          "selectTab is not supported by the current backend (extension backend required)",
+        );
+      }
+      return result;
+    },
+
+    async closeTab(tabId: number): Promise<{
+      closed: boolean;
+      tabId: number;
+      clientId?: string;
+    }> {
+      if (sticky && active?.client.closeTab) {
+        return active.client.closeTab(tabId);
+      }
+      if (sticky) {
+        throw new CdpError(
+          "transport_error",
+          "closeTab is not supported by the current backend (extension backend required)",
+        );
+      }
+      const result = await scopedClient.send<{
+        closed: boolean;
+        tabId: number;
+        clientId?: string;
+      }>("Vellum.closeTab", { tabId });
+      if (!active?.client.closeTab) {
+        throw new CdpError(
+          "transport_error",
+          "closeTab is not supported by the current backend (extension backend required)",
+        );
+      }
+      return result;
+    },
   };
 
   return scopedClient;
@@ -591,6 +745,7 @@ async function sendWithFailover<T>(
     kind: CdpClientKind;
     manager: BrowserSessionManager;
     sessionId: string;
+    client: CdpClient;
   }) => void,
   isDisposed: () => boolean,
   conversationId: string,
@@ -619,9 +774,16 @@ async function sendWithFailover<T>(
     );
 
     let backend: BrowserBackend;
+    let underlyingClient: CdpClient;
     try {
       const created = candidate.create();
       backend = created.backend;
+      // Hold the underlying CdpClient so we can forward
+      // setCdpSessionId calls to it after the backend becomes
+      // sticky. Without this the scopedClient's setCdpSessionId
+      // method has no way to reach the materialised client (the
+      // BrowserSessionManager only exposes a send/dispose surface).
+      underlyingClient = created.client;
     } catch (err) {
       // Backend construction failed -- treat as transport error and
       // try the next candidate.
@@ -810,7 +972,12 @@ async function sendWithFailover<T>(
       { conversationId, candidateKind: candidate.kind, method },
       "CDP factory: candidate succeeded, backend is now sticky",
     );
-    onEstablished({ kind: candidate.kind, manager, sessionId: session.id });
+    onEstablished({
+      kind: candidate.kind,
+      manager,
+      sessionId: session.id,
+      client: underlyingClient,
+    });
     return envelope.result as T;
   }
 

package/src/tools/browser/cdp-client/local-cdp-client.ts

@@ -156,6 +156,27 @@ export class LocalCdpClient implements ScopedCdpClient {
     }
   }
 
+  /**
+   * LocalCdpClient doesn't support re-targeting to a specific tab/session.
+   * The local Chromium instance manages all tabs globally, not per-client.
+   * This method is a no-op to satisfy the {@link ScopedCdpClient} interface.
+   */
+  setCdpSessionId(): void {
+    // no-op
+  }
+
+  async listTabs(): Promise<never> {
+    throw new CdpError("transport_error", "listTabs is not supported by the local backend (extension backend required)");
+  }
+
+  async selectTab(_tabId: number): Promise<never> {
+    throw new CdpError("transport_error", "selectTab is not supported by the local backend (extension backend required)");
+  }
+
+  async closeTab(_tabId: number): Promise<never> {
+    throw new CdpError("transport_error", "closeTab is not supported by the local backend (extension backend required)");
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;

package/src/tools/browser/cdp-client/types.ts

@@ -10,6 +10,16 @@
 
 import type { BrowserBackend } from "../../../browser-session/types.js";
 
+/** Shape of a single Chrome tab as returned by Vellum.listTabs. */
+export interface TabInfo {
+  tabId?: number;
+  windowId?: number;
+  url?: string;
+  title?: string;
+  active: boolean;
+  pinned: boolean;
+}
+
 export interface CdpClient {
   /**
    * Send a CDP command and await the result. `method` must be a
@@ -34,6 +44,52 @@ export interface CdpClient {
    * is allowed but should surface as an error.
    */
   dispose(): void;
+
+  /**
+   * Update the `cdpSessionId` used on subsequent {@link CdpClient.send}
+   * calls. Backends that don't multiplex commands across multiple
+   * targets (local Playwright, cdp-inspect) may implement this as a
+   * no-op. The extension backend uses this after opening a new tab
+   * (via the `Vellum.createTab` pseudo-CDP method) to route
+   * follow-on commands to the freshly-created tab instead of the
+   * currently-active one.
+   *
+   * Pass `undefined` to clear an existing pinned session and revert
+   * to default routing (i.e. dispatcher resolves the active tab).
+   * Used in the `Vellum.createTab` no-tabId fallback path to avoid
+   * sending follow-on commands to a stale/dead tab when the previous
+   * pin is no longer valid.
+   *
+   * Optional — callers should null-check before invoking.
+   */
+  setCdpSessionId?(cdpSessionId: string | undefined): void;
+
+  /**
+   * List all open browser tabs. Extension backend only — returns
+   * `{ tabId, windowId, url, title, active, pinned }[]`.
+   * Optional — callers must null-check before invoking.
+   */
+  listTabs?(): Promise<TabInfo[]>;
+
+  /**
+   * Select (activate) an existing tab. Extension backend only. Optional.
+   */
+  selectTab?(tabId: number): Promise<{
+    tabId?: number;
+    windowId?: number;
+    url?: string;
+    title?: string;
+    clientId?: string;
+  }>;
+
+  /**
+   * Close a browser tab by ID. Extension backend only. Optional.
+   */
+  closeTab?(tabId: number): Promise<{
+    closed: boolean;
+    tabId: number;
+    clientId?: string;
+  }>;
 }
 
 /**
@@ -97,6 +153,51 @@ export interface ScopedCdpClient extends CdpClient {
   readonly kind: CdpClientKind;
   /** Stable conversation id this client is bound to. */
   readonly conversationId: string;
+  /**
+   * Re-target follow-on CDP commands at a specific tab/target. Calling
+   * this updates the underlying client's `cdpSessionId`. This is used by
+   * the navigator executor after `Vellum.createTab` returns to ensure the
+   * subsequent `Page.navigate` and all follow-on commands on this
+   * conversation route to the newly-created tab instead of the
+   * previously-active tab.
+   *
+   * Pass `undefined` to clear an existing pinned session on the chained
+   * client and on the underlying client (if it supports the method).
+   * Used in the `Vellum.createTab` no-tabId fallback path.
+   *
+   * If the underlying client doesn't implement this method (e.g., local
+   * or cdp-inspect clients), the call is silently ignored via optional
+   * chaining.
+   */
+  setCdpSessionId(cdpSessionId: string | undefined): void;
+
+  /**
+   * List all open browser tabs. Throws with code "transport_error" if
+   * the current backend does not support tab listing.
+   */
+  listTabs(): Promise<TabInfo[]>;
+
+  /**
+   * Select (activate) an existing tab. Throws if backend doesn't support it.
+   */
+  selectTab(tabId: number): Promise<{
+    tabId?: number;
+    windowId?: number;
+    url?: string;
+    title?: string;
+    clientId?: string;
+  }>;
+
+  /**
+   * Close a browser tab by ID. Throws if backend doesn't support it.
+   * The optional `clientId` identifies which extension client actually
+   * closed the tab — used to scope pin cleanup in multi-client setups.
+   */
+  closeTab(tabId: number): Promise<{
+    closed: boolean;
+    tabId: number;
+    clientId?: string;
+  }>;
 }
 
 /**

package/src/tools/browser/pinned-tabs.ts

@@ -0,0 +1,146 @@
+/**
+ * Per-conversation, per-client pinned-tab store for the Chrome extension
+ * browser backend.
+ *
+ * Pin store key is (conversationId, clientId) → tabId. This scopes pins
+ * to a specific extension instance so that closing a tab on clientA does
+ * not clear clientB's pin to a tab with the same numeric ID on a
+ * different Chrome instance (issue #31361).
+ *
+ * Persistence is process-lifetime (in-memory only). The daemon is a
+ * single process and all CLI invocations land in it via IPC, so a
+ * module-level Map is sufficient. A pin is cleared when the extension
+ * reports the underlying CDP target as invalidated via
+ * `host_browser_session_invalidated`.
+ */
+
+import { log } from "../../cli/logger.js";
+
+const pinnedTabs = new Map<string, Map<string, string>>();
+
+/**
+ * Record a tabId as the pinned tab for the given conversation and optional
+ * client. The tabId is stored as a string because it travels on the wire
+ * as `cdpSessionId` (a string-typed field on the host-browser envelope).
+ */
+export function setPinnedTab(
+  conversationId: string,
+  tabId: string,
+  clientId?: string,
+): void {
+  if (!conversationId || !tabId) return;
+  const key = clientId ?? "__default__";
+  let inner = pinnedTabs.get(conversationId);
+  if (!inner) {
+    inner = new Map();
+    pinnedTabs.set(conversationId, inner);
+  }
+  inner.set(key, tabId);
+  log.debug(
+    { conversationId, clientId, tabId },
+    "Pinned extension tab for conversation",
+  );
+}
+
+/**
+ * Return the tabId pinned to the given conversation and optional client,
+ * or undefined if no pin exists.
+ *
+ * When `clientId` is provided, returns the pin for that client first,
+ * falling back to the `__default__` slot. When no `clientId` is given,
+ * returns the first entry (best-guess for auto-routing).
+ */
+export function getPinnedTab(
+  conversationId: string,
+  clientId?: string,
+): string | undefined {
+  if (!conversationId) return undefined;
+  const inner = pinnedTabs.get(conversationId);
+  if (!inner) return undefined;
+  if (clientId !== undefined) {
+    return inner.get(clientId) ?? inner.get("__default__");
+  }
+  // No clientId: return the first entry (best-guess for auto-routing)
+  const first = inner.values().next();
+  return first.done ? undefined : first.value;
+}
+
+/**
+ * Clear the pin for the given conversation and optional client. Idempotent
+ * — clearing a non-existent pin is a no-op.
+ *
+ * When `clientId` is provided, only clears that client's slot. When
+ * omitted, clears all client slots for the conversation.
+ */
+export function clearPinnedTab(
+  conversationId: string,
+  clientId?: string,
+): void {
+  if (!conversationId) return;
+  const inner = pinnedTabs.get(conversationId);
+  if (!inner) return;
+  if (clientId !== undefined) {
+    if (inner.delete(clientId)) {
+      log.debug({ conversationId, clientId }, "Cleared pinned extension tab");
+    }
+    if (inner.size === 0) pinnedTabs.delete(conversationId);
+  } else {
+    // Clear all clients for this conversation
+    if (pinnedTabs.delete(conversationId)) {
+      log.debug(
+        { conversationId },
+        "Cleared all pinned extension tabs for conversation",
+      );
+    }
+  }
+}
+
+/**
+ * Clear every pin pointing at a given tabId across all conversations.
+ * Used when the extension reports a target as invalidated (tab closed,
+ * crashed, navigated away from a debuggable URL, etc.) so we don't
+ * keep routing to a dead tab.
+ *
+ * When `clientId` is provided, only clears the slot for that client.
+ * When omitted, clears all entries pointing at this tabId (backward compat).
+ *
+ * Returns the number of slots cleared.
+ */
+export function clearPinnedTabByTabId(tabId: string, clientId?: string): number {
+  if (!tabId) return 0;
+  let cleared = 0;
+  for (const [conversationId, inner] of pinnedTabs.entries()) {
+    if (clientId !== undefined) {
+      // Only clear the specific client's slot if its tabId matches
+      if (inner.get(clientId) === tabId) {
+        inner.delete(clientId);
+        cleared++;
+        log.debug(
+          { conversationId, clientId, tabId },
+          "Cleared pinned extension tab due to invalidation",
+        );
+      }
+    } else {
+      // Backward compat: clear all entries pointing at this tabId
+      for (const [cid, pinned] of inner.entries()) {
+        if (pinned === tabId) {
+          inner.delete(cid);
+          cleared++;
+          log.debug(
+            { conversationId, clientId: cid, tabId },
+            "Cleared pinned extension tab due to invalidation",
+          );
+        }
+      }
+    }
+    if (inner.size === 0) pinnedTabs.delete(conversationId);
+  }
+  return cleared;
+}
+
+/**
+ * Reset the entire pin store. Test-only.
+ */
+export function __resetPinnedTabsForTests(): void {
+  pinnedTabs.clear();
+}