@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/oauth/connection-resolver.test.ts

@@ -6,6 +6,9 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 let mockProvider: Record<string, unknown> | undefined;
 let mockConnection: Record<string, unknown> | undefined;
+let mockConnections:
+  | Array<Record<string, unknown> & { clientId?: string; accountInfo?: string }>
+  | undefined;
 let mockAccessToken: string | undefined;
 let mockConfig: Record<string, unknown> = {};
 let mockPlatformClient: Record<string, unknown> | null = null;
@@ -24,15 +27,17 @@ mock.module("../util/logger.js", () => ({
 
 mock.module("./oauth-store.js", () => ({
   getProvider: () => mockProvider,
-  getActiveConnection: (
+  getActiveConnections: (
     _pk: string,
     opts?: { clientId?: string; account?: string },
   ) => {
-    if (opts?.clientId && mockConnection?.clientId !== opts.clientId)
-      return undefined;
-    if (opts?.account && mockConnection?.accountInfo !== opts.account)
-      return undefined;
-    return mockConnection;
+    // Default to the single mockConnection unless a test sets an explicit list.
+    const rows = mockConnections ?? (mockConnection ? [mockConnection] : []);
+    return rows.filter((row) => {
+      if (opts?.clientId && row.clientId !== opts.clientId) return false;
+      if (opts?.account && row.accountInfo !== opts.account) return false;
+      return true;
+    });
   },
 }));
 
@@ -131,6 +136,7 @@ function setupDefaults(): void {
       "google-oauth": { mode: "managed" },
     },
   };
+  mockConnections = undefined;
   mockPlatformClient = makeMockClient();
   syncManualTokenCalls = [];
 }
@@ -294,6 +300,140 @@ describe("resolveOAuthConnection", () => {
   });
 });
 
