@vellumai/assistant 0.8.2 → 0.8.4

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

@@ -2382,4 +2382,32 @@ describe("macOS host-browser proxy without extension registry", () => {
     );
     expect(result).toEqual({ ok: true, via: "extension" });
   });
+  test("setCdpSessionId is forwarded to the underlying client through buildChainedClient", async () => {
+    // This test exercises the real chained-client path that integrates
+    // the extension CdpClient. Without it, the test suite would only ever
+    // instantiate getCdpClient(), which returns the scopedClient directly.
+    // buildChainedClient (used by the navigator executor) wraps that
+    // client and must forward setCdpSessionId calls to the underlying
+    // extension client — otherwise --new-tab would silently fail to
+    // re-target CDP commands.
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({ conversationId: "set-session-id-test" });
+    const client = getCdpClient(ctx);
+    // The scopedClient should expose setCdpSessionId (which it didn't
+    // before the fix).
+    expect(typeof client.setCdpSessionId).toBe("function");
+    // Call it; it should reach the underlying extension client without error.
+    // (The fake client's setCdpSessionId is a no-op in this test, but in
+    // production ExtensionCdpClient.setCdpSessionId updates cdpSessionId to
+    // re-target follow-on commands at a specific tab.)
+    const newTabId = "12345";
+    client.setCdpSessionId(newTabId);
+    // Verify the client is still functional after the session ID call.
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+      { url: "https://example.com" },
+    );
+    expect(result).toEqual({ ok: true, via: "extension" });
+  });
 });

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

@@ -88,6 +88,7 @@ describe("cdp-client re-exports", () => {
           throw new CdpError("disposed", "stub");
         },
         dispose: () => {},
+        setCdpSessionId: () => {},
       };
       expect(scoped.kind).toBe(kind);
       expect(scoped.conversationId).toBe("conv-123");

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

@@ -700,6 +700,16 @@ export class CdpInspectClient implements ScopedCdpClient {
     }
   }
 
