@vellumai/assistant 0.8.3 → 0.8.5

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/telemetry/types.ts

@@ -38,6 +38,18 @@ export interface LlmUsageTelemetryEvent extends TelemetryEventBase {
   output_tokens: number;
   cache_creation_input_tokens: number | null;
   cache_read_input_tokens: number | null;
+  /**
+   * The provider's untouched `usage` block. Anthropic surfaces a TTL
+   * breakdown under `cache_creation.ephemeral_{5m,1h}_input_tokens`;
+   * OpenAI surfaces cached-read counts under
+   * `prompt_tokens_details.cached_tokens` (and reasoning tokens under
+   * `completion_tokens_details`). Both shapes are forwarded verbatim so
+   * downstream consumers (admin charts, dbt models) can extract any
+   * provider-specific detail without requiring a schema change here.
+   * Null when the provider did not return a usage payload, and for
+   * daemons that predate `260-llm-usage-add-raw-usage`.
+   */
+  raw_usage: Record<string, unknown> | null;
   actor: string;
   llm_call_site: LLMCallSite | null;
   inference_profile: string | null;

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -159,6 +159,7 @@ function makeUsageEvent(
     outputTokens: 50,
     cacheCreationInputTokens: 10,
     cacheReadInputTokens: 5,
+    rawUsage: null,
     actor: "main_agent",
     callSite: null,
     inferenceProfile: null,
@@ -435,6 +436,53 @@ describe("UsageTelemetryReporter", () => {
     expect(e.inference_profile_source).toBe("conversation");
     expect(e.cost).toBe(0.001);
     expect(e.recorded_at).toBe(1700000099000);
+    // raw_usage defaults to null on this fixture (the makeUsageEvent default),
+    // confirming the wire shape carries the key as `null` rather than
+    // dropping it for legacy rows or providers that did not return a
+    // usage block.
+    expect(e.raw_usage).toBeNull();
+  });
+
+  test("payload forwards the provider's raw_usage block verbatim", async () => {
+    // The reporter must surface the literal usage object the provider
+    // returned (Anthropic nests TTL breakdown under `cache_creation`,
+    // OpenAI nests cached-read counts under `prompt_tokens_details`,
+    // etc.) so downstream consumers can extract any provider-specific
+    // detail without a wire-level schema change. Anything that
+    // transforms, summarises, or strips fields here destroys data the
+    // admin charts and dbt models depend on.
+    const rawUsage = {
+      input_tokens: 200,
+      output_tokens: 100,
+      cache_creation_input_tokens: 750,
+      cache_creation: {
+        ephemeral_5m_input_tokens: 250,
+        ephemeral_1h_input_tokens: 500,
+      },
+      cache_read_input_tokens: 15,
+      service_tier: "standard",
+    };
+    const event = makeUsageEvent({
+      id: "evt-raw-usage",
+      provider: "anthropic",
+      model: "claude-sonnet-4-20250514",
+      cacheCreationInputTokens: 750,
+      rawUsage,
+    });
+    mockQueryUnreportedUsageEvents.mockReturnValue([event]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":1}', { status: 200 })),
+    );
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    const e = body.events[0];
+    expect(e.cache_creation_input_tokens).toBe(750);
+    expect(e.raw_usage).toEqual(rawUsage);
   });
 
   test("payload preserves null attribution for historical usage rows", async () => {

package/src/telemetry/usage-telemetry-reporter.ts

@@ -234,6 +234,7 @@ export class UsageTelemetryReporter {
             output_tokens: e.outputTokens,
             cache_creation_input_tokens: e.cacheCreationInputTokens ?? null,
             cache_read_input_tokens: e.cacheReadInputTokens ?? null,
+            raw_usage: e.rawUsage,
             actor: e.actor,
             llm_call_site: e.callSite,
             inference_profile: e.inferenceProfile,