+describe("resolveOAuthConnection scope-awareness", () => {
+  const GMAIL_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
+  const CALENDAR_ONLY = [
+    "https://www.googleapis.com/auth/calendar.events",
+    "https://www.googleapis.com/auth/userinfo.email",
+  ];
+  const FULL_BUNDLE = [GMAIL_SCOPE, ...CALENDAR_ONLY];
+
+  function clientReturning(results: unknown[]) {
+    return {
+      ...makeMockClient(),
+      fetch: mock(
+        async () => new Response(JSON.stringify({ results }), { status: 200 }),
+      ),
+    };
+  }
+
+  beforeEach(() => {
+    setupDefaults();
+    mockProvider!.managedServiceConfigKey = "google-oauth";
+  });
+
+  test("managed: rejects a Calendar-only connection when Gmail scope is required", async () => {
+    mockPlatformClient = clientReturning([
+      { id: "cal-only", account_label: null, scopes_granted: CALENDAR_ONLY },
+    ]);
+
+    await expect(
+      resolveOAuthConnection("google", { requiredScopes: [GMAIL_SCOPE] }),
+    ).rejects.toThrow(/missing required access.*gmail\.readonly/s);
+  });
+
+  test("managed: resolves when a connection carries the required Gmail scope", async () => {
+    mockPlatformClient = clientReturning([
+      { id: "full", account_label: null, scopes_granted: FULL_BUNDLE },
+    ]);
+
+    const result = await resolveOAuthConnection("google", {
+      requiredScopes: [GMAIL_SCOPE],
+    });
+    expect(result).toBeInstanceOf(PlatformOAuthConnection);
+  });
+
+  test("managed: unknown scope data never blocks (back-compat)", async () => {
+    // Older connections report no scopes_granted — must not be rejected.
+    mockPlatformClient = clientReturning([
+      { id: "legacy", account_label: null },
+    ]);
+
+    const result = await resolveOAuthConnection("google", {
+      requiredScopes: [GMAIL_SCOPE],
+    });
+    expect(result).toBeInstanceOf(PlatformOAuthConnection);
+  });
+
+  test("managed: prefers a scope-satisfying connection over a narrow one", async () => {
+    const fullClient = clientReturning([
+      { id: "cal-only", account_label: null, scopes_granted: CALENDAR_ONLY },
+      { id: "full", account_label: null, scopes_granted: FULL_BUNDLE },
+    ]);
+    mockPlatformClient = fullClient;
+
+    const result = await resolveOAuthConnection("google", {
+      requiredScopes: [GMAIL_SCOPE],
+    });
+    expect(result).toBeInstanceOf(PlatformOAuthConnection);
+    // PlatformOAuthConnection is keyed by provider, so assert resolution
+    // succeeded (it would have thrown if only the narrow connection matched).
+    expect(result.provider).toBe("google");
+  });
+
+  test("managed: no requiredScopes preserves prior behavior", async () => {
+    mockPlatformClient = clientReturning([
+      { id: "cal-only", account_label: null, scopes_granted: CALENDAR_ONLY },
+    ]);
+
+    const result = await resolveOAuthConnection("google");
+    expect(result).toBeInstanceOf(PlatformOAuthConnection);
+  });
+
+  test("BYO: rejects when granted scopes are known and missing the requirement", async () => {
+    (mockConfig.services as Record<string, unknown>)["google-oauth"] = {
+      mode: "your-own",
+    };
+    mockConnection!.grantedScopes = JSON.stringify(CALENDAR_ONLY);
+
+    await expect(
+      resolveOAuthConnection("google", { requiredScopes: [GMAIL_SCOPE] }),
+    ).rejects.toThrow(/missing required access/);
+  });
+
+  test("BYO: unknown granted scopes never block", async () => {
+    (mockConfig.services as Record<string, unknown>)["google-oauth"] = {
+      mode: "your-own",
+    };
+    mockConnection!.grantedScopes = JSON.stringify([]);
+
+    const result = await resolveOAuthConnection("google", {
+      requiredScopes: [GMAIL_SCOPE],
+    });
+    expect(result).toBeInstanceOf(BYOOAuthConnection);
+  });
+
+  test("BYO: picks an older scope-satisfying connection over a newer narrow one", async () => {
+    (mockConfig.services as Record<string, unknown>)["google-oauth"] = {
+      mode: "your-own",
+    };
+    // Newest first (matching the store's ordering): a Calendar-only row, then
+    // an older row that carries the Gmail scope. The narrow row must not win.
+    mockConnections = [
+      {
+        id: "cal-only",
+        provider: "google",
+        accountInfo: "user@example.com",
+        grantedScopes: JSON.stringify(CALENDAR_ONLY),
+        status: "active",
+      },
+      {
+        id: "full",
+        provider: "google",
+        accountInfo: "user@example.com",
+        grantedScopes: JSON.stringify(FULL_BUNDLE),
+        status: "active",
+      },
+    ];
+
+    const result = await resolveOAuthConnection("google", {
+      requiredScopes: [GMAIL_SCOPE],
+    });
+    expect(result).toBeInstanceOf(BYOOAuthConnection);
+    expect(result.id).toBe("full");
+  });
+});
+
 describe("resolveEffectiveBaseUrl", () => {
   const fallback = "https://login.salesforce.com";
 

package/src/oauth/connection-resolver.ts

@@ -10,8 +10,9 @@ import { BYOOAuthConnection } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
 import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
 import { syncManualTokenConnection } from "./manual-token-connection.js";
-import { getActiveConnection, getProvider } from "./oauth-store.js";
+import { getActiveConnections, getProvider } from "./oauth-store.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
+import { scopeDifference } from "./scope-utils.js";
 
 const log = getLogger("connection-resolver");
 
@@ -23,6 +24,17 @@ export interface ResolveOAuthConnectionOptions {
    *  accounts are connected for the same provider. Best-effort: not guaranteed
    *  to be present on all connections. */
   account?: string;
+  /**
+   * Scopes the caller needs the connection to actually carry. A single provider
+   * key can bundle several products behind one OAuth app (notably Google: Gmail
+   * + Calendar + Drive), and a connection may have been granted only a subset.
+   * When set, resolution prefers a connection whose granted scopes cover these,
+   * and fails with an actionable "reconnect to grant X" error — instead of
+   * returning a token that 403s downstream — when the only active connection(s)
+   * positively lack a required scope. Scope data that is simply unknown never
+   * blocks (see {@link selectConnectionByScopes}).
+   */
+  requiredScopes?: string[];
 }
 
 /**
@@ -46,7 +58,7 @@ export async function resolveOAuthConnection(
   provider: string,
   options?: ResolveOAuthConnectionOptions,
 ): Promise<OAuthConnection> {
-  const { clientId, account } = options ?? {};
+  const { clientId, account, requiredScopes } = options ?? {};
   const providerRow = getProvider(provider);
   const managedKey = providerRow?.managedServiceConfigKey;
 
@@ -68,6 +80,7 @@ export async function resolveOAuthConnection(
         client,
         provider,
         account,
+        requiredScopes,
       });
 
       return new PlatformOAuthConnection({
@@ -87,8 +100,8 @@ export async function resolveOAuthConnection(
     await syncManualTokenConnection(provider);
   }
 
-  const conn = getActiveConnection(provider, { clientId, account });
-  if (!conn) {
+  const candidates = getActiveConnections(provider, { clientId, account });
+  if (candidates.length === 0) {
     const filters = [
       account && `account "${account}"`,
       clientId && `client ID "${clientId}"`,
@@ -101,6 +114,25 @@ export async function resolveOAuthConnection(
     );
   }
 
+  // Scope guard: when the caller needs specific scopes, pick a connection that
+  // actually carries them rather than blindly taking the newest row — a user
+  // may hold several active connections (e.g. one Calendar-only, one full).
+  // Only fail when EVERY active connection positively lacks a required scope;
+  // unknown scope data never blocks. Without requiredScopes, behavior is
+  // unchanged: take the most-recently-created connection.
+  let conn = candidates[0];
+  if (requiredScopes?.length) {
+    const { eligible, missingScopes } = partitionByScopes(
+      candidates,
+      requiredScopes,
+      (row) => parseGrantedScopes(row.grantedScopes),
+    );
+    if (eligible.length === 0) {
+      throw new Error(missingScopesMessage(provider, missingScopes));
+    }
+    conn = eligible[0];
+  }
+
   const tokenResult = await getConnectionAccessTokenResult({
     provider,
     connectionId: conn.id,
@@ -188,11 +220,15 @@ interface ResolvePlatformConnectionIdOptions {
   client: VellumPlatformClient;
   provider: string;
   account?: string;
+  requiredScopes?: string[];
 }
 
 interface PlatformConnectionEntry {
   id: string;
   account_label?: string | null;
+  /** Scopes the platform actually granted this connection. May be absent for
+   *  older connections or providers that don't report scopes. */
+  scopes_granted?: string[] | null;
 }
 
 /**
@@ -241,7 +277,7 @@ async function fetchPlatformConnections(options: {
 async function resolvePlatformConnectionId(
   options: ResolvePlatformConnectionIdOptions,
 ): Promise<string> {
-  const { client, provider, account } = options;
+  const { client, provider, account, requiredScopes } = options;
 
   let connections = await fetchPlatformConnections({
     client,
@@ -268,6 +304,26 @@ async function resolvePlatformConnectionId(
     );
   }
 
+  // Narrow to connections that actually carry the scopes the caller needs.
+  // This is what keeps a narrowly-scoped Google connection (e.g. Calendar-only,
+  // created by the onboarding check-in flow) from being resolved as a full
+  // Gmail connection and 403-ing on the first Gmail API call.
+  if (requiredScopes?.length) {
+    const { eligible, missingScopes } = partitionByScopes(
+      connections,
+      requiredScopes,
+      (c) => c.scopes_granted ?? [],
+    );
+    if (eligible.length === 0) {
+      log.warn(
+        { provider, count: connections.length, requiredScopes, missingScopes },
+        "Active platform connection(s) found but none carry the required scopes",
+      );
+      throw new Error(missingScopesMessage(provider, missingScopes));
+    }
+    connections = eligible;
+  }
+
   if (connections.length > 1 && !account) {
     const allAccounts = connections
       .map((c) => c.account_label ?? c.id)
@@ -286,3 +342,74 @@ async function resolvePlatformConnectionId(
 
   return connections[0].id;
 }
+
+/**
+ * Partition connections into those eligible to serve a request needing
+ * `requiredScopes` versus the scopes positively missing across all of them.
+ *
+ * Scope data can be absent (older connections, providers that don't report
+ * granted scopes). We only ever REJECT a connection when we can positively see
+ * its granted-scope set AND that set is missing a required scope — never when
+ * scope data is simply unknown. This keeps the check from breaking existing
+ * working connections while still catching the real failure mode: a narrowly-
+ * scoped connection masquerading as a fully-capable one.
+ *
+ * `eligible` is ordered scope-satisfying first, then scope-unknown, preserving
+ * the caller's most-recent-first ordering within each group, so `eligible[0]`
+ * is the best connection to use. `missingScopes` is only meaningful when
+ * `eligible` is empty (every connection positively lacked a required scope).
+ */
+function partitionByScopes<T>(
+  items: T[],
+  requiredScopes: string[],
+  getGranted: (item: T) => string[],
+): { eligible: T[]; missingScopes: string[] } {
+  const satisfying: T[] = [];
+  const scopeUnknown: T[] = [];
+  const missingPerItem: string[][] = [];
+
+  for (const item of items) {
+    const granted = getGranted(item);
+    if (granted.length === 0) {
+      // Unknown scope coverage — don't block on it.
+      scopeUnknown.push(item);
+      continue;
+    }
+    const missing = scopeDifference(requiredScopes, granted);
+    if (missing.length === 0) {
+      satisfying.push(item);
+    } else {
+      missingPerItem.push(missing);
+    }
+  }
+
+  return {
+    eligible: [...satisfying, ...scopeUnknown],
+    missingScopes: Array.from(new Set(missingPerItem.flat())),
+  };
+}
+
+/** Best-effort parse of a connection row's JSON-encoded granted-scopes column. */
+function parseGrantedScopes(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed)
+      ? parsed.filter((s): s is string => typeof s === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Actionable error shown when a connection is missing required scopes. */
+function missingScopesMessage(
+  provider: string,
+  missingScopes: string[],
+): string {
+  return (
+    `Your ${provider} account is connected but is missing required access ` +
+    `(${missingScopes.join(", ")}). Reconnect ${provider} and grant the ` +
+    `missing permission to continue.`
+  );
+}

package/src/oauth/oauth-store.ts

@@ -821,6 +821,20 @@ export function getActiveConnection(
   provider: string,
   options?: { clientId?: string; account?: string },
 ): OAuthConnectionRow | undefined {
+  return getActiveConnections(provider, options)[0];
+}
+
+/**
+ * Like {@link getActiveConnection}, but returns ALL matching active connections
+ * (most-recently-created first) instead of just the newest. Callers that must
+ * choose among multiple connections — e.g. picking the one that carries a
+ * specific set of granted scopes — use this; `getActiveConnection` is the
+ * single-result convenience over the same query.
+ */
+export function getActiveConnections(
+  provider: string,
+  options?: { clientId?: string; account?: string },
+): OAuthConnectionRow[] {
   const { clientId, account } = options ?? {};
   const db = getDb();
 
@@ -835,7 +849,7 @@ export function getActiveConnection(
 
   if (clientId) {
     const app = getAppByProviderAndClientId(provider, clientId);
-    if (!app) return undefined;
+    if (!app) return [];
     conditions.push(eq(oauthConnections.oauthAppId, app.id));
   }
 
@@ -844,8 +858,7 @@ export function getActiveConnection(
     .from(oauthConnections)
     .where(and(...conditions))
     .orderBy(desc(oauthConnections.createdAt), sql`rowid DESC`)
-    .limit(1)
-    .get();
+    .all();
 }
 
 /** @deprecated Use {@link getActiveConnection} instead. */

package/src/oauth/scope-utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared helpers for reasoning about OAuth scope coverage.
+ *
+ * A single provider key can bundle several products behind one OAuth app
+ * (notably Google: Gmail + Calendar + Drive + Contacts). A connection may be
+ * granted only a subset of those scopes, so callers that need a specific
+ * capability must compare what they require against what was actually granted
+ * rather than treating any active connection as fully capable.
+ */
+
+/**
+ * Return the required scopes that are NOT present in the granted set.
+ * An empty result means every required scope is granted.
+ */
+export function scopeDifference(
+  required: string[],
+  granted: string[],
+): string[] {
+  const grantedSet = new Set(granted);
+  return required.filter((s) => !grantedSet.has(s));
+}

package/src/plugin-api/index.ts

@@ -20,8 +20,8 @@
  * the host hands to plugin hooks, and the logger shape they include.
  *
  * Alongside those types, the module exposes a small set of **runtime
- * handles** for plugins that need to reach the assistant's live singletons
- * (subscribe to runtime events, read secrets). These resolve to the
+ * handles for plugins that need to reach the assistant's live singletons
+ * (subscribe to runtime events, inspect inference profiles). These resolve to the
  * assistant's own instances: the host parks the loaded plugin-api namespace
  * on `globalThis` at boot, and the workspace-level shim re-binds each
  * runtime export from there — so a plugin's
@@ -31,7 +31,6 @@
  * disjoint module copy.
  *
  * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
- * - {@link getSecureKeyAsync} — read a secret from secure storage
  * - {@link getModelProfiles} — list the workspace inference profiles a plugin
  *   can route to (e.g. a model router building its category → profile map)
  * - {@link getConfiguredProvider} — resolve a {@link Provider} for a call site
@@ -130,8 +129,14 @@ export type {
   AssistantEventSubscription,
 } from "../runtime/assistant-event-hub.js";
 export { assistantEventHub } from "../runtime/assistant-event-hub.js";
-export { getSecureKeyAsync } from "../security/secure-keys.js";
 export { getModelProfiles } from "./model-profiles.js";
+// Check whether a profile's resolved model can process image input. Resolves
+// the effective (provider, model) by merging over the workspace default and
+// inferring the provider for model-only profiles, then looks up the model
+// catalog's `supportsVision` flag. Handles mix profiles (true if any arm
+// supports vision). Fail-open for unknown models. Pair with
+// `getModelProfiles()` to inspect the active or candidate profiles.
+export { doesSupportVision } from "./vision-support.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.

package/src/plugin-api/model-profiles.test.ts

@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ─── Mock config ────────────────────────────────────────────────────────────
+
+interface MockProfileEntry {
+  label?: string;
+  description?: string;
+  provider?: string;
+  model?: string;
+  status?: string;
+  mix?: unknown;
+}
+
+let mockProfiles: Record<string, MockProfileEntry> = {};
+let mockActiveProfile: string | undefined;
+let mockProfileOrder: string[] | undefined;
+
+const realConfigLoader = await import("../config/loader.js");
+
+mock.module("../config/loader.js", () => ({
+  ...realConfigLoader,
+  getConfig: () => ({
+    llm: {
+      profiles: mockProfiles,
+      activeProfile: mockActiveProfile,
+      profileOrder: mockProfileOrder,
+    },
+  }),
+  getConfigReadOnly: () => ({
+    llm: {
+      profiles: mockProfiles,
+      activeProfile: mockActiveProfile,
+      profileOrder: mockProfileOrder,
+    },
+  }),
+}));
+
+const { getModelProfiles } = await import("./model-profiles.js");
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  mockProfiles = {};
+  mockActiveProfile = undefined;
+  mockProfileOrder = undefined;
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("getModelProfiles", () => {
+  test("returns all configured profiles in order", () => {
+    mockProfiles = {
+      balanced: { label: "Balanced", provider: "anthropic" },
+      "quality-optimized": { label: "Quality", provider: "anthropic" },
+    };
+    mockProfileOrder = ["balanced", "quality-optimized"];
+
+    const result = getModelProfiles();
+    expect(result.map((p) => p.key)).toEqual(["balanced", "quality-optimized"]);
+  });
+
+  test("includes disabled profiles (flagged via isDisabled)", () => {
+    mockProfiles = {
+      balanced: { label: "Balanced", provider: "anthropic" },
+      disabled: {
+        label: "Disabled",
+        provider: "anthropic",
+        status: "disabled",
+      },
+    };
+
+    const result = getModelProfiles();
+    expect(result).toHaveLength(2);
+    const disabled = result.find((p) => p.key === "disabled");
+    expect(disabled?.isDisabled).toBe(true);
+  });
+
+  test("flags mix profiles via isMix", () => {
+    mockProfiles = {
+      "mix-profile": {
+        label: "Mix",
+        mix: [{ profile: "balanced", weight: 1 }],
+      },
+    };
+
+    const result = getModelProfiles();
+    expect(result[0].isMix).toBe(true);
+  });
+
+  test("skips metadata-only profiles that cannot route plugin calls", () => {
+    mockProfiles = {
+      metadata: { label: "Metadata Only" },
+      "model-only": { label: "Model Only", model: "claude-opus-4-6" },
+      "provider-only": { label: "Provider Only", provider: "anthropic" },
+      mix: {
+        label: "Mix",
+        mix: [{ profile: "model-only", weight: 1 }],
+      },
+    };
+    mockProfileOrder = ["metadata", "model-only", "provider-only", "mix"];
+
+    const result = getModelProfiles();
+    expect(result.map((p) => p.key)).toEqual([
+      "model-only",
+      "provider-only",
+      "mix",
+    ]);
+  });
+
+  test("marks the active profile with isActive", () => {
+    mockProfiles = {
+      balanced: { label: "Balanced", provider: "anthropic" },
+      "quality-optimized": { label: "Quality", provider: "anthropic" },
+    };
+    mockActiveProfile = "balanced";
+
+    const result = getModelProfiles();
+    expect(result.find((p) => p.key === "balanced")?.isActive).toBe(true);
+    expect(result.find((p) => p.key === "quality-optimized")?.isActive).toBe(
+      false,
+    );
+  });
+});

package/src/plugin-api/model-profiles.ts

@@ -1,11 +1,14 @@
 import { getConfig } from "../config/loader.js";
+import { isDispatchableProfile } from "../config/profile-dispatchability.js";
 import { orderProfileKeys } from "../config/profile-order.js";
 import type { ModelProfileInfo } from "./types.js";
 
 /**
  * List the workspace inference profiles a plugin can route to, in the order the
  * `/model` picker presents them (`llm.profileOrder` first, then the rest
- * alphabetically). Disabled profiles are included and flagged via
+ * alphabetically). Metadata-only entries without a provider, model, or mix are
+ * not routing targets, so plugins never see them. Disabled profiles are
+ * included and flagged via
  * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
  * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
  * routing target (it resolves to one constituent per conversation).
@@ -20,6 +23,7 @@ export function getModelProfiles(): ModelProfileInfo[] {
   for (const key of orderProfileKeys(profiles, llm.profileOrder)) {
     const entry = profiles[key];
     if (entry == null) continue;
+    if (!isDispatchableProfile(entry)) continue;
     result.push({
       key,
       label: entry.label ?? key,