@vellumai/assistant 0.4.35 → 0.4.37

package/src/tools/browser/chrome-cdp.ts

@@ -0,0 +1,211 @@
+/**
+ * Shared Chrome CDP session management.
+ *
+ * Consolidates the duplicated launch / readiness / window-management logic
+ * that was previously copy-pasted across the Amazon and DoorDash CLIs.
+ * Callers get back a {@link CdpSession} with structured metadata so they can
+ * make cleanup decisions (e.g. only kill Chrome if *we* launched it).
+ */
+
+import { spawn as spawnChild } from "node:child_process";
+import { homedir } from "node:os";
+import { join as pathJoin } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CDP_PORT = 9222;
+const DEFAULT_CDP_BASE = `http://localhost:${DEFAULT_CDP_PORT}`;
+const DEFAULT_USER_DATA_DIR = pathJoin(
+  homedir(),
+  "Library/Application Support/Google/Chrome-CDP",
+);
+const CHROME_APP_PATH =
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CdpSession {
+  /** Base URL for the CDP HTTP endpoints (e.g. `http://localhost:9222`). */
+  baseUrl: string;
+  /** Whether this helper launched Chrome (true) or it was already running (false). */
+  launchedByUs: boolean;
+  /** The `--user-data-dir` used for the Chrome instance. */
+  userDataDir: string;
+}
+
+export interface EnsureChromeOptions {
+  /** CDP port. Defaults to `9222`. */
+  port?: number;
+  /** User data directory for Chrome. Defaults to `~/Library/Application Support/Google/Chrome-CDP`. */
+  userDataDir?: string;
+  /** Initial URL to open when launching Chrome. */
+  startUrl?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Readiness check
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when a CDP endpoint is responding at the given base URL.
+ */
+export async function isCdpReady(
+  cdpBase: string = DEFAULT_CDP_BASE,
+): Promise<boolean> {
+  try {
+    const res = await fetch(`${cdpBase}/json/version`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Launch / ensure
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure a Chrome instance with CDP is available. If one is already listening
+ * on the target port, returns immediately. Otherwise spawns a new detached
+ * Chrome process and waits for the CDP endpoint to become ready.
+ *
+ * Returns a {@link CdpSession} with metadata about the running instance.
+ */
+export async function ensureChromeWithCdp(
+  options: EnsureChromeOptions = {},
+): Promise<CdpSession> {
+  const port = options.port ?? DEFAULT_CDP_PORT;
+  const baseUrl = `http://localhost:${port}`;
+  const userDataDir = options.userDataDir ?? DEFAULT_USER_DATA_DIR;
+
+  if (await isCdpReady(baseUrl)) {
+    return { baseUrl, launchedByUs: false, userDataDir };
+  }
+
+  const args = [
+    `--remote-debugging-port=${port}`,
+    `--force-renderer-accessibility`,
+    `--user-data-dir=${userDataDir}`,
+  ];
+  if (options.startUrl) {
+    args.push(options.startUrl);
+  }
+
+  spawnChild(CHROME_APP_PATH, args, {
+    detached: true,
+    stdio: "ignore",
+  }).unref();
+
+  // Poll until CDP responds (up to 15 s)
+  for (let i = 0; i < 30; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (await isCdpReady(baseUrl)) {
+      return { baseUrl, launchedByUs: true, userDataDir };
+    }
+  }
+
+  throw new Error("Chrome started but CDP endpoint not responding after 15s");
+}
+
+// ---------------------------------------------------------------------------
+// Window management helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up the first page target and return its WebSocket debugger URL.
+ */
+async function findPageTarget(cdpBase: string): Promise<string | null> {
+  const res = await fetch(`${cdpBase}/json/list`);
+  const targets = (await res.json()) as Array<{
+    type: string;
+    webSocketDebuggerUrl: string;
+  }>;
+  const page = targets.find((t) => t.type === "page");
+  return page?.webSocketDebuggerUrl ?? null;
+}
+
+/**
+ * Set the window state of the Chrome window owning the first page target.
+ * Used by both minimize and restore.
+ */
+async function setWindowState(
+  cdpBase: string,
+  windowState: "minimized" | "normal",
+): Promise<void> {
+  const wsUrl = await findPageTarget(cdpBase);
+  if (!wsUrl) return;
+
+  const ws = new WebSocket(wsUrl);
+
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error(`CDP ${windowState} timed out`));
+    }, 5000);
+
+    ws.addEventListener("open", () => {
+      ws.send(JSON.stringify({ id: 1, method: "Browser.getWindowForTarget" }));
+    });
+
+    ws.addEventListener("message", (event) => {
+      const msg = JSON.parse(String(event.data)) as {
+        id: number;
+        result?: { windowId: number };
+        error?: { message: string };
+      };
+      if (msg.id === 1 && msg.result) {
+        ws.send(
+          JSON.stringify({
+            id: 2,
+            method: "Browser.setWindowBounds",
+            params: {
+              windowId: msg.result.windowId,
+              bounds: { windowState },
+            },
+          }),
+        );
+      } else if (msg.id === 1) {
+        clearTimeout(timeout);
+        ws.close();
+        reject(new Error("Browser.getWindowForTarget failed"));
+      } else if (msg.id === 2) {
+        clearTimeout(timeout);
+        ws.close();
+        if (msg.error) {
+          reject(
+            new Error(`Browser.setWindowBounds failed: ${msg.error.message}`),
+          );
+        } else {
+          resolve();
+        }
+      }
+    });
+
+    ws.addEventListener("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Minimize the Chrome window associated with the CDP session.
+ */
+export async function minimizeChromeWindow(
+  cdpBase: string = DEFAULT_CDP_BASE,
+): Promise<void> {
+  await setWindowState(cdpBase, "minimized");
+}
+
+/**
+ * Restore (un-minimize) the Chrome window associated with the CDP session.
+ */
+export async function restoreChromeWindow(
+  cdpBase: string = DEFAULT_CDP_BASE,
+): Promise<void> {
+  await setWindowState(cdpBase, "normal");
+}

package/src/tools/browser/network-recorder.test.ts

@@ -0,0 +1,83 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+} from "bun:test";
+
+// Mock the logger to avoid side effects during tests
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => ({
+    info: () => {},
+    debug: () => {},
+    warn: () => {},
+    error: () => {},
+  }),
+}));
+
+const { NetworkRecorder } = await import("./network-recorder.js");
+
+describe("NetworkRecorder", () => {
+  describe("startDirect CDP URL passthrough", () => {
+    const originalFetch = globalThis.fetch;
+    let fetchCalls: string[];
+
+    beforeEach(() => {
+      fetchCalls = [];
+      // Mock fetch to capture the URL and return a valid CDP version response.
+      globalThis.fetch = (async (url: string | URL | Request) => {
+        fetchCalls.push(String(url));
+        return new Response(
+          JSON.stringify({
+            webSocketDebuggerUrl: "ws://localhost:1234/devtools/browser/fake",
+          }),
+          { status: 200 },
+        );
+      }) as unknown as typeof fetch;
+    });
+
+    afterEach(() => {
+      globalThis.fetch = originalFetch;
+    });
+
+    // Safety net: restore fetch even if afterEach is skipped due to a test error
+    afterAll(() => {
+      globalThis.fetch = originalFetch;
+    });
+
+    it("uses constructor-provided cdpBaseUrl when called without arguments", async () => {
+      const customBase = "http://custom-host:9333";
+      const recorder = new NetworkRecorder(undefined, customBase);
+
+      // startDirect will fail at the WebSocket connect step, but we only
+      // care that fetch was called with the correct URL.
+      try {
+        await recorder.startDirect();
+      } catch {
+        // Expected — WebSocket connection will fail in test environment
+      }
+
+      expect(fetchCalls.length).toBeGreaterThanOrEqual(1);
+      expect(fetchCalls[0]).toBe(`${customBase}/json/version`);
+      expect(fetchCalls[0]).not.toContain("undefined");
+    });
+
+    it("uses explicit cdpBaseUrl argument when provided", async () => {
+      const constructorBase = "http://constructor-host:9222";
+      const explicitBase = "http://explicit-host:9444";
+      const recorder = new NetworkRecorder(undefined, constructorBase);
+
+      try {
+        await recorder.startDirect(explicitBase);
+      } catch {
+        // Expected — WebSocket connection will fail in test environment
+      }
+
+      expect(fetchCalls.length).toBeGreaterThanOrEqual(1);
+      expect(fetchCalls[0]).toBe(`${explicitBase}/json/version`);
+    });
+  });
+});

package/src/tools/browser/network-recorder.ts

@@ -18,8 +18,8 @@ const log = getLogger("network-recorder");
 /** Max response body size to capture (64 KB). */
 const MAX_BODY_SIZE = 64 * 1024;
 
-/** CDP endpoint to discover targets. */
-const CDP_BASE = "http://localhost:9222";
+/** Default CDP endpoint — used when no base URL is injected. */
+const DEFAULT_CDP_BASE = "http://localhost:9222";
 
 /**
  * Minimal CDP client over WebSocket — talks the Chrome DevTools Protocol directly
@@ -115,7 +115,7 @@ export class NetworkRecorder {
   private entries = new Map<string, NetworkRecordedEntry>();
   private targetDomain?: string;
   private running = false;
-  private cdpBaseUrl = CDP_BASE;
+  private cdpBaseUrl = DEFAULT_CDP_BASE;
   private attachedTargetIds = new Set<string>();
   private targetPollTimer?: ReturnType<typeof setInterval>;
 
@@ -130,20 +130,21 @@ export class NetworkRecorder {
     return this.entries.size;
   }
 
-  constructor(targetDomain?: string) {
+  constructor(targetDomain?: string, cdpBaseUrl?: string) {
     this.targetDomain = targetDomain;
+    if (cdpBaseUrl) this.cdpBaseUrl = cdpBaseUrl;
   }
 
   /**
    * Connect directly to Chrome's CDP endpoint and start recording network events.
    * Attaches to the browser-level target so events from all tabs are captured.
    */
-  async startDirect(cdpBaseUrl: string = CDP_BASE): Promise<void> {
+  async startDirect(cdpBaseUrl?: string): Promise<void> {
     if (this.running) return;
-    this.cdpBaseUrl = cdpBaseUrl;
+    if (cdpBaseUrl) this.cdpBaseUrl = cdpBaseUrl;
 
     // Discover the browser's WebSocket debugger URL
-    const versionRes = await fetch(`${cdpBaseUrl}/json/version`);
+    const versionRes = await fetch(`${this.cdpBaseUrl}/json/version`);
     const version = (await versionRes.json()) as {
       webSocketDebuggerUrl: string;
     };

package/src/tools/browser/x-auto-navigate.ts

@@ -9,7 +9,7 @@ import { getLogger } from "../../util/logger.js";
 
 const log = getLogger("x-auto-navigate");
 
-const CDP_BASE = "http://localhost:9222";
+const DEFAULT_CDP_BASE = "http://localhost:9222";
 
 interface NavStep {
   label: string;
@@ -71,19 +71,25 @@ class MiniCDP {
   }
 }
 
+export interface NavigateXPagesOptions {
+  abortSignal?: { aborted: boolean };
+  cdpBaseUrl?: string;
+}
+
 /**
  * Navigate Chrome through X.com pages to trigger GraphQL calls.
  * The NetworkRecorder should already be attached and capturing.
  *
- * @param abortSignal Optional signal to stop navigation early.
+ * @param options Optional configuration for abort and CDP base URL.
  * @returns List of step labels that completed successfully.
  */
-export async function navigateXPages(abortSignal?: {
-  aborted: boolean;
-}): Promise<string[]> {
+export async function navigateXPages(
+  options?: NavigateXPagesOptions,
+): Promise<string[]> {
+  const { abortSignal, cdpBaseUrl = DEFAULT_CDP_BASE } = options ?? {};
   let wsUrl: string | null = null;
   try {
-    const res = await fetch(`${CDP_BASE}/json/list`);
+    const res = await fetch(`${cdpBaseUrl}/json/list`);
     if (!res.ok) {
       log.warn("CDP not available for auto-navigation");
       return [];

package/src/tools/credentials/policy-types.ts

@@ -30,6 +30,19 @@ export interface CredentialPolicy {
 /** How a credential value is injected into an outbound proxied request. */
 export type CredentialInjectionType = "header" | "query";
 
+/** Reference to another credential whose value is composed with the primary value. */
+export interface CredentialComposeRef {
+  /** Service of the credential to compose with. */
+  service: string;
+  /** Field of the credential to compose with. */
+  field: string;
+  /** Separator between the primary and composed values (e.g. ":"). */
+  separator: string;
+}
+
+/** Transform applied to a credential value after composition. */
+export type CredentialValueTransform = "base64";
+
 /**
  * Describes where and how to inject a credential into proxied requests
  * matching a specific host pattern.
@@ -45,6 +58,17 @@ export interface CredentialInjectionTemplate {
   valuePrefix?: string;
   /** Query parameter name when injectionType is 'query'. */
   queryParamName?: string;
+  /**
+   * Compose this credential's value with another credential's value before injection.
+   * The result is `{primaryValue}{separator}{composedValue}`, optionally transformed
+   * by `valueTransform`.
+   */
+  composeWith?: CredentialComposeRef;
+  /**
+   * Transform applied to the (possibly composed) value before prepending `valuePrefix`.
+   * Applied after composition.
+   */
+  valueTransform?: CredentialValueTransform;
 }
 
 /** Input fields for specifying policy when storing a credential. */

package/src/tools/credentials/vault.ts

@@ -10,9 +10,7 @@ import type { ToolDefinition } from "../../providers/types.js";
 import type { TokenEndpointAuthMethod } from "../../security/oauth2.js";
 import {
   deleteSecureKey,
-  getBackendType,
   getSecureKey,
-  isDowngradedFromKeychain,
   listSecureKeys,
   setSecureKey,
 } from "../../security/secure-keys.js";
@@ -426,30 +424,21 @@ class CredentialStoreTool implements Tool {
         }
 
         const allMetadata = listCredentialMetadata();
-        // On the encrypted backend we can verify secrets still exist by reading
-        // all key names once (instead of per-entry getSecureKey calls that each
-        // re-read/re-derive the store). On keychain we trust metadata since the
-        // OS keychain has no batch list API.
-        // In downgraded mode (keychain failed, switched to encrypted), skip
-        // batch verification because listSecureKeys() only returns keys from
-        // the encrypted store — keychain-only credentials would be hidden.
-        const downgraded = isDowngradedFromKeychain();
-        const verifySecrets = getBackendType() === "encrypted" && !downgraded;
+        // Verify secrets still exist by reading all key names once (instead of
+        // per-entry getSecureKey calls that each re-read/re-derive the store).
         let secureKeySet: Set<string> | undefined;
-        if (verifySecrets) {
-          try {
-            secureKeySet = new Set(listSecureKeys());
-          } catch (err) {
-            log.error(
-              { err },
-              "Failed to read secure store while listing credentials",
-            );
-            return {
-              content:
-                "Error: failed to read secure storage; cannot list credentials",
-              isError: true,
-            };
-          }
+        try {
+          secureKeySet = new Set(listSecureKeys());
+        } catch (err) {
+          log.error(
+            { err },
+            "Failed to read secure store while listing credentials",
+          );
+          return {
+            content:
+              "Error: failed to read secure storage; cannot list credentials",
+            isError: true,
+          };
         }
         const entries = allMetadata
           .filter((m) => {
@@ -505,8 +494,14 @@ class CredentialStoreTool implements Tool {
         }
 
         const key = `credential:${service}:${field}`;
-        const ok = deleteSecureKey(key);
-        if (!ok) {
+        const result = deleteSecureKey(key);
+        if (result === "error") {
+          return {
+            content: `Error: failed to delete credential ${service}/${field} from secure storage`,
+            isError: true,
+          };
+        }
+        if (result === "not-found") {
           return {
             content: `Error: credential ${service}/${field} not found`,
             isError: true,

package/src/tools/network/script-proxy/session-manager.ts

@@ -32,6 +32,7 @@ import { listCredentialMetadata } from "../../credentials/metadata-store.js";
 import type { CredentialInjectionTemplate } from "../../credentials/policy-types.js";
 import {
   resolveById,
+  resolveByServiceField,
   type ResolvedCredential,
 } from "../../credentials/resolve.js";
 
@@ -92,6 +93,35 @@ const sessions = new Map<ProxySessionId, ManagedSession>();
  */
 const acquireLocks = new Map<string, Promise<ProxySession>>();
 
+/**
+ * Build the final header value for a matched credential injection template.
+ * Handles optional composition with a second credential and value transforms.
+ * Returns null if any referenced credential cannot be resolved.
+ */
+function buildInjectedValue(
+  tpl: CredentialInjectionTemplate,
+  primaryValue: string,
+): string | null {
+  let value = primaryValue;
+
+  if (tpl.composeWith) {
+    const composed = resolveByServiceField(
+      tpl.composeWith.service,
+      tpl.composeWith.field,
+    );
+    if (!composed) return null;
+    const composedValue = getSecureKey(composed.storageKey);
+    if (!composedValue) return null;
+    value = `${value}${tpl.composeWith.separator}${composedValue}`;
+  }
+
+  if (tpl.valueTransform === "base64") {
+    value = Buffer.from(value).toString("base64");
+  }
+
+  return (tpl.valuePrefix ?? "") + value;
+}
+
 /**
  * Resolve injection templates for a credential.
  *
@@ -295,8 +325,15 @@ export async function startSession(
             const value = getSecureKey(resolved.storageKey);
             if (!value) return req.headers;
 
-            req.headers[tpl.headerName.toLowerCase()] =
-              (tpl.valuePrefix ?? "") + value;
+            const headerValue = buildInjectedValue(tpl, value);
+            if (!headerValue) {
+              log.warn(
+                { host: req.hostname, credentialId: credId },
+                "MITM rewrite: blocking request — composeWith credential missing",
+              );
+              return null;
+            }
+            req.headers[tpl.headerName.toLowerCase()] = headerValue;
             return req.headers;
           }
 
@@ -377,7 +414,14 @@ export async function startSession(
         if (!value) return {};
 
         if (template.injectionType === "header" && template.headerName) {
-          const headerValue = (template.valuePrefix ?? "") + value;
+          const headerValue = buildInjectedValue(template, value);
+          if (!headerValue) {
+            log.warn(
+              { hostname, credentialId },
+              "Policy: blocking matched request — composeWith credential missing",
+            );
+            return null;
+          }
           return { [template.headerName.toLowerCase()]: headerValue };
         }
         // Query param injection is handled via URL rewriting in the MITM path

package/src/tools/permission-checker.ts

@@ -266,6 +266,7 @@ export class PermissionChecker {
           persistentDecisionsAllowed,
           context.signal,
           temporaryOptionsAvailable,
+          context.toolUseId,
         );
 
         const decision = response.decision;

package/src/tools/types.ts

@@ -167,6 +167,8 @@ export interface ToolContext {
   requesterChatId?: string;
   /** Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile. */
   channelPermissionChannelId?: string;
+  /** The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations. */
+  toolUseId?: string;
 }
 
 export interface DiffInfo {

package/src/tools/ui-surface/definitions.ts

@@ -61,8 +61,7 @@ export const uiShowTool: Tool = {
     "- Bulk actions: include `selectedRows` array with full row data for context\n\n" +
     "Presenting choices: When the user needs to make a choice or provide structured input, prefer interactive surfaces over plain text. " +
     "Use list (2-8 options, single select), form (structured input with typed fields), confirmation (destructive/important actions), or table (data review with selectable rows).\n\n" +
-    "Tool chaining: After gathering data via tools (web search, browser, APIs), synthesize results into a visual output. " +
-    "Exception: get_weather automatically renders its own surface with live API data — do NOT call ui_show, ui_update, app_create, or web_search after get_weather. Just respond with a brief summary.\n\n" +
+    "Tool chaining: After gathering data via tools (web search, browser, APIs), synthesize results into a visual output.\n\n" +
     'Task progress for multi-step workflows: Create a card with template "task_progress" and templateData containing steps. ' +
     "As each step completes, call ui_update to patch data.templateData (not top-level fields). " +
     'Set templateData.status to "completed" or "failed" when done.',

package/src/tools/watch/watch-state.ts

@@ -34,6 +34,8 @@ export interface WatchSession {
   recordingId?: string;
   /** Path where the learn recording was successfully saved (undefined if save failed) */
   savedRecordingPath?: string;
+  /** Reason the learn-mode bootstrap failed (CDP launch vs recorder attach) */
+  bootstrapFailureReason?: string;
 }
 
 /** Module-level map of watch sessions keyed by watchId. */