@vellumai/assistant 0.8.2 → 0.8.4

package/src/security/oauth2-device-code.ts

@@ -0,0 +1,307 @@
+/**
+ * OAuth2 Device Authorization Grant (RFC 8628).
+ *
+ * Implements the device-code flow for environments where a browser redirect
+ * is impractical (CLI, headless). The user visits a verification URI and
+ * enters a short code; meanwhile, the client polls the token endpoint until
+ * authorization completes.
+ *
+ * This is intentionally separate from the PKCE authorization code flow in
+ * oauth2.ts — different grant type, different UX (no localhost server), and
+ * different polling lifecycle.
+ */
+
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("oauth2-device-code");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DeviceCodeConfig {
+  deviceCodeUrl: string;
+  tokenUrl: string;
+  clientId: string;
+  scopes: string[];
+  audience?: string;
+}
+
+export interface DeviceCodeInitResult {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresIn: number;
+  interval: number;
+}
+
+export interface DeviceCodeTokenResult {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  tokenType?: string;
+  scope?: string;
+}
+
+export class DeviceCodeError extends Error {
+  constructor(
+    message: string,
+    public readonly code:
+      | "expired_token"
+      | "access_denied"
+      | "request_failed"
+      | "aborted",
+  ) {
+    super(message);
+    this.name = "DeviceCodeError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Well-known provider configs
+// ---------------------------------------------------------------------------
+
+export const OPENAI_DEVICE_CODE_CONFIG: DeviceCodeConfig = {
+  deviceCodeUrl: "https://auth.openai.com/oauth/device/code",
+  tokenUrl: "https://auth.openai.com/oauth/token",
+  clientId: "app_EMoamEEZ73f0CkXaXp7hrann",
+  scopes: ["openid", "profile", "email", "offline_access"],
+  audience: "https://chatgpt.com",
+};
+
+// ---------------------------------------------------------------------------
+// Device code request
+// ---------------------------------------------------------------------------
+
+export async function requestDeviceCode(
+  config: DeviceCodeConfig,
+): Promise<DeviceCodeInitResult> {
+  const body: Record<string, string> = {
+    client_id: config.clientId,
+    scope: config.scopes.join(" "),
+  };
+  if (config.audience) {
+    body.audience = config.audience;
+  }
+
+  const resp = await fetch(config.deviceCodeUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: new URLSearchParams(body),
+  });
+
+  if (!resp.ok) {
+    const rawBody = await resp.text().catch(() => "");
+    log.error(
+      { status: resp.status, body: rawBody },
+      "Device code request failed",
+    );
+    throw new DeviceCodeError(
+      `Device code request failed (HTTP ${resp.status})`,
+      "request_failed",
+    );
+  }
+
+  const data = (await resp.json()) as Record<string, unknown>;
+
+  return {
+    deviceCode: data.device_code as string,
+    userCode: data.user_code as string,
+    verificationUri: data.verification_uri as string,
+    verificationUriComplete: data.verification_uri_complete as
+      | string
+      | undefined,
+    expiresIn: data.expires_in as number,
+    interval: (data.interval as number | undefined) ?? 5,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Token polling
+// ---------------------------------------------------------------------------
+
+/**
+ * Poll the token endpoint until the user completes authorization or the
+ * device code expires.
+ *
+ * Handles RFC 8628 error codes:
+ * - `authorization_pending` — keep polling
+ * - `slow_down` — increase interval by 5 seconds (per spec)
+ * - `expired_token` — abort with error
+ * - `access_denied` — abort with error
+ */
+export async function pollForToken(
+  config: DeviceCodeConfig,
+  deviceCode: string,
+  intervalSeconds: number,
+  expiresIn: number,
+  signal?: AbortSignal,
+  /** @internal Test-only: override the sleep function to avoid real delays. */
+  _sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>,
+): Promise<DeviceCodeTokenResult> {
+  const doSleep = _sleepFn ?? sleep;
+  let interval = intervalSeconds;
+  const deadline = Date.now() + expiresIn * 1000;
+
+  while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      throw new DeviceCodeError("Device code flow aborted", "aborted");
+    }
+
+    await doSleep(interval * 1000, signal);
+
+    if (signal?.aborted) {
+      throw new DeviceCodeError("Device code flow aborted", "aborted");
+    }
+
+    const body = new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: deviceCode,
+      client_id: config.clientId,
+    });
+
+    let resp: Response;
+    try {
+      resp = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body,
+        signal,
+      });
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new DeviceCodeError("Device code flow aborted", "aborted");
+      }
+      log.warn({ err }, "Token poll request failed, will retry");
+      continue;
+    }
+
+    const data = (await resp.json()) as Record<string, unknown>;
+
+    if (resp.ok) {
+      log.info("Device code authorization completed");
+      return {
+        accessToken: data.access_token as string,
+        refreshToken: data.refresh_token as string | undefined,
+        expiresIn: data.expires_in as number | undefined,
+        tokenType: data.token_type as string | undefined,
+        scope: data.scope as string | undefined,
+      };
+    }
+
+    const errorCode = data.error as string | undefined;
+
+    if (errorCode === "authorization_pending") {
+      log.debug("Authorization pending, continuing to poll");
+      continue;
+    }
+
+    if (errorCode === "slow_down") {
+      interval += 5;
+      log.info({ newInterval: interval }, "Received slow_down, increasing poll interval");
+      continue;
+    }
+
+    if (errorCode === "expired_token") {
+      throw new DeviceCodeError(
+        "Device code expired before user completed authorization",
+        "expired_token",
+      );
+    }
+
+    if (errorCode === "access_denied") {
+      throw new DeviceCodeError(
+        "User denied the authorization request",
+        "access_denied",
+      );
+    }
+
+    log.error(
+      { status: resp.status, error: errorCode },
+      "Unexpected token poll error",
+    );
+    throw new DeviceCodeError(
+      `Token poll failed: ${errorCode ?? `HTTP ${resp.status}`}`,
+      "request_failed",
+    );
+  }
+
+  throw new DeviceCodeError(
+    "Device code expired before user completed authorization",
+    "expired_token",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Combined flow
+// ---------------------------------------------------------------------------
+
+export interface DeviceCodeFlowResult {
+  tokens: DeviceCodeTokenResult;
+  init: DeviceCodeInitResult;
+}
+
+/**
+ * Run the full device-code flow:
+ * 1. Request a device code + user code
+ * 2. Return the user code and verification URI (caller shows these to the user)
+ * 3. Poll for the token
+ *
+ * The returned `init` contains the user code and verification URI that the
+ * caller should present to the user before awaiting `tokens`.
+ */
+export async function startDeviceCodeFlow(
+  config: DeviceCodeConfig,
+  signal?: AbortSignal,
+): Promise<DeviceCodeFlowResult> {
+  const init = await requestDeviceCode(config);
+
+  log.info(
+    {
+      verificationUri: init.verificationUri,
+      expiresIn: init.expiresIn,
+      interval: init.interval,
+    },
+    "Device code flow started",
+  );
+
+  const tokens = await pollForToken(
+    config,
+    init.deviceCode,
+    init.interval,
+    init.expiresIn,
+    signal,
+  );
+
+  return { tokens, init };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DeviceCodeError("Device code flow aborted", "aborted"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    if (typeof timer === "object" && "unref" in timer) timer.unref();
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DeviceCodeError("Device code flow aborted", "aborted"));
+      },
+      { once: true },
+    );
+  });
+}

