@vellumai/assistant 0.5.11 → 0.5.13

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

@@ -14,7 +14,7 @@ import {
 } from "../../../oauth/oauth-store.js";
 import { VellumPlatformClient } from "../../../platform/client.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
-import { isManagedMode, resolveService, toBareProvider } from "./shared.js";
+import { isManagedMode } from "./shared.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -86,12 +86,9 @@ export function registerRequestCommand(oauth: Command): void {
   oauth
     .command("request <url>")
     .description(
-      "Make an authenticated OAuth request (curl-like interface for LLM agents)",
-    )
-    .requiredOption(
-      "--provider <key>",
-      "Provider key (e.g. integration:google) or alias (e.g. gmail)",
+      "The recommended way to make an authenticated request to an OAuth provider (supports a curl-like interface)",
     )
+    .requiredOption("--provider <key>", "Provider name (e.g. google, slack)")
     .option("-X, --request <method>", "HTTP method (default: GET)")
     .option(
       "-H, --header <header>",
@@ -114,9 +111,13 @@ export function registerRequestCommand(oauth: Command): void {
     .addHelpText(
       "after",
       `
-Make authenticated HTTP requests through an OAuth provider. Resolves the
-OAuth connection automatically (platform-managed or BYO) and injects
-tokens transparently.
+This is the first-class mechanism for making authenticated HTTP requests
+to an OAuth provider. By using this CLI, you follow security best-practices
+regarding how the OAuth token is used. This approach is preferred over retrieving
+the token (using \`assistant oauth token\`) and making the request directly.
+
+This command resolves the OAuth connection automatically (regardless of whether
+the provider's mode is set to "managed" or "your-own") and injects tokens transparently.
 
 URL can be absolute (https://api.twitter.com/2/tweets) or relative (/2/tweets).
 Absolute URLs have their host extracted as a baseUrl override; relative paths
@@ -126,11 +127,11 @@ Note: The Authorization header is set automatically. User-supplied
 -H "Authorization: ..." will be overridden by the OAuth bearer token.
 
 Examples:
-  $ assistant oauth request --provider integration:twitter https://api.x.com/2/tweets
-  $ assistant oauth request --provider gmail /gmail/v1/users/me/messages -G
-  $ assistant oauth request --provider integration:twitter -X POST -d '{"text":"Hello"}' https://api.x.com/2/tweets
-  $ assistant oauth request --provider integration:google -d @body.json https://www.googleapis.com/calendar/v3/calendars
-  $ assistant oauth request --provider integration:slack -H "Content-Type: application/json" -d '{"channel":"C123"}' /api/chat.postMessage --json`,
+  $ assistant oauth request --provider twitter https://api.x.com/2/tweets
+  $ assistant oauth request --provider google /gmail/v1/users/me/messages -G
+  $ assistant oauth request --provider twitter -X POST -d '{"text":"Hello"}' https://api.x.com/2/tweets
+  $ assistant oauth request --provider google -d @body.json https://www.googleapis.com/calendar/v3/calendars
+  $ assistant oauth request --provider slack -H "Content-Type: application/json" -d '{"channel":"C123"}' /api/chat.postMessage --json`,
     )
     .action(
       async (
@@ -173,18 +174,13 @@ Examples:
         };
 
         try {
-          // -----------------------------------------------------------------
-          // 1. Resolve provider key
-          // -----------------------------------------------------------------
-          const providerKey = resolveService(opts.provider);
-
           // -----------------------------------------------------------------
           // Pre-flight check 1: Provider not found
           // -----------------------------------------------------------------
-          const providerRow = getProvider(providerKey);
+          const providerRow = getProvider(opts.provider);
           if (!providerRow) {
             writeError(
-              `Error: Unknown provider "${providerKey}".\n\n` +
+              `Error: Unknown provider "${opts.provider}".\n\n` +
                 `Run 'assistant oauth providers list' to see available providers.\n` +
                 `If this is a custom provider, register it first with 'assistant oauth providers register --help'.`,
             );
@@ -194,7 +190,7 @@ Examples:
           // -----------------------------------------------------------------
           // Pre-flight check 2: Determine managed vs BYO mode
           // -----------------------------------------------------------------
-          const managed = isManagedMode(providerKey);
+          const managed = isManagedMode(opts.provider);
 
           // -----------------------------------------------------------------
           // Pre-flight check 3: Client ID not found (BYO only)
@@ -202,16 +198,16 @@ Examples:
           if (opts.clientId) {
             if (managed) {
               writeInfo(
-                `Warning: --client-id is ignored for platform-managed providers. The platform manages OAuth apps for "${providerKey}".`,
+                `Warning: --client-id is ignored for platform-managed providers. The platform manages OAuth apps for "${opts.provider}".`,
               );
             } else {
               const app = getAppByProviderAndClientId(
-                providerKey,
+                opts.provider,
                 opts.clientId,
               );
               if (!app) {
                 writeError(
-                  `Error: No registered OAuth app found for "${providerKey}" with client ID "${opts.clientId}".\n\n` +
+                  `Error: No registered OAuth app found for "${opts.provider}" with client ID "${opts.clientId}".\n\n` +
                     `Run 'assistant oauth apps list' to see registered apps for this provider.\n` +
                     `To register a new app, run 'assistant oauth apps upsert --help'.`,
                 );
@@ -229,7 +225,7 @@ Examples:
               const client = await VellumPlatformClient.create();
               if (client && client.platformAssistantId) {
                 const params = new URLSearchParams();
-                params.set("provider", toBareProvider(providerKey));
+                params.set("provider", opts.provider);
                 params.set("status", "ACTIVE");
                 params.set("account_identifier", opts.account);
 
@@ -246,8 +242,8 @@ Examples:
 
                   if (connections.length === 0) {
                     writeError(
-                      `Error: No active platform connection found for "${providerKey}" with account "${opts.account}".\n\n` +
-                        `Run 'assistant oauth status ${providerKey}' to see connected accounts for this provider.\n` +
+                      `Error: No active platform connection found for "${opts.provider}" with account "${opts.account}".\n\n` +
+                        `Run 'assistant oauth status ${opts.provider}' to see connected accounts for this provider.\n` +
                         `To connect a new account, run 'assistant oauth connect --help'.`,
                     );
                     return;
@@ -259,14 +255,14 @@ Examples:
                 );
               }
             } else {
-              const conn = getActiveConnection(providerKey, {
+              const conn = getActiveConnection(opts.provider, {
                 clientId: opts.clientId,
                 account: opts.account,
               });
               if (!conn) {
                 writeError(
-                  `Error: No active OAuth connection found for "${providerKey}" with account "${opts.account}"${opts.clientId ? ` and client ID "${opts.clientId}"` : ""}.\n\n` +
-                    `Run 'assistant oauth status ${providerKey}' to see active connections.\n` +
+                  `Error: No active OAuth connection found for "${opts.provider}" with account "${opts.account}"${opts.clientId ? ` and client ID "${opts.clientId}"` : ""}.\n\n` +
+                    `Run 'assistant oauth status ${opts.provider}' to see active connections.\n` +
                     `To connect a new account, run 'assistant oauth connect --help'.`,
                 );
                 return;
@@ -418,7 +414,7 @@ Examples:
           let connection;
           try {
             connection = await resolveOAuthConnection(
-              providerKey,
+              opts.provider,
               resolveOptions,
             );
           } catch (resolveErr) {
@@ -434,13 +430,13 @@ Examples:
             if (managed) {
               writeError(
                 `Error: ${resolveMessage}\n\n` +
-                  `Run 'assistant oauth status ${providerKey}' to check connection status.\n` +
+                  `Run 'assistant oauth status ${opts.provider}' to check connection status.\n` +
                   `To connect, run 'assistant oauth connect --help'.`,
               );
             } else {
               writeError(
                 `Error: ${resolveMessage}\n\n` +
-                  `Run 'assistant oauth status ${providerKey}' to see active connections.\n` +
+                  `Run 'assistant oauth status ${opts.provider}' to see active connections.\n` +
                   `To connect, run 'assistant oauth connect --help'.`,
               );
             }
@@ -473,12 +469,12 @@ Examples:
             if (managed) {
               authHint =
                 `Hint: Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-                `Run 'assistant oauth status ${providerKey}' to check connection health.\n` +
+                `Run 'assistant oauth status ${opts.provider}' to check connection health.\n` +
                 `To reconnect, run 'assistant oauth connect --help'.`;
             } else {
               authHint =
                 `Hint: Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-                `Run 'assistant oauth status ${providerKey}' to check connection status.\n` +
+                `Run 'assistant oauth status ${opts.provider}' to check connection status.\n` +
                 `To reconnect, run 'assistant oauth connect --help'.`;
             }
             writeInfo(authHint);
@@ -535,14 +531,6 @@ Examples:
           // Error case 7: Generic/unexpected errors
           const message = err instanceof Error ? err.message : String(err);
 
-          // Try to extract providerKey for the generic hint
-          let providerKey: string;
-          try {
-            providerKey = resolveService(opts.provider);
-          } catch {
-            providerKey = opts.provider;
-          }
-
           // BYO connections throw on persistent 401 (after refresh retry
           // exhaustion) with a `status` property. Detect this and show the
           // same auth hint that the response-level 401/403 check would give.
@@ -552,13 +540,13 @@ Examples:
               : undefined;
 
           if (errStatus === 401 || errStatus === 403) {
-            const managed = isManagedMode(providerKey);
+            const managed = isManagedMode(opts.provider);
             const authHint = managed
               ? `Hint: Request returned HTTP ${errStatus}. The OAuth token may be expired or revoked.\n\n` +
-                `Run 'assistant oauth status ${providerKey}' to check connection health.\n` +
+                `Run 'assistant oauth status ${opts.provider}' to check connection health.\n` +
                 `To reconnect, run 'assistant oauth connect --help'.`
               : `Hint: Request returned HTTP ${errStatus}. The OAuth token may be expired or revoked.\n\n` +
-                `Run 'assistant oauth status ${providerKey}' to check connection status.\n` +
+                `Run 'assistant oauth status ${opts.provider}' to check connection status.\n` +
                 `To reconnect, run 'assistant oauth connect --help'.`;
 
             writeError(`Error: ${message}`, authHint);
@@ -568,7 +556,7 @@ Examples:
 
           writeError(
             `Error: ${message}\n\n` +
-              `For provider diagnostics, run 'assistant oauth providers get ${providerKey}'.`,
+              `For provider diagnostics, run 'assistant oauth providers get ${opts.provider}'.`,
           );
         }
       },

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

@@ -6,16 +6,9 @@ import {
   ServicesSchema,
 } from "../../../config/schemas/services.js";
 import { getProvider } from "../../../oauth/oauth-store.js";
-import { resolveService } from "../../../oauth/provider-behaviors.js";
 import { VellumPlatformClient } from "../../../platform/client.js";
 import { writeOutput } from "../../output.js";
 
-// ---------------------------------------------------------------------------
-// Re-exports
-// ---------------------------------------------------------------------------
-
-export { resolveService };
-
 // ---------------------------------------------------------------------------
 // Shared types
 // ---------------------------------------------------------------------------
@@ -31,17 +24,6 @@ export interface PlatformConnectionEntry {
 // Shared helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Extract the bare provider slug (e.g. "google") from either a raw CLI
- * argument or a canonical provider key (e.g. "integration:google").
- * Platform API paths expect the bare slug, not the internal key.
- */
-export function toBareProvider(provider: string): string {
-  return provider.startsWith("integration:")
-    ? provider.slice("integration:".length)
-    : provider;
-}
-
 /**
  * Return the provider's `managedServiceConfigKey` if it exists and is a valid
  * key in `ServicesSchema.shape`, or `null` otherwise. This centralises the
@@ -104,7 +86,7 @@ export async function fetchActiveConnections(
   options?: { silent?: boolean },
 ): Promise<PlatformConnectionEntry[] | null> {
   const params = new URLSearchParams();
-  params.set("provider", toBareProvider(provider));
+  params.set("provider", provider);
   params.set("status", "ACTIVE");
 
   const path = `/v1/assistants/${encodeURIComponent(client.platformAssistantId)}/oauth/connections/?${params.toString()}`;

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

@@ -7,7 +7,6 @@ import {
   fetchActiveConnections,
   isManagedMode,
   requirePlatformClient,
-  resolveService,
 } from "./shared.js";
 
 const log = getCliLogger("cli");
@@ -19,15 +18,12 @@ const log = getCliLogger("cli");
 export function registerStatusCommand(oauth: Command): void {
   oauth
     .command("status <provider>")
-    .description(
-      "Show OAuth connection status for a provider (auto-detects managed vs BYO mode)",
-    )
+    .description("Show OAuth connection status for a specified provider")
     .addHelpText(
       "after",
       `
 Arguments:
-  provider   Provider name or key. Accepts bare names (google, slack),
-             canonical keys (integration:google), or aliases (gmail).
+  provider   Provider name (e.g. google, slack).
              Run 'assistant oauth providers list' to see all available providers.
 
 The output includes connection IDs and account identifiers that can be used
@@ -36,15 +32,9 @@ as inputs to other commands:
   - 'assistant oauth request --provider <provider> --account <account>' to
     make authenticated requests as a specific account
 
-Mode detection:
-  The command automatically detects whether the provider is configured in
-  platform-managed mode or bring-your-own (BYO) mode based on the assistant's
-  services config. Managed mode delegates OAuth to the Vellum platform; BYO
-  mode uses locally stored tokens.
-
 Examples:
   $ assistant oauth status google
-  $ assistant oauth status integration:google --json`,
+  $ assistant oauth status google --json`,
     )
     .action(
       async (
@@ -54,10 +44,9 @@ Examples:
       ) => {
         try {
           // -----------------------------------------------------------------
-          // Resolve + validate provider
+          // Validate provider
           // -----------------------------------------------------------------
-          const providerKey = resolveService(provider);
-          const providerRow = getProvider(providerKey);
+          const providerRow = getProvider(provider);
 
           if (!providerRow) {
             writeOutput(cmd, {
@@ -73,7 +62,7 @@ Examples:
           // -----------------------------------------------------------------
           // Detect mode
           // -----------------------------------------------------------------
-          const managed = isManagedMode(providerKey);
+          const managed = isManagedMode(provider);
 
           if (managed) {
             // ---------------------------------------------------------------
@@ -84,7 +73,7 @@ Examples:
 
             const rawEntries = await fetchActiveConnections(
               client,
-              providerKey,
+              provider,
               cmd,
             );
             if (!rawEntries) return;
@@ -99,7 +88,7 @@ Examples:
             if (shouldOutputJson(cmd)) {
               writeOutput(cmd, {
                 ok: true,
-                provider: providerKey,
+                provider: provider,
                 mode: "managed",
                 connections,
               });
@@ -109,12 +98,12 @@ Examples:
             // Human output
             if (connections.length === 0) {
               log.info(
-                `No active connections for ${providerKey}. Connect with 'assistant oauth connect ${providerKey}'.`,
+                `No active connections for ${provider}. Connect with 'assistant oauth connect ${provider}'.`,
               );
               return;
             }
 
-            log.info(`Provider: ${providerKey} (managed)`);
+            log.info(`Provider: ${provider} (managed)`);
             log.info(`${connections.length} active connection(s):`);
             for (const c of connections) {
               const scopes =
@@ -129,7 +118,7 @@ Examples:
             // ---------------------------------------------------------------
             // BYO path
             // ---------------------------------------------------------------
-            const allConnections = listConnections(providerKey);
+            const allConnections = listConnections(provider);
             const activeRows = allConnections.filter(
               (r) => r.status === "active",
             );
@@ -159,7 +148,7 @@ Examples:
             if (shouldOutputJson(cmd)) {
               writeOutput(cmd, {
                 ok: true,
-                provider: providerKey,
+                provider: provider,
                 mode: "byo",
                 connections,
               });
@@ -169,12 +158,12 @@ Examples:
             // Human output
             if (connections.length === 0) {
               log.info(
-                `No active connections for ${providerKey}. Connect with 'assistant oauth connect ${providerKey}'.`,
+                `No active connections for ${provider}. Connect with 'assistant oauth connect ${provider}'.`,
               );
               return;
             }
 
-            log.info(`Provider: ${providerKey} (byo)`);
+            log.info(`Provider: ${provider} (byo)`);
             log.info(`${connections.length} active connection(s):`);
             for (const c of connections) {
               const scopes =

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

@@ -3,7 +3,7 @@ import type { Command } from "commander";
 import { getActiveConnection } from "../../../oauth/oauth-store.js";
 import { withValidToken } from "../../../security/token-manager.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
-import { isManagedMode, resolveService } from "./shared.js";
+import { isManagedMode } from "./shared.js";
 
 // ---------------------------------------------------------------------------
 // CES shell lockdown guard
@@ -31,44 +31,40 @@ export function registerTokenCommand(oauth: Command): void {
   oauth
     .command("token <provider>")
     .description(
-      "Print a valid OAuth access token for a provider (BYO providers only)",
+      'An escape hatch to retrieve a valid OAuth access token for a provider whose mode is "your-own" for direct use.',
     )
     .option(
       "--account <account>",
-      "Account identifier for BYO disambiguation (e.g. user@gmail.com)",
+      "Account identifier for account disambiguation (e.g. user@gmail.com)",
     )
     .option(
       "--client-id <id>",
-      "Filter by OAuth client ID when multiple apps exist for the provider",
+      "Filter by OAuth client ID when multiple OAuth apps exist for the provider",
     )
     .addHelpText(
       "after",
       `
 Arguments:
-  provider   Provider name or key. Accepts bare names (google, slack),
-             canonical keys (integration:google), aliases (gmail), or
-             provider IDs. Run 'assistant oauth providers list' to see
-             all available providers.
-
-Options:
-  --account <account>   Select a specific account when multiple connections
-                        exist for the same provider. Uses the account label
-                        shown in 'assistant oauth status <provider>'.
-  --client-id <id>      Select a specific OAuth app when multiple apps exist
-                        for the same provider.
-
-Token retrieval is only supported for BYO (bring-your-own credentials)
-providers. Platform-managed providers handle tokens internally — use
+  provider   Provider name (e.g. google, slack).
+             Run 'assistant oauth providers list' to see all available
+             providers.
+
+This command is discouraged and should be used sparingly. Only use if you
+need direct access to the token (i.e. \`assistant oauth request\` is
+insufficient) and you are comfortable with the security implications.
+
+Token retrieval is only supported for providers with mode set to "your-own".
+Platform-managed providers handle tokens internally — use
 'assistant oauth ping <provider>' to verify connectivity or
 'assistant oauth request --provider <provider> <url>' to make
 authenticated requests.
 
-CES shell lockdown: This command is blocked when running in an untrusted
-shell (VELLUM_UNTRUSTED_SHELL=1) to prevent token exfiltration.
+Use 'assistant oauth status <provider>' to find account identifiers for
+--account. Shell lockdown: blocked when VELLUM_UNTRUSTED_SHELL=1.
 
 Examples:
   $ assistant oauth token google
-  $ assistant oauth token integration:twitter --json
+  $ assistant oauth token twitter --json
   $ assistant oauth token google --account user@gmail.com
   $ assistant oauth token google --client-id abc123`,
     )
@@ -80,20 +76,15 @@ Examples:
       ) => {
         try {
           // ---------------------------------------------------------------
-          // 1. Resolve provider key
-          // ---------------------------------------------------------------
-          const providerKey = resolveService(provider);
-
-          // ---------------------------------------------------------------
-          // 2. Check managed mode
+          // 1. Check managed mode
           // ---------------------------------------------------------------
-          if (isManagedMode(providerKey)) {
+          if (isManagedMode(provider)) {
             const message =
               "Token retrieval is not supported for platform-managed providers. " +
               "When a provider is in managed mode, Vellum handles OAuth tokens on your behalf — " +
               "they are not exposed directly.\n\n" +
-              `To verify your connection is working, run 'assistant oauth ping ${providerKey}'.\n` +
-              `To make authenticated requests, use 'assistant oauth request --provider ${providerKey} <url>'.`;
+              `To verify your connection is working, run 'assistant oauth ping ${provider}'.\n` +
+              `To make authenticated requests, use 'assistant oauth request --provider ${provider} <url>'.`;
             writeOutput(cmd, { ok: false, error: message });
             process.exitCode = 1;
             return;
@@ -118,7 +109,7 @@ Examples:
           let tokenOpts: string | { connectionId: string } | undefined;
 
           if (opts.account || opts.clientId) {
-            const conn = getActiveConnection(providerKey, {
+            const conn = getActiveConnection(provider, {
               clientId: opts.clientId,
               account: opts.account,
             });
@@ -129,8 +120,8 @@ Examples:
                   ? ` with client ID "${opts.clientId}"`
                   : "";
               const message =
-                `No active connection found for "${providerKey}"${hint}. ` +
-                `Connect first with 'assistant oauth connect ${providerKey}'.`;
+                `No active connection found for "${provider}"${hint}. ` +
+                `Connect first with 'assistant oauth connect ${provider}'.`;
               writeOutput(cmd, { ok: false, error: message });
               process.exitCode = 1;
               return;
@@ -139,7 +130,7 @@ Examples:
           }
 
           const token = await withValidToken(
-            providerKey,
+            provider,
             async (t) => t,
             tokenOpts,
           );