+  /**
+   * CdpInspectClient doesn't support re-targeting to a specific tab/session.
+   * It connects directly to a remote CDP endpoint, which manages targets
+   * globally. This method is a no-op to satisfy the {@link ScopedCdpClient}
+   * interface.
+   */
+  setCdpSessionId(): void {
+    // no-op
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;

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

@@ -43,7 +43,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
   constructor(
     private readonly proxy: HostBrowserProxy,
     public readonly conversationId: string,
-    private readonly cdpSessionId?: string,
+    private cdpSessionId?: string,
     /**
      * Caller's actor principal id. When provided, the proxy will refuse to
      * dispatch this CDP command to a host_browser-capable client owned by a
@@ -182,6 +182,20 @@ export class ExtensionCdpClient implements ScopedCdpClient {
     // it here. In-flight requests will be cancelled by the AbortSignal
     // the tool passes in, or by conversation teardown.
   }
+
+  /**
+   * Update the `cdpSessionId` used on subsequent {@link send} calls.
+   *
+   * Used by the navigate executor after opening a new tab via the
+   * `Vellum.createTab` pseudo-CDP method: the returned tabId becomes
+   * this client's pinned target so the follow-on `Page.navigate`
+   * (and every command on this conversation thereafter) routes to
+   * the freshly-created tab instead of the user's currently-active
+   * tab.
+   */
+  setCdpSessionId(cdpSessionId: string | undefined): void {
+    this.cdpSessionId = cdpSessionId;
+  }
 }
 
 /**

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";
@@ -222,7 +223,14 @@ export function buildPinnedCandidateList(
             const client = createExtensionCdpClient(
               hostBrowserProxy,
               conversationId,
-              undefined,
+              // Conversation pins are scoped to "default routing on
+              // this conversation". When `target_client_id` is an
+              // explicit override, the caller is taking over routing
+              // and the pin (which may point at a tab on a different
+              // host client) must not be applied — otherwise we'd
+              // send tabId from host A to host B and get
+              // cdp_session_not_found.
+              targetClientId ? undefined : getPinnedTab(conversationId),
               sourceActorPrincipalId,
               targetClientId,
             );
@@ -330,6 +338,11 @@ export function buildCandidateList(context: ToolContext, targetClientId?: string
         kind: "extension",
         reason: `target_client_id override: ${targetClientId}`,
         create() {
+          // Explicit target_client_id override → ignore the
+          // conversation's pinned tab. Pins are conversation-scoped
+          // (not host-client-scoped) and would route a tabId from
+          // a different host to this one, producing
+          // cdp_session_not_found.
           const client = createExtensionCdpClient(
             hostBrowserProxy,
             conversationId,
@@ -358,7 +371,9 @@ export function buildCandidateList(context: ToolContext, targetClientId?: string
         const client = createExtensionCdpClient(
           hostBrowserProxy,
           conversationId,
-          undefined,
+          // See comment above the pinned-mode call site for why pins
+          // are skipped under explicit target_client_id override.
+          targetClientId ? undefined : getPinnedTab(conversationId),
           sourceActorPrincipalId,
           targetClientId,
         );
@@ -484,6 +499,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 +516,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 +581,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 +607,31 @@ 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;
+    },
   };
 
   return scopedClient;
@@ -591,6 +662,7 @@ async function sendWithFailover<T>(
     kind: CdpClientKind;
     manager: BrowserSessionManager;
     sessionId: string;
+    client: CdpClient;
   }) => void,
   isDisposed: () => boolean,
   conversationId: string,
@@ -619,9 +691,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 +889,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,15 @@ 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
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;

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

@@ -34,6 +34,25 @@ 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;
 }
 
 /**
@@ -97,6 +116,23 @@ 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;
 }
 
 /**

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

@@ -0,0 +1,90 @@
+/**
+ * Per-conversation pinned-tab store for the Chrome extension browser
+ * backend.
+ *
+ * When a navigate is issued with `new_tab: true`, the executor first
+ * asks the extension to open a fresh tab (via the `Vellum.createTab`
+ * pseudo-CDP method), then records the returned tabId here against the
+ * conversation. Subsequent CDP commands constructed for the same
+ * conversation pick up this tabId as the `cdpSessionId` on the
+ * outgoing envelope, which causes the extension's
+ * `resolveHostBrowserTarget` to route to that specific tab instead of
+ * falling back to `chrome.tabs.query({ active: true })`.
+ *
+ * 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 (see
+ * `consumeInvalidatedTargetId` in `browser-session/events.ts`) — that
+ * eviction is wired through `BrowserSessionManager.invalidateByTargetId`
+ * and the host-browser session-invalidated event route.
+ */
+
+import { log } from "../../cli/logger.js";
+
+const pinnedTabs = new Map<string, string>();
+
+/**
+ * Record a tabId as the pinned tab for the given conversation. 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): void {
+  if (!conversationId || !tabId) return;
+  pinnedTabs.set(conversationId, tabId);
+  log.debug(
+    { conversationId, tabId },
+    "Pinned extension tab for conversation",
+  );
+}
+
+/**
+ * Return the tabId pinned to the given conversation, or undefined if
+ * no pin exists.
+ */
+export function getPinnedTab(conversationId: string): string | undefined {
+  if (!conversationId) return undefined;
+  return pinnedTabs.get(conversationId);
+}
+
+/**
+ * Clear the pin for the given conversation. Idempotent — clearing a
+ * non-existent pin is a no-op.
+ */
+export function clearPinnedTab(conversationId: string): void {
+  if (!conversationId) return;
+  if (pinnedTabs.delete(conversationId)) {
+    log.debug({ conversationId }, "Cleared pinned extension tab");
+  }
+}
+
+/**
+ * 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.
+ *
+ * Returns the number of conversations whose pin was cleared.
+ */
+export function clearPinnedTabByTabId(tabId: string): number {
+  if (!tabId) return 0;
+  let cleared = 0;
+  for (const [conversationId, pinned] of pinnedTabs.entries()) {
+    if (pinned === tabId) {
+      pinnedTabs.delete(conversationId);
+      cleared++;
+      log.debug(
+        { conversationId, tabId },
+        "Cleared pinned extension tab due to invalidation",
+      );
+    }
+  }
+  return cleared;
+}
+
+/**
+ * Reset the entire pin store. Test-only.
+ */
+export function __resetPinnedTabsForTests(): void {
+  pinnedTabs.clear();
+}