@vellumai/assistant 0.11.2-dev.202608050137.0c8f50a → 0.11.2-dev.202608050309.fa8263f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608050137.0c8f50a",
+  "version": "0.11.2-dev.202608050309.fa8263f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/oauth-provider-profiles.test.ts

@@ -23,7 +23,7 @@ describe("oauth provider profiles (DB-seeded)", () => {
     );
   });
 
-  test("google provider row contains bearer injection templates for 4 Google API hosts", () => {
+  test("google provider row contains bearer injection templates for 6 Google API hosts", () => {
     const provider = getProvider("google");
 
     expect(provider).toBeDefined();
@@ -36,7 +36,7 @@ describe("oauth provider profiles (DB-seeded)", () => {
       valuePrefix: string;
     }>;
 
-    expect(templates).toHaveLength(4);
+    expect(templates).toHaveLength(6);
 
     const byHost = new Map(templates.map((t) => [t.hostPattern, t]));
 
@@ -45,6 +45,8 @@ describe("oauth provider profiles (DB-seeded)", () => {
       "www.googleapis.com",
       "people.googleapis.com",
       "docs.googleapis.com",
+      "tasks.googleapis.com",
+      "calendar.googleapis.com",
     ]) {
       const tpl = byHost.get(host);
       expect(tpl).toBeDefined();

package/src/__tests__/ui-choice-copy-surfaces.test.ts

@@ -204,6 +204,7 @@ describe("choice and copy_block surface proxying", () => {
       providerKey: "google",
       displayName: "Google",
       description: "Connect Gmail for this task.",
+      requestedScopes: ["gmail.readonly"],
     });
     expect(ctx.pendingSurfaceActions.get(showMessage.surfaceId)).toEqual({
       surfaceType: "oauth_connect",

package/src/api/surfaces-oauth-connect.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  type OAuthConnectSurfaceData,
+  OAuthConnectSurfaceDataSchema,
+} from "./surfaces.js";
+
+describe("OAuthConnectSurfaceDataSchema requestedScopes", () => {
+  test("parses a valid scopes array and preserves order", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [
+        "https://www.googleapis.com/auth/tasks",
+        "https://www.googleapis.com/auth/calendar",
+        "openid",
+      ],
+    });
+    expect(parsed.requestedScopes).toEqual([
+      "https://www.googleapis.com/auth/tasks",
+      "https://www.googleapis.com/auth/calendar",
+      "openid",
+    ]);
+  });
+
+  test("absent requestedScopes parses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("an empty array collapses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [],
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("non-array values collapse to undefined instead of rejecting", () => {
+    for (const value of [
+      "https://www.googleapis.com/auth/tasks, openid",
+      42,
+      true,
+      { scope: "openid" },
+      null,
+    ]) {
+      const parsed = OAuthConnectSurfaceDataSchema.parse({
+        providerKey: "google",
+        requestedScopes: value,
+      });
+      expect(parsed.requestedScopes).toBeUndefined();
+    }
+  });
+
+  test("an array of blanks collapses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: ["", "   ", "\t"],
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("entries are trimmed and blank or non-string junk is dropped", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [
+        "  https://www.googleapis.com/auth/tasks  ",
+        "",
+        null,
+        { nope: true },
+        "openid",
+      ],
+    });
+    expect(parsed.requestedScopes).toEqual([
+      "https://www.googleapis.com/auth/tasks",
+      "openid",
+    ]);
+  });
+
+  test("a bare string is not split on commas (scopes are opaque URIs)", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: "a,b,c",
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("legacy payload { providerKey: 'google' } still parses (skew guard)", () => {
+    const parsed: OAuthConnectSurfaceData = OAuthConnectSurfaceDataSchema.parse(
+      { providerKey: "google" },
+    );
+    expect(parsed.providerKey).toBe("google");
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+});

package/src/api/surfaces.ts

@@ -120,6 +120,21 @@ export const CardSurfaceDataSchema = z.object({
 });
 export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;
 
+/**
+ * Stringify+trim entries, drop blanks and non-scalars, and collapse an
+ * empty result to `undefined` so a schema treats it as "field absent".
+ */
+function cleanedStringEntries(items: unknown[]): string[] | undefined {
+  const cleaned = items
+    .map((item) =>
+      typeof item === "string" || typeof item === "number"
+        ? String(item).trim()
+        : "",
+    )
+    .filter((item) => item.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
 /**
  * Accepted MIME-type / extension patterns for a `file_upload` surface.
  *
@@ -137,14 +152,7 @@ const FileUploadAcceptedTypesSchema = z.preprocess((value) => {
       : Array.isArray(value)
         ? value
         : [];
-  const cleaned = items
-    .map((item) =>
-      typeof item === "string" || typeof item === "number"
-        ? String(item).trim()
-        : "",
-    )
-    .filter((item) => item.length > 0);
-  return cleaned.length > 0 ? cleaned : undefined;
+  return cleanedStringEntries(items);
 }, z.array(z.string()).optional());
 
 export const FileUploadSurfaceDataSchema = z.object({
@@ -238,6 +246,19 @@ export const ChoiceSurfaceDataSchema = z.object({
 });
 export type ChoiceSurfaceData = z.infer<typeof ChoiceSurfaceDataSchema>;
 
+/**
+ * Requested OAuth scopes for an `oauth_connect` surface.
+ *
+ * Unlike `FileUploadAcceptedTypesSchema`, a bare string is NOT split on
+ * commas: OAuth scopes are opaque URIs, so only arrays are accepted.
+ * Entries are stringified and trimmed, blanks are dropped, and an empty
+ * result or any non-array value collapses to `undefined` (use defaults).
+ */
+const RequestedScopesSchema = z.preprocess(
+  (value) => (Array.isArray(value) ? cleanedStringEntries(value) : undefined),
+  z.array(z.string()).optional(),
+);
+
 export const OAuthConnectSurfaceDataSchema = z.object({
   /** OAuth provider key from the managed provider catalog, e.g. "google". */
   providerKey: z
@@ -246,6 +267,13 @@ export const OAuthConnectSurfaceDataSchema = z.object({
       z.string(),
     )
     .catch(""),
+  /**
+   * Optional OAuth scopes to request for the managed connection. A full
+   * replacement set: when present, the platform uses exactly these scopes
+   * instead of its defaults (it does not merge). Omit to use the platform's
+   * default scopes for the provider.
+   */
+  requestedScopes: RequestedScopesSchema,
   /** Optional display label. The client falls back to the provider catalog. */
   displayName: tolerantString(),
   /** Optional helper text. The client falls back to the provider catalog. */

package/src/cli/commands/oauth/connect-surface-guidance.test.ts

@@ -36,5 +36,21 @@ describe("OAuth connect surface guidance", () => {
     expect(hint).toContain('surface_type "oauth_connect"');
     expect(hint).toContain('data.providerKey "google"');
     expect(hint).toContain("paste an OAuth URL");
+    expect(hint).not.toContain("requestedScopes");
+  });
+
+  test("hint with scopes teaches the full replacement set semantics", () => {
+    const hint = oauthConnectSurfaceHint("google", ["a", "b"]);
+    expect(hint).toContain("data.requestedScopes");
+    expect(hint).toContain("full replacement set");
+  });
+
+  test("redirect with scopes carries requestedScopes in the next action", () => {
+    const redirect = buildOAuthConnectSurfaceRedirect("google", ["a", "b"]);
+    expect(redirect.nextAction.data).toEqual({
+      providerKey: "google",
+      requestedScopes: ["a", "b"],
+    });
+    expect(redirect.hint).toBe(oauthConnectSurfaceHint("google", ["a", "b"]));
   });
 });

package/src/cli/commands/oauth/connect-surface-guidance.ts

@@ -1,7 +1,9 @@
+import type { OAuthConnectSurfaceData } from "../../../api/surfaces.js";
+
 export interface OAuthConnectSurfaceNextAction {
   type: "ui_show";
   surfaceType: "oauth_connect";
-  data: { providerKey: string };
+  data: Pick<OAuthConnectSurfaceData, "providerKey" | "requestedScopes">;
 }
 
 export interface OAuthConnectSurfaceRedirect {
@@ -12,35 +14,51 @@ export interface OAuthConnectSurfaceRedirect {
   nextAction: OAuthConnectSurfaceNextAction;
 }
 
-export function oauthConnectSurfaceHint(provider: string): string {
-  return (
+export function oauthConnectSurfaceHint(
+  provider: string,
+  requestedScopes?: string[],
+): string {
+  const base =
     `To let the user connect, render the connect button: call ` +
     `\`ui_show\` with surface_type "oauth_connect" and ` +
     `data.providerKey "${provider}". That surface is always available — do ` +
     `not run further \`oauth\`/\`channels\` commands, paste an OAuth URL, or ` +
-    `load a setup skill just to display it.`
+    `load a setup skill just to display it.`;
+  if (!requestedScopes?.length) {
+    return base;
+  }
+  return (
+    base +
+    ` Include data.requestedScopes verbatim from nextAction.data in the ` +
+    `\`ui_show\` call: it is a full replacement set, so list every default ` +
+    `scope you want to keep, not just the new ones.`
   );
 }
 
 export function buildOAuthConnectSurfaceNextAction(
   provider: string,
+  requestedScopes?: string[],
 ): OAuthConnectSurfaceNextAction {
   return {
     type: "ui_show",
     surfaceType: "oauth_connect",
-    data: { providerKey: provider },
+    data: {
+      providerKey: provider,
+      ...(requestedScopes?.length ? { requestedScopes } : {}),
+    },
   };
 }
 
 export function buildOAuthConnectSurfaceRedirect(
   provider: string,
+  requestedScopes?: string[],
 ): OAuthConnectSurfaceRedirect {
   return {
     ok: false,
     code: "use_oauth_connect_surface",
     provider,
-    hint: oauthConnectSurfaceHint(provider),
-    nextAction: buildOAuthConnectSurfaceNextAction(provider),
+    hint: oauthConnectSurfaceHint(provider, requestedScopes),
+    nextAction: buildOAuthConnectSurfaceNextAction(provider, requestedScopes),
   };
 }
 

package/src/cli/commands/oauth/connect.test.ts

@@ -70,7 +70,7 @@ afterEach(() => {
   process.exitCode = 0;
 });
 
-async function runConnectCommand(): Promise<{
+async function runConnectCommand(extraArgs: string[] = []): Promise<{
   stdout: string;
   exitCode: number;
 }> {
@@ -94,6 +94,7 @@ async function runConnectCommand(): Promise<{
       "--json",
       "connect",
       "google",
+      ...extraArgs,
     ]);
   } catch {
     // Commander may throw under exitOverride for parse errors; the assertions
@@ -123,4 +124,28 @@ describe("oauth connect", () => {
       "oauth_mode_get",
     ]);
   });
+
+  test("managed provider in a conversation shell includes requested scopes in the oauth_connect guidance", async () => {
+    const { stdout, exitCode } = await runConnectCommand([
+      "--scopes",
+      "https://www.googleapis.com/auth/tasks",
+      "https://www.googleapis.com/auth/calendar",
+    ]);
+
+    expect(exitCode).toBe(1);
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+    expect(parsed.code).toBe("use_oauth_connect_surface");
+    expect(parsed.nextAction).toEqual({
+      type: "ui_show",
+      surfaceType: "oauth_connect",
+      data: {
+        providerKey: "google",
+        requestedScopes: [
+          "https://www.googleapis.com/auth/tasks",
+          "https://www.googleapis.com/auth/calendar",
+        ],
+      },
+    });
+    expect(openedUrls).toEqual([]);
+  });
 });

package/src/cli/commands/oauth/connect.ts

@@ -141,7 +141,10 @@ export function registerConnectCommand(oauth: Command): void {
             // =============================================================
 
             if (isModelSpawnedConversationShell()) {
-              const redirect = buildOAuthConnectSurfaceRedirect(provider);
+              const redirect = buildOAuthConnectSurfaceRedirect(
+                provider,
+                opts.scopes,
+              );
               writeOutput(cmd, redirect);
               process.exitCode = 1;
               return;

package/src/cli/commands/oauth/index.help.ts

@@ -691,7 +691,9 @@ Important for chat/UI turns: do not run this command just to let the user
 connect a managed provider. Render the first-class connect surface instead:
 call \`ui_show\` with surface_type "oauth_connect" and data.providerKey set to
 the provider (for example, "google"). That surface starts the managed OAuth UI
-and avoids pasting raw authorization links into the conversation.
+and avoids pasting raw authorization links into the conversation. If the user
+needs non-default scopes, also pass data.requestedScopes as a full replacement
+set (list every scope the connection should keep, not just the new ones).
 
 Examples:
   $ assistant oauth connect google

package/src/oauth/seed-providers.ts

@@ -137,6 +137,18 @@ export const PROVIDER_SEED_DATA: Record<
         headerName: "Authorization",
         valuePrefix: "Bearer ",
       },
+      {
+        hostPattern: "tasks.googleapis.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+      {
+        hostPattern: "calendar.googleapis.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
     ],
     revokeUrl: "https://oauth2.googleapis.com/revoke",
     revokeBodyTemplate: { token: "{access_token}" },

package/src/tools/ui-surface/surface-shape-docs.ts

@@ -132,7 +132,7 @@ export const SURFACE_SHAPE_DOCS: Record<string, SurfaceShapeDoc> = {
   oauth_connect: {
     purpose: "managed OAuth connection button for an integration account",
     shape:
-      "{ providerKey, displayName?, description?, logoUrl? } — managed OAuth connection CTA; use when the task needs a managed integration account (Google, Linear, GitHub, ...) instead of settings or shell OAuth. Do not include OAuth scopes; managed providers use the platform's configured scopes",
+      "{ providerKey, requestedScopes?, displayName?, description?, logoUrl? }: managed OAuth connection CTA; use when the task needs a managed integration account (Google, Linear, GitHub, ...) instead of settings or shell OAuth. requestedScopes is an optional FULL replacement set of OAuth scopes: when set, the connection is granted exactly these scopes instead of the platform defaults, so include every scope the connection should keep; omit it to use the platform's default scopes",
     missingContent: (data) =>
       isNonEmptyString(data.providerKey)
         ? null