package/src/security/oauth2.ts

@@ -86,6 +86,10 @@ export interface OAuth2FlowOptions {
    *  instead of an OS-assigned random port. Required for providers like Slack that
    *  need pre-registered redirect URIs. */
   loopbackPort?: number;
+  /** Override the loopback callback path. Defaults to `/oauth/callback`.
+   *  Required for providers with pre-registered redirect URIs that use a
+   *  different path (e.g. OpenAI Codex uses `/auth/callback`). */
+  loopbackCallbackPath?: string;
 }
 
 export interface OAuth2FlowResult {
@@ -98,15 +102,15 @@ export interface OAuth2FlowResult {
 // PKCE helpers
 // ---------------------------------------------------------------------------
 
-function generateCodeVerifier(): string {
+export function generateCodeVerifier(): string {
   return randomBytes(32).toString("base64url");
 }
 
-function generateCodeChallenge(verifier: string): string {
+export function generateCodeChallenge(verifier: string): string {
   return createHash("sha256").update(verifier).digest("base64url");
 }
 
-function generateState(): string {
+export function generateState(): string {
   return randomBytes(16).toString("hex");
 }
 
@@ -114,7 +118,7 @@ function generateState(): string {
 // Token exchange (shared between transports)
 // ---------------------------------------------------------------------------
 
-async function exchangeCodeForTokens(
+export async function exchangeCodeForTokens(
   config: OAuth2Config,
   code: string,
   redirectUri: string,
@@ -293,6 +297,7 @@ async function runLoopbackFlow(
   codeChallenge: string,
   state: string,
   loopbackPort?: number,
+  callbackPath?: string,
 ): Promise<OAuth2FlowResult> {
   const { code, redirectUri } = await startLoopbackServerAndWaitForCode(
     config,
@@ -300,6 +305,7 @@ async function runLoopbackFlow(
     codeChallenge,
     state,
     loopbackPort,
+    callbackPath,
   );
 
   return await exchangeCodeForTokens(config, code, redirectUri, codeVerifier);
@@ -317,7 +323,9 @@ function startLoopbackServerAndWaitForCode(
   codeChallenge: string,
   state: string,
   loopbackPort?: number,
+  callbackPath?: string,
 ): Promise<{ code: string; redirectUri: string }> {
+  const effectiveCallbackPath = callbackPath ?? LOOPBACK_CALLBACK_PATH;
   return new Promise((resolve, reject) => {
     let settled = false;
     let boundRedirectUri = "";
@@ -340,7 +348,7 @@ function startLoopbackServerAndWaitForCode(
 
       const url = new URL(req.url ?? "/", `http://127.0.0.1`);
 
-      if (url.pathname !== LOOPBACK_CALLBACK_PATH) {
+      if (url.pathname !== effectiveCallbackPath) {
         log.info(
           { pathname: url.pathname },
           "oauth2 loopback: non-callback path, returning 404",
@@ -426,7 +434,7 @@ function startLoopbackServerAndWaitForCode(
 
     server.listen(loopbackPort ?? 0, "localhost", () => {
       const addr = server.address() as { port: number };
-      boundRedirectUri = `http://localhost:${addr.port}${LOOPBACK_CALLBACK_PATH}`;
+      boundRedirectUri = `http://localhost:${addr.port}${effectiveCallbackPath}`;
 
       log.info(
         { port: addr.port, redirectUri: boundRedirectUri },
@@ -497,7 +505,11 @@ export async function prepareOAuth2Flow(
   const transport = options?.callbackTransport ?? "loopback";
 
   if (transport === "loopback") {
-    return prepareLoopbackFlow(config, options?.loopbackPort);
+    return prepareLoopbackFlow(
+      config,
+      options?.loopbackPort,
+      options?.loopbackCallbackPath,
+    );
   }
 
   // Dynamic imports required here to avoid circular dependencies with
@@ -555,6 +567,7 @@ export async function prepareOAuth2Flow(
 async function prepareLoopbackFlow(
   config: OAuth2Config,
   loopbackPort?: number,
+  callbackPath?: string,
 ): Promise<OAuth2PreparedFlow> {
   const codeVerifier = generateCodeVerifier();
   const codeChallenge = generateCodeChallenge(codeVerifier);
@@ -563,6 +576,7 @@ async function prepareLoopbackFlow(
   const { redirectUri, codePromise } = await startLoopbackServerForPreparedFlow(
     state,
     loopbackPort,
+    callbackPath,
   );
 
   const authParams = new URLSearchParams({
@@ -599,7 +613,9 @@ async function prepareLoopbackFlow(
 function startLoopbackServerForPreparedFlow(
   state: string,
   loopbackPort?: number,
+  callbackPath?: string,
 ): Promise<{ redirectUri: string; codePromise: Promise<string> }> {
+  const effectiveCallbackPath = callbackPath ?? LOOPBACK_CALLBACK_PATH;
   return new Promise((resolveSetup, rejectSetup) => {
     let settled = false;
     let listening = false;
@@ -619,7 +635,7 @@ function startLoopbackServerForPreparedFlow(
 
       const url = new URL(req.url ?? "/", `http://127.0.0.1`);
 
-      if (url.pathname !== LOOPBACK_CALLBACK_PATH) {
+      if (url.pathname !== effectiveCallbackPath) {
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");
         return;
@@ -683,7 +699,7 @@ function startLoopbackServerForPreparedFlow(
 
     server.listen(loopbackPort ?? 0, "localhost", () => {
       const addr = server.address() as { port: number };
-      const redirectUri = `http://localhost:${addr.port}${LOOPBACK_CALLBACK_PATH}`;
+      const redirectUri = `http://localhost:${addr.port}${effectiveCallbackPath}`;
       listening = true;
       resolveSetup({ redirectUri, codePromise });
     });
@@ -784,6 +800,7 @@ export async function startOAuth2Flow(
     codeChallenge,
     state,
     options?.loopbackPort,
+    options?.loopbackCallbackPath,
   );
 }
 

package/src/security/secure-keys.ts

@@ -113,6 +113,11 @@ const RECONNECT_COOLDOWN_MS = 3_000;
  */
 const CREDENTIAL_OP_TIMEOUT_MS = 45_000;
 
+/** Returns the current CES RPC client if one has been injected. */
+export function getCesClient(): CesClient | undefined {
+  return _cesClient;
+}
+
 /** Inject a CES RPC client for credential routing. Resets the resolved backend. */
 export function setCesClient(client: CesClient | undefined): void {
   _cesClient = client;

package/src/skills/catalog-install.ts

@@ -111,7 +111,9 @@ export async function fetchCatalog(): Promise<CatalogSkill[]> {
   if (!Array.isArray(manifest.skills)) {
     throw new Error("Platform catalog has invalid skills array");
   }
-  return manifest.skills;
+  return manifest.skills.filter(
+    (s): s is CatalogSkill => !!s && typeof s.id === "string",
+  );
 }
 
 export function readLocalCatalog(repoSkillsDir: string): CatalogSkill[] {
@@ -119,7 +121,9 @@ export function readLocalCatalog(repoSkillsDir: string): CatalogSkill[] {
     const raw = readFileSync(join(repoSkillsDir, "catalog.json"), "utf-8");
     const manifest = JSON.parse(raw) as CatalogManifest;
     if (!Array.isArray(manifest.skills)) return [];
-    return manifest.skills;
+    return manifest.skills.filter(
+      (s): s is CatalogSkill => !!s && typeof s.id === "string",
+    );
   } catch {
     return [];
   }

package/src/subagent/manager.ts

@@ -903,6 +903,8 @@ export class SubagentManager {
           subagentId: info.subagentId,
           label: info.label,
           status: "running" as const,
+          conversationId: managed.state.conversationId,
+          objective: managed.state.config.objective,
         },
       },
     );

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

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  __resetPinnedTabsForTests,
+  clearPinnedTab,
+  clearPinnedTabByTabId,
+  getPinnedTab,
+  setPinnedTab,
+} from "../pinned-tabs.js";
+
+describe("pinned-tabs", () => {
+  afterEach(() => {
+    __resetPinnedTabsForTests();
+  });
+
+  test("setPinnedTab / getPinnedTab round-trips", () => {
+    setPinnedTab("conv-a", "42");
+    expect(getPinnedTab("conv-a")).toBe("42");
+  });
+
+  test("getPinnedTab returns undefined for unset conversation", () => {
+    expect(getPinnedTab("unset-conv")).toBeUndefined();
+  });
+
+  test("conversations have independent pins", () => {
+    setPinnedTab("conv-a", "42");
+    setPinnedTab("conv-b", "99");
+    expect(getPinnedTab("conv-a")).toBe("42");
+    expect(getPinnedTab("conv-b")).toBe("99");
+  });
+
+  test("setPinnedTab overwrites a prior pin for the same conversation", () => {
+    setPinnedTab("conv-a", "42");
+    setPinnedTab("conv-a", "100");
+    expect(getPinnedTab("conv-a")).toBe("100");
+  });
+
+  test("clearPinnedTab removes the pin", () => {
+    setPinnedTab("conv-a", "42");
+    clearPinnedTab("conv-a");
+    expect(getPinnedTab("conv-a")).toBeUndefined();
+  });
+
+  test("clearPinnedTab on a non-existent conversation is a no-op", () => {
+    // Should not throw or affect other conversations.
+    setPinnedTab("conv-a", "42");
+    clearPinnedTab("nonexistent");
+    expect(getPinnedTab("conv-a")).toBe("42");
+  });
+
+  test("clearPinnedTabByTabId clears every matching conversation", () => {
+    setPinnedTab("conv-a", "42");
+    setPinnedTab("conv-b", "42");
+    setPinnedTab("conv-c", "99");
+
+    const cleared = clearPinnedTabByTabId("42");
+
+    expect(cleared).toBe(2);
+    expect(getPinnedTab("conv-a")).toBeUndefined();
+    expect(getPinnedTab("conv-b")).toBeUndefined();
+    expect(getPinnedTab("conv-c")).toBe("99"); // unchanged
+  });
+
+  test("clearPinnedTabByTabId on a non-matching tab is a no-op returning 0", () => {
+    setPinnedTab("conv-a", "42");
+    const cleared = clearPinnedTabByTabId("999");
+    expect(cleared).toBe(0);
+    expect(getPinnedTab("conv-a")).toBe("42");
+  });
+
+  test("empty conversationId is rejected on set", () => {
+    setPinnedTab("", "42");
+    expect(getPinnedTab("")).toBeUndefined();
+  });
+
+  test("empty tabId is rejected on set", () => {
+    setPinnedTab("conv-a", "");
+    expect(getPinnedTab("conv-a")).toBeUndefined();
+  });
+});

package/src/tools/browser/browser-execution.ts

@@ -70,6 +70,7 @@ import type {
   CdpClient,
   CdpClientKind,
 } from "./cdp-client/types.js";
+import { clearPinnedTab, setPinnedTab } from "./pinned-tabs.js";
 import { checkBrowserRuntime } from "./runtime-check.js";
 
 const log = getLogger("headless-browser");
@@ -471,6 +472,15 @@ function wrapWithKindMemo(
     dispose(): void {
       inner.dispose();
     },
+    // Proxy the optional setCdpSessionId through to the underlying
+    // client so the navigate executor's --new-tab path can pin the
+    // freshly-created tab onto the extension CDP client. We define
+    // the method unconditionally here (rather than only when the
+    // inner client implements it) so callers can use a simple optional
+    // chain on this wrapper without re-walking the inner reference.
+    setCdpSessionId(cdpSessionId: string): void {
+      inner.setCdpSessionId?.(cdpSessionId);
+    },
   };
 }
 
@@ -624,6 +634,89 @@ export async function executeBrowserNavigate(
   if (acquired.errorResult) return acquired.errorResult;
   const { cdp, browserMode } = acquired;
 
+  // --new-tab: open a fresh tab via the extension's Vellum.createTab
+  // pseudo-CDP method, then pin this client (and the conversation) to
+  // the returned tabId so this Page.navigate and every subsequent
+  // command on the same conversation routes to the new tab instead of
+  // the user's currently-active tab. Extension backend only; the local
+  // (Playwright) backend manages its own isolated browser and the
+  // cdp-inspect backend connects to a single tab by URL pattern.
+  const newTab = input.new_tab === true;
+  if (newTab && cdp.kind === "extension") {
+    try {
+      const result = await cdp.send<{ tabId?: number | string }>(
+        "Vellum.createTab",
+        {},
+        context.signal,
+      );
+      const tabId =
+        typeof result?.tabId === "number"
+          ? String(result.tabId)
+          : typeof result?.tabId === "string"
+            ? result.tabId
+            : undefined;
+      if (!tabId) {
+        // Malformed createTab response (no tabId). We're nominally falling
+        // back to active-tab routing — but the live `cdp` instance was
+        // already constructed with whatever pin was in scope for this
+        // conversation, AND the pin store still holds it for future
+        // client construction. Clear both: the pin store (so the next
+        // executeBrowserNavigate builds a clean client) AND the current
+        // cdp instance's session (so the Page.navigate that runs in a
+        // few lines targets the active tab rather than the stale pin).
+        // Without the setCdpSessionId(undefined) call, the warn message
+        // is a lie: navigation would still route to the dead tab via the
+        // already-injected cdpSessionId and likely fail with
+        // cdp_session_not_found.
+        clearPinnedTab(context.conversationId);
+        cdp.setCdpSessionId?.(undefined);
+        log.warn(
+          { conversationId: context.conversationId, result },
+          "Vellum.createTab returned no tabId; cleared stale pin and live session, falling back to active-tab routing",
+        );
+      } else {
+        cdp.setCdpSessionId?.(tabId);
+        setPinnedTab(context.conversationId, tabId);
+        log.debug(
+          { conversationId: context.conversationId, tabId },
+          "Opened new tab via --new-tab; pinned subsequent ops to it",
+        );
+      }
+    } catch (err) {
+      // Surface the failure rather than silently clobbering the active
+      // tab — that's exactly the behavior --new-tab is supposed to
+      // avoid. Clear any stale pin so subsequent ops don't route to a
+      // dead tab. Note: an old extension build without Vellum.createTab
+      // support will land here (CDP returns an "unknown method" error).
+      // We're early-returning before the main try/finally block below,
+      // so we must dispose the cdp client manually to avoid leaking it.
+      clearPinnedTab(context.conversationId);
+      const message =
+        err instanceof Error ? err.message : String(err);
+      log.warn(
+        { conversationId: context.conversationId, err },
+        "Vellum.createTab failed; aborting --new-tab navigate",
+      );
+      try {
+        cdp.dispose();
+      } catch (disposeErr) {
+        log.warn(
+          { conversationId: context.conversationId, err: disposeErr },
+          "Failed to dispose CDP client after Vellum.createTab failure",
+        );
+      }
+      return {
+        content: `Error: Failed to open a new tab for navigation: ${message}. The Chrome extension may need an update to support --new-tab.`,
+        isError: true,
+      };
+    }
+  } else if (newTab && cdp.kind !== "extension") {
+    log.debug(
+      { conversationId: context.conversationId, backendKind: cdp.kind },
+      "--new-tab requested but backend does not support it; ignoring",
+    );
+  }
+
   // Screencast + handoff are Playwright-backed and only meaningful
   // for the local sacrificial-profile path. On the extension path the
   // user already has their own Chrome window, so both are no-ops.