@vellumai/assistant 0.4.37 → 0.4.41

package/src/cli/integrations.ts

@@ -205,21 +205,19 @@ export function registerIntegrationsCommand(program: Command): void {
     "after",
     `
 Reads integration configuration and status through the gateway API. The
-assistant must be running for most subcommands (telegram, twilio, guardian)
+assistant must be running for most subcommands (telegram, guardian)
 since they query the gateway. Exceptions: "ingress config" and "voice config"
 read from the local config file and do not require the gateway.
 
 Integration categories:
   telegram     Telegram bot configuration and webhook status
-  twilio       Twilio credentials, phone numbers, and SMS compliance
   guardian     Guardian trust verification system for contacts
   ingress      Public ingress URL and local gateway target (config-only)
   voice        Voice/call readiness and ElevenLabs voice ID (config-only)
 
 Examples:
-  $ vellum integrations telegram config
-  $ vellum integrations twilio numbers
-  $ vellum integrations guardian status --channel sms`,
+  $ assistant integrations telegram config
+  $ assistant integrations guardian status --channel sms`,
   );
 
   const telegram = integrations
@@ -233,8 +231,8 @@ Checks the Telegram bot configuration status through the gateway API.
 Requires the assistant to be running.
 
 Examples:
-  $ vellum integrations telegram config
-  $ vellum integrations telegram config --json`,
+  $ assistant integrations telegram config
+  $ assistant integrations telegram config --json`,
   );
 
   telegram
@@ -250,8 +248,8 @@ The response includes whether a bot token is configured, the current webhook
 endpoint, and the bot's Telegram username.
 
 Examples:
-  $ vellum integrations telegram config
-  $ vellum integrations telegram config --json`,
+  $ assistant integrations telegram config
+  $ assistant integrations telegram config --json`,
     )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () =>
@@ -271,8 +269,8 @@ contacts on each channel have completed identity verification. Requires
 the assistant to be running.
 
 Examples:
-  $ vellum integrations guardian status
-  $ vellum integrations guardian status --channel voice`,
+  $ assistant integrations guardian status
+  $ assistant integrations guardian status --channel voice`,
   );
 
   guardian
@@ -290,10 +288,10 @@ not specified. The response includes whether guardian verification is active
 and the current verification state for that channel.
 
 Examples:
-  $ vellum integrations guardian status
-  $ vellum integrations guardian status --channel telegram
-  $ vellum integrations guardian status --channel voice
-  $ vellum integrations guardian status --channel sms --json`,
+  $ assistant integrations guardian status
+  $ assistant integrations guardian status --channel telegram
+  $ assistant integrations guardian status --channel voice
+  $ assistant integrations guardian status --channel sms --json`,
     )
     .action(async (opts: { channel?: GuardianChannel }, cmd: Command) => {
       const channel = opts.channel ?? "telegram";
@@ -304,129 +302,6 @@ Examples:
       );
     });
 
-  const twilio = integrations
-    .command("twilio")
-    .description("Twilio integration status");
-
-  twilio.addHelpText(
-    "after",
-    `
-Covers Twilio credential status, phone number management, and SMS regulatory
-compliance. All subcommands require the assistant to be running since they
-query the gateway API.
-
-Subcommands:
-  config          Check Twilio credential status and phone number configuration
-  numbers         List all Twilio incoming phone numbers
-  sms compliance  Check SMS regulatory compliance status
-
-Examples:
-  $ vellum integrations twilio config
-  $ vellum integrations twilio numbers
-  $ vellum integrations twilio sms compliance`,
-  );
-
-  twilio
-    .command("config")
-    .description("Get Twilio credential and phone number status")
-    .addHelpText(
-      "after",
-      `
-Checks the Twilio credential status and phone number configuration through
-the gateway. Requires the assistant to be running.
-
-The response includes whether the Twilio account SID and auth token are
-configured, and the currently assigned phone number.
-
-Examples:
-  $ vellum integrations twilio config
-  $ vellum integrations twilio config --json`,
-    )
-    .action(async (_opts: unknown, cmd: Command) => {
-      await runRead(cmd, async () =>
-        gatewayGet("/v1/integrations/twilio/config"),
-      );
-    });
-
-  twilio
-    .command("numbers")
-    .description("List Twilio incoming phone numbers")
-    .addHelpText(
-      "after",
-      `
-Lists all incoming phone numbers associated with the configured Twilio
-account. Requires the assistant to be running.
-
-Returns an array of phone number objects with their SID, phone number,
-friendly name, and capabilities.
-
-Examples:
-  $ vellum integrations twilio numbers
-  $ vellum integrations twilio numbers --json`,
-    )
-    .action(async (_opts: unknown, cmd: Command) => {
-      await runRead(cmd, async () =>
-        gatewayGet("/v1/integrations/twilio/numbers"),
-      );
-    });
-
-  const twilioSms = twilio.command("sms").description("Twilio SMS status");
-
-  twilioSms.addHelpText(
-    "after",
-    `
-Covers SMS regulatory compliance for the configured Twilio account. All
-subcommands require the assistant to be running since they query the gateway API.
-
-Subcommands:
-  compliance   Check SMS regulatory compliance status
-
-Examples:
-  $ vellum integrations twilio sms compliance
-  $ vellum integrations twilio sms compliance --json`,
-  );
-
-  twilioSms
-    .command("compliance")
-    .description("Get Twilio SMS compliance status")
-    .addHelpText(
-      "after",
-      `
-Checks the SMS regulatory compliance status for the configured Twilio
-account. Requires the assistant to be running.
-
-Returns the current compliance state, including whether the account is
-approved for SMS messaging and any outstanding compliance requirements.
-
-Examples:
-  $ vellum integrations twilio sms compliance
-  $ vellum integrations twilio sms compliance --json`,
-    )
-    .action(async (_opts: unknown, cmd: Command) => {
-      await runRead(cmd, async () =>
-        gatewayGet("/v1/integrations/twilio/sms/compliance"),
-      );
-    });
-
-  twilio
-    .command("sms-compliance")
-    .description('Alias for "vellum integrations twilio sms compliance"')
-    .addHelpText(
-      "after",
-      `
-Shortcut alias for "vellum integrations twilio sms compliance". Prefer
-the canonical path for scripts and documentation.
-
-Examples:
-  $ vellum integrations twilio sms-compliance
-  $ vellum integrations twilio sms compliance   # canonical form`,
-    )
-    .action(async (_opts: unknown, cmd: Command) => {
-      await runRead(cmd, async () =>
-        gatewayGet("/v1/integrations/twilio/sms/compliance"),
-      );
-    });
-
   const ingress = integrations
     .command("ingress")
     .description("Trusted contact membership and invite status");
@@ -438,7 +313,7 @@ Shows the public ingress URL and local gateway target URL. Reads from the
 local config file and does not require the gateway to be running.
 
 Examples:
-  $ vellum integrations ingress config`,
+  $ assistant integrations ingress config`,
   );
 
   ingress
@@ -455,8 +330,8 @@ URL (if any), and the local gateway target address. Ingress is considered
 enabled if explicitly set to true or if a publicBaseUrl is configured.
 
 Examples:
-  $ vellum integrations ingress config
-  $ vellum integrations ingress config --json`,
+  $ assistant integrations ingress config
+  $ assistant integrations ingress config --json`,
     )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () => readIngressConfig());
@@ -471,7 +346,7 @@ Shows voice and call readiness configuration. Reads from the local config
 file and does not require the gateway to be running.
 
 Examples:
-  $ vellum integrations voice config`,
+  $ assistant integrations voice config`,
   );
 
   voice
@@ -488,8 +363,8 @@ ID (falls back to default if not configured), whether a custom voice ID is
 set, and whether the default voice is in use.
 
 Examples:
-  $ vellum integrations voice config
-  $ vellum integrations voice config --json`,
+  $ assistant integrations voice config
+  $ assistant integrations voice config --json`,
     )
     .action(async (_opts: unknown, cmd: Command) => {
       await runRead(cmd, async () => readVoiceConfig());

package/src/cli/keys.ts

@@ -24,9 +24,9 @@ plaintext. Each key is identified by provider name.
 Known providers: ${API_KEY_PROVIDERS.join(", ")}
 
 Examples:
-  $ vellum keys list
-  $ vellum keys set anthropic sk-ant-...
-  $ vellum keys delete openai`,
+  $ assistant keys list
+  $ assistant keys set anthropic sk-ant-...
+  $ assistant keys delete openai`,
   );
 
   keys
@@ -40,7 +40,7 @@ names of providers that have a stored key. Providers without a stored key are
 omitted from the output.
 
 Examples:
-  $ vellum keys list`,
+  $ assistant keys list`,
     )
     .action(() => {
       const stored: string[] = [];
@@ -59,7 +59,7 @@ Examples:
 
   keys
     .command("set <provider> <key>")
-    .description("Store an API key (e.g. vellum keys set anthropic sk-ant-...)")
+    .description("Store an API key (e.g. assistant keys set anthropic sk-ant-...)")
     .addHelpText(
       "after",
       `
@@ -70,9 +70,9 @@ Arguments:
 If a key already exists for the given provider, it is silently overwritten.
 
 Examples:
-  $ vellum keys set anthropic sk-ant-abc123
-  $ vellum keys set openai sk-proj-xyz789
-  $ vellum keys set fireworks fw-abc123`,
+  $ assistant keys set anthropic sk-ant-abc123
+  $ assistant keys set openai sk-proj-xyz789
+  $ assistant keys set fireworks fw-abc123`,
     )
     .action((provider: string, key: string) => {
       if (setSecureKey(provider, key)) {
@@ -96,8 +96,8 @@ Removes the API key for the given provider from secure local storage. If
 no key exists for the provider, exits with an error.
 
 Examples:
-  $ vellum keys delete openai
-  $ vellum keys delete anthropic`,
+  $ assistant keys delete openai
+  $ assistant keys delete anthropic`,
     )
     .action((provider: string) => {
       const result = deleteSecureKey(provider);

package/src/cli/map.ts

@@ -1,5 +1,5 @@
 /**
- * CLI command: `vellum map <domain>`
+ * CLI command: `assistant map <domain>`
  *
  * Launches Chrome with CDP, starts a Ride Shotgun learn session to auto-navigate
  * the given domain, then analyzes captured network traffic into a deduplicated API map.
@@ -309,9 +309,9 @@ How it works:
 The assistant must be running (the learn session is coordinated through it).
 
 Examples:
-  $ vellum map example.com
-  $ vellum map open.spotify.com --duration 180
-  $ vellum map garmin.com --manual`,
+  $ assistant map example.com
+  $ assistant map open.spotify.com --duration 180
+  $ assistant map garmin.com --manual`,
     )
     .action(
       async (

package/src/cli/mcp.ts

@@ -72,10 +72,10 @@ Changes to MCP server configuration require an assistant restart to take effect
 (vellum sleep && vellum wake).
 
 Examples:
-  $ vellum mcp list
-  $ vellum mcp add my-server -t stdio -c npx -a my-mcp-server
-  $ vellum mcp auth my-server
-  $ vellum mcp remove my-server`,
+  $ assistant mcp list
+  $ assistant mcp add my-server -t stdio -c npx -a my-mcp-server
+  $ assistant mcp auth my-server
+  $ assistant mcp remove my-server`,
   );
 
   mcp
@@ -103,8 +103,8 @@ In non-TTY mode (piped), checks run sequentially. With --json, outputs raw
 server config without running health checks.
 
 Examples:
-  $ vellum mcp list
-  $ vellum mcp list --json`,
+  $ assistant mcp list
+  $ assistant mcp list --json`,
     )
     .action(async (opts: { json?: boolean }) => {
       const raw = loadRawConfig();
@@ -278,12 +278,12 @@ The --risk flag sets the default risk level for all tools from this server
 --disabled is passed.
 
 If a server with the same name already exists, the command fails. Remove the
-existing server first with "vellum mcp remove <name>".
+existing server first with "assistant mcp remove <name>".
 
 Examples:
-  $ vellum mcp add my-server -t stdio -c npx -a my-mcp-server
-  $ vellum mcp add remote-api -t streamable-http -u https://api.example.com/mcp -r medium
-  $ vellum mcp add legacy-sse -t sse -u https://old.example.com/events --disabled`,
+  $ assistant mcp add my-server -t stdio -c npx -a my-mcp-server
+  $ assistant mcp add remote-api -t streamable-http -u https://api.example.com/mcp -r medium
+  $ assistant mcp add legacy-sse -t sse -u https://old.example.com/events --disabled`,
     )
     .action(
       (
@@ -305,7 +305,7 @@ Examples:
 
         if (servers[name]) {
           log.error(
-            `MCP server "${name}" already exists. Remove it first with: vellum mcp remove ${name}`,
+            `MCP server "${name}" already exists. Remove it first with: assistant mcp remove ${name}`,
           );
           process.exitCode = 1;
           return;
@@ -388,8 +388,8 @@ After successful authentication, restart the assistant for changes to take effec
 (vellum sleep && vellum wake).
 
 Examples:
-  $ vellum mcp auth my-server
-  $ vellum mcp auth remote-api`,
+  $ assistant mcp auth my-server
+  $ assistant mcp auth remote-api`,
     )
     .action(async (name: string) => {
       const raw = loadRawConfig();
@@ -399,7 +399,7 @@ Examples:
 
       if (!serverConfig) {
         log.error(
-          `MCP server "${name}" not found. Add it first with: vellum mcp add`,
+          `MCP server "${name}" not found. Add it first with: assistant mcp add`,
         );
         process.exitCode = 1;
         return;
@@ -508,7 +508,7 @@ Examples:
           log.error(`Authorization cancelled for "${name}".`);
         } else if (message.includes("timed out")) {
           log.error(
-            `Authorization timed out for "${name}". Try again with: vellum mcp auth ${name}`,
+            `Authorization timed out for "${name}". Try again with: assistant mcp auth ${name}`,
           );
         } else {
           log.error(`Authorization failed for "${name}": ${message}`);
@@ -567,8 +567,8 @@ After removal, restart the assistant for changes to take effect
 (vellum sleep && vellum wake).
 
 Examples:
-  $ vellum mcp remove my-server
-  $ vellum mcp remove legacy-sse`,
+  $ assistant mcp remove my-server
+  $ assistant mcp remove legacy-sse`,
     )
     .action(async (name: string) => {
       const raw = loadRawConfig();

package/src/cli/memory.ts

@@ -38,10 +38,10 @@ Key concepts:
   conflicts    Pairs of contradictory statements awaiting resolution
 
 Examples:
-  $ vellum memory status
-  $ vellum memory query "What is the project deadline?"
-  $ vellum memory backfill
-  $ vellum memory dismiss-conflicts --all`,
+  $ assistant memory status
+  $ assistant memory query "What is the project deadline?"
+  $ assistant memory backfill
+  $ assistant memory dismiss-conflicts --all`,
   );
 
   memory
@@ -68,7 +68,7 @@ Fields shown:
   jobs               Status of background jobs (backfill, cleanup, rebuild-index)
 
 Examples:
-  $ vellum memory status`,
+  $ assistant memory status`,
     )
     .action(() => {
       initializeDb();
@@ -133,8 +133,8 @@ all segments regardless of whether they have already been indexed. This is
 useful after bulk imports or if the incremental state has become inconsistent.
 
 Examples:
-  $ vellum memory backfill
-  $ vellum memory backfill --force`,
+  $ assistant memory backfill
+  $ assistant memory backfill --force`,
     )
     .action((opts: { force?: boolean }) => {
       initializeDb();
@@ -165,8 +165,8 @@ record must have before it is eligible for cleanup. If omitted, the system
 default retention period is used.
 
 Examples:
-  $ vellum memory cleanup
-  $ vellum memory cleanup --retention-ms 86400000`,
+  $ assistant memory cleanup
+  $ assistant memory cleanup --retention-ms 86400000`,
     )
     .action((opts: { retentionMs?: string }) => {
       initializeDb();
@@ -207,9 +207,9 @@ The optional --session flag provides a conversation/session ID for
 context-aware recall. If omitted, the most recent conversation is used.
 
 Examples:
-  $ vellum memory query "What is the project deadline?"
-  $ vellum memory query "preferred communication style" --session conv_abc123
-  $ vellum memory query "API rate limits"`,
+  $ assistant memory query "What is the project deadline?"
+  $ assistant memory query "preferred communication style" --session conv_abc123
+  $ assistant memory query "API rate limits"`,
     )
     .action(async (text: string, opts?: { session?: string }) => {
       initializeDb();
@@ -247,12 +247,12 @@ search) index and the vector embedding index. All existing index data is
 dropped and reconstructed from the source memory items.
 
 This is useful after schema changes, embedding model upgrades, or if index
-corruption is suspected. The rebuild runs asynchronously; use "vellum memory
+corruption is suspected. The rebuild runs asynchronously; use "assistant memory
 status" to monitor job progress.
 
 Examples:
-  $ vellum memory rebuild-index
-  $ vellum memory status`,
+  $ assistant memory rebuild-index
+  $ assistant memory status`,
     )
     .action(() => {
       initializeDb();
@@ -286,9 +286,9 @@ omitted. The --dry-run flag previews which conflicts would be dismissed
 without actually modifying any records.
 
 Examples:
-  $ vellum memory dismiss-conflicts --all
-  $ vellum memory dismiss-conflicts --pattern "project deadline" --dry-run
-  $ vellum memory dismiss-conflicts --pattern "^preferred\\b" --scope work`,
+  $ assistant memory dismiss-conflicts --all
+  $ assistant memory dismiss-conflicts --pattern "project deadline" --dry-run
+  $ assistant memory dismiss-conflicts --pattern "^preferred\\b" --scope work`,
     )
     .action(
       (opts: {

package/src/cli/notifications.ts

@@ -57,10 +57,10 @@ ${buildSourceChannelsHelpBlock()}
 ${buildSourceEventNamesHelpBlock()}
 
 Examples:
-  $ vellum notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Build finished"
-  $ vellum notifications send --source-channel scheduler --source-event-name reminder.fired --message "Stand-up in 5 minutes" --urgency high
-  $ vellum notifications send --source-channel watcher --source-event-name watcher.notification --message "File changed" --no-requires-action --is-async-background
-  $ vellum notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Deploy complete" --preferred-channels vellum,telegram --json`,
+  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Build finished"
+  $ assistant notifications send --source-channel scheduler --source-event-name reminder.fired --message "Stand-up in 5 minutes" --urgency high
+  $ assistant notifications send --source-channel watcher --source-event-name watcher.notification --message "File changed" --no-requires-action --is-async-background
+  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Deploy complete" --preferred-channels vellum,telegram --json`,
   );
 
   // -------------------------------------------------------------------------
@@ -131,8 +131,8 @@ Examples:
       "after",
       `
 Arguments:
-  --source-channel     One of the registered source channels (see "vellum notifications --help")
-  --source-event-name  One of the registered event names (see "vellum notifications --help")
+  --source-channel     One of the registered source channels (see "assistant notifications --help")
+  --source-event-name  One of the registered event names (see "assistant notifications --help")
   --message            The notification body text (required, must be non-empty)
 
 Behavioral notes:
@@ -144,9 +144,9 @@ Behavioral notes:
   - --dedupe-key suppresses duplicate signals with the same key.
 
 Examples:
-  $ vellum notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Task complete"
-  $ vellum notifications send --source-channel scheduler --source-event-name reminder.fired --message "Meeting in 5 min" --urgency high --title "Reminder"
-  $ vellum notifications send --source-channel watcher --source-event-name watcher.notification --message "Detected change" --no-requires-action --is-async-background --json`,
+  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Task complete"
+  $ assistant notifications send --source-channel scheduler --source-event-name reminder.fired --message "Meeting in 5 min" --urgency high --title "Reminder"
+  $ assistant notifications send --source-channel watcher --source-event-name watcher.notification --message "Detected change" --no-requires-action --is-async-background --json`,
     )
     .action(
       async (
@@ -318,10 +318,10 @@ notification pipeline.
 ${buildSourceEventNamesHelpBlock()}
 
 Examples:
-  $ vellum notifications list
-  $ vellum notifications list --limit 5
-  $ vellum notifications list --source-event-name reminder.fired
-  $ vellum notifications list --source-event-name reminder.fired --limit 10 --json`,
+  $ assistant notifications list
+  $ assistant notifications list --limit 5
+  $ assistant notifications list --source-event-name reminder.fired
+  $ assistant notifications list --source-event-name reminder.fired --limit 10 --json`,
     )
     .action(
       (

package/src/cli/oauth.ts

@@ -0,0 +1,77 @@
+import type { Command } from "commander";
+
+import { withValidToken } from "../security/token-manager.js";
+import { shouldOutputJson, writeOutput } from "./integrations.js";
+
+export function registerOAuthCommand(program: Command): void {
+  const oauth = program
+    .command("oauth")
+    .description("Manage OAuth tokens for connected integrations")
+    .option("--json", "Machine-readable compact JSON output");
+
+  oauth.addHelpText(
+    "after",
+    `
+OAuth tokens are managed automatically — the "token" command returns a
+guaranteed-valid access token, refreshing transparently if the stored token
+is expired or near-expiry. Callers never need to handle refresh themselves.
+
+The <service> argument is the short integration name (e.g. "twitter", "gmail",
+"slack"). Internally this maps to credential:integration:<service>:access_token.
+
+Examples:
+  $ assistant oauth token twitter
+  $ assistant oauth token twitter --json
+  $ TOKEN=$(assistant oauth token gmail)
+  $ curl -H "Authorization: Bearer $(assistant oauth token twitter)" https://api.x.com/2/tweets`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // token — return a guaranteed-valid access token
+  // ---------------------------------------------------------------------------
+
+  oauth
+    .command("token <service>")
+    .description(
+      "Print a valid OAuth access token for a service, refreshing if expired",
+    )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  service   Integration name without the "integration:" prefix
+            (e.g. "twitter", "gmail", "slack")
+
+Returns a valid OAuth access token for the given service. If the stored token
+is expired or near-expiry, it is refreshed automatically before being returned.
+The refresh uses the stored refresh token and OAuth2 configuration from
+credential metadata — no additional input is required.
+
+In human mode, prints the bare token to stdout (suitable for shell substitution).
+In JSON mode (--json), prints {"ok": true, "token": "..."}.
+
+Exits with code 1 if no access token exists for the service, no refresh token
+is available, or the token refresh fails (e.g. revoked credentials).
+
+Examples:
+  $ assistant oauth token twitter
+  $ assistant oauth token gmail --json
+  $ export TOKEN=$(assistant oauth token twitter)`,
+    )
+    .action(async (service: string, _opts: unknown, cmd: Command) => {
+      try {
+        const qualifiedService = `integration:${service}`;
+        const token = await withValidToken(qualifiedService, async (t) => t);
+
+        if (shouldOutputJson(cmd)) {
+          writeOutput(cmd, { ok: true, token });
+        } else {
+          process.stdout.write(token + "\n");
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/program.ts

@@ -22,6 +22,7 @@ import { registerMapCommand } from "./map.js";
 import { registerMcpCommand } from "./mcp.js";
 import { registerMemoryCommand } from "./memory.js";
 import { registerNotificationsCommand } from "./notifications.js";
+import { registerOAuthCommand } from "./oauth.js";
 import { registerSequenceCommand } from "./sequence.js";
 import { registerSessionsCommand } from "./sessions.js";
 import { registerTrustCommand } from "./trust.js";
@@ -55,6 +56,7 @@ export function buildCliProgram(): Command {
   registerAutonomyCommand(program);
   registerCompletionsCommand(program);
   registerNotificationsCommand(program);
+  registerOAuthCommand(program);
 
   registerTwitterCommand(program);
   registerMapCommand(program);