@vellumai/assistant 0.4.49 → 0.4.50

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

@@ -1,18 +1,30 @@
 import type { Command } from "commander";
 
+import { orchestrateOAuthConnect } from "../../../oauth/connect-orchestrator.js";
 import {
   disconnectOAuthProvider,
+  getAppByProviderAndClientId,
   getConnection,
   getConnectionByProvider,
+  getMostRecentAppByProvider,
+  getProvider,
   listConnections,
 } from "../../../oauth/oauth-store.js";
+import {
+  getProviderBehavior,
+  resolveService,
+} from "../../../oauth/provider-behaviors.js";
 import { credentialKey } from "../../../security/credential-key.js";
-import { deleteSecureKeyAsync } from "../../../security/secure-keys.js";
+import {
+  deleteSecureKeyAsync,
+  getSecureKey,
+} from "../../../security/secure-keys.js";
 import { withValidToken } from "../../../security/token-manager.js";
 import {
   assertMetadataWritable,
   deleteCredentialMetadata,
 } from "../../../tools/credentials/metadata-store.js";
+import { isLinux, isMacOS } from "../../../util/platform.js";
 import { getCliLogger } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 
@@ -74,9 +86,14 @@ token expiry, refresh token availability, account info, and status.
 Examples:
   $ assistant oauth connections list
   $ assistant oauth connections list --provider integration:gmail
+  $ assistant oauth connections list --client-id abc123
   $ assistant oauth connections get --id <uuid>
   $ assistant oauth connections get --provider integration:gmail
-  $ assistant oauth connections token integration:twitter`,
+  $ assistant oauth connections get --provider integration:gmail --client-id abc123
+  $ assistant oauth connections token integration:twitter
+  $ assistant oauth connections ping integration:gmail
+  $ assistant oauth connections connect integration:gmail
+  $ assistant oauth connections connect integration:gmail --open-browser`,
   );
 
   // ---------------------------------------------------------------------------
@@ -90,21 +107,25 @@ Examples:
       "--provider <key>",
       "Filter by provider key (e.g. integration:gmail)",
     )
+    .option("--client-id <id>", "Filter by OAuth client ID")
     .addHelpText(
       "after",
       `
-Lists all OAuth connections, optionally filtered by provider key.
+Lists all OAuth connections, optionally filtered by provider key and/or client ID.
 
 Each connection shows its ID, provider, account info, granted scopes, token
 expiry, refresh token availability, and status.
 
 Examples:
   $ assistant oauth connections list
-  $ assistant oauth connections list --provider integration:gmail`,
+  $ assistant oauth connections list --provider integration:gmail
+  $ assistant oauth connections list --client-id abc123`,
     )
-    .action((opts: { provider?: string }, cmd: Command) => {
+    .action((opts: { provider?: string; clientId?: string }, cmd: Command) => {
       try {
-        const rows = listConnections(opts.provider).map(formatConnectionRow);
+        const rows = listConnections(opts.provider, opts.clientId).map(
+          formatConnectionRow,
+        );
 
         if (!shouldOutputJson(cmd)) {
           log.info(`Found ${rows.length} connection(s)`);
@@ -130,6 +151,10 @@ Examples:
       "--provider <key>",
       "Provider key (returns most recent active connection)",
     )
+    .option(
+      "--client-id <id>",
+      "Filter by OAuth client ID (used with --provider)",
+    )
     .addHelpText(
       "after",
       `
@@ -140,39 +165,45 @@ Two lookup modes are supported:
 
   2. By provider (returns the most recent active connection):
      $ assistant oauth connections get --provider integration:gmail
+     $ assistant oauth connections get --provider integration:gmail --client-id abc123
 
 At least --id or --provider must be specified.`,
     )
-    .action((opts: { id?: string; provider?: string }, cmd: Command) => {
-      try {
-        let row;
-
-        if (opts.id) {
-          row = getConnection(opts.id);
-        } else if (opts.provider) {
-          row = getConnectionByProvider(opts.provider);
-        } else {
-          writeOutput(cmd, {
-            ok: false,
-            error: "Provide --id or --provider",
-          });
-          process.exitCode = 1;
-          return;
-        }
-
-        if (!row) {
-          writeOutput(cmd, { ok: false, error: "Connection not found" });
+    .action(
+      (
+        opts: { id?: string; provider?: string; clientId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          let row;
+
+          if (opts.id) {
+            row = getConnection(opts.id);
+          } else if (opts.provider) {
+            row = getConnectionByProvider(opts.provider, opts.clientId);
+          } else {
+            writeOutput(cmd, {
+              ok: false,
+              error: "Provide --id or --provider",
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          if (!row) {
+            writeOutput(cmd, { ok: false, error: "Connection not found" });
+            process.exitCode = 1;
+            return;
+          }
+
+          writeOutput(cmd, formatConnectionRow(row));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
           process.exitCode = 1;
-          return;
         }
-
-        writeOutput(cmd, formatConnectionRow(row));
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        writeOutput(cmd, { ok: false, error: message });
-        process.exitCode = 1;
-      }
-    });
+      },
+    );
 
   // ---------------------------------------------------------------------------
   // connections token <provider-key>
@@ -183,6 +214,10 @@ At least --id or --provider must be specified.`,
     .description(
       "Print a valid OAuth access token for a provider, refreshing if expired",
     )
+    .option(
+      "--client-id <id>",
+      "Filter by OAuth client ID when multiple apps exist for the provider",
+    )
     .addHelpText(
       "after",
       `
@@ -199,22 +234,135 @@ Exits with code 1 if no access token exists or refresh fails.
 
 Examples:
   $ assistant oauth connections token integration:twitter
-  $ assistant oauth connections token integration:gmail --json`,
+  $ assistant oauth connections token integration:gmail --json
+  $ assistant oauth connections token integration:gmail --client-id abc123`,
     )
-    .action(async (providerKey: string, _opts: unknown, cmd: Command) => {
-      try {
-        const token = await withValidToken(providerKey, async (t) => t);
-        if (shouldOutputJson(cmd)) {
-          writeOutput(cmd, { ok: true, token });
-        } else {
-          process.stdout.write(token + "\n");
+    .action(
+      async (
+        providerKey: string,
+        opts: { clientId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          const token = await withValidToken(
+            providerKey,
+            async (t) => t,
+            opts.clientId,
+          );
+          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;
         }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        writeOutput(cmd, { ok: false, error: message });
-        process.exitCode = 1;
-      }
-    });
+      },
+    );
+
+  // ---------------------------------------------------------------------------
+  // connections ping <provider-key>
+  // ---------------------------------------------------------------------------
+
+  connections
+    .command("ping <provider-key>")
+    .description(
+      "Verify that a stored OAuth token is still valid by hitting the provider's health-check endpoint",
+    )
+    .option(
+      "--client-id <id>",
+      "Filter by OAuth client ID when multiple apps exist for the provider",
+    )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider-key   Provider key (e.g. integration:gmail, integration:twitter)
+
+Fetches a valid access token (refreshing if needed) and sends a GET request
+to the provider's configured ping URL. Reports success (HTTP 2xx) or failure.
+
+The ping URL is set per-provider in seed data or via "providers register --ping-url".
+If no ping URL is configured for the provider, exits with an error.
+
+Examples:
+  $ assistant oauth connections ping integration:gmail
+  $ assistant oauth connections ping integration:twitter --json
+  $ assistant oauth connections ping integration:gmail --client-id abc123`,
+    )
+    .action(
+      async (
+        providerKey: string,
+        opts: { clientId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          const provider = getProvider(providerKey);
+          if (!provider) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `Provider not found: ${providerKey}`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          if (!provider.pingUrl) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `No ping URL configured for "${providerKey}"`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          const pingUrl = provider.pingUrl;
+
+          const result = await withValidToken(
+            providerKey,
+            async (token) => {
+              const res = await fetch(pingUrl, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${token}` },
+              });
+              return { status: res.status, ok: res.ok };
+            },
+            opts.clientId,
+          );
+
+          if (result.ok) {
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, {
+                ok: true,
+                provider: providerKey,
+                status: result.status,
+              });
+            } else {
+              log.info(`${providerKey}: OK (HTTP ${result.status})`);
+              writeOutput(cmd, {
+                ok: true,
+                provider: providerKey,
+                status: result.status,
+              });
+            }
+          } else {
+            writeOutput(cmd, {
+              ok: false,
+              provider: providerKey,
+              status: result.status,
+              error: `Ping failed with HTTP ${result.status}`,
+            });
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
 
   // ---------------------------------------------------------------------------
   // connections disconnect <provider-key>
@@ -225,6 +373,10 @@ Examples:
     .description(
       "Disconnect an OAuth integration and remove all associated credentials",
     )
+    .option(
+      "--client-id <id>",
+      "Filter by OAuth client ID when multiple apps exist for the provider",
+    )
     .addHelpText(
       "after",
       `
@@ -240,60 +392,242 @@ client_id, client_secret) are also cleaned up if present.
 
 Examples:
   $ assistant oauth connections disconnect integration:gmail
-  $ assistant oauth connections disconnect integration:slack`,
+  $ assistant oauth connections disconnect integration:slack
+  $ assistant oauth connections disconnect integration:gmail --client-id abc123`,
     )
-    .action(async (providerKey: string, _opts: unknown, cmd: Command) => {
-      try {
-        assertMetadataWritable();
-
-        let cleanedUp = false;
-
-        // 1. Disconnect the OAuth connection (new-format keys + connection row)
-        const oauthResult = await disconnectOAuthProvider(providerKey);
-        if (oauthResult === "error") {
-          writeOutput(cmd, {
-            ok: false,
-            error: `Failed to disconnect OAuth provider "${providerKey}" — please try again`,
-          });
+    .action(
+      async (
+        providerKey: string,
+        opts: { clientId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          assertMetadataWritable();
+
+          let cleanedUp = false;
+
+          // 1. Disconnect the OAuth connection (new-format keys + connection row)
+          const oauthResult = await disconnectOAuthProvider(
+            providerKey,
+            opts.clientId,
+          );
+          if (oauthResult === "error") {
+            writeOutput(cmd, {
+              ok: false,
+              error: `Failed to disconnect OAuth provider "${providerKey}" — please try again`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+          if (oauthResult === "disconnected") cleanedUp = true;
+
+          // 2. Clean up legacy credential keys for common fields
+          const legacyFields = [
+            "access_token",
+            "refresh_token",
+            "client_id",
+            "client_secret",
+          ];
+          for (const field of legacyFields) {
+            const key = credentialKey(providerKey, field);
+            const result = await deleteSecureKeyAsync(key);
+            if (result === "deleted") cleanedUp = true;
+
+            const metaDeleted = deleteCredentialMetadata(providerKey, field);
+            if (metaDeleted) cleanedUp = true;
+          }
+
+          if (!cleanedUp) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `No OAuth connection or credentials found for "${providerKey}"`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          writeOutput(cmd, { ok: true, service: providerKey });
+
+          if (!shouldOutputJson(cmd)) {
+            log.info(`Disconnected ${providerKey}`);
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
           process.exitCode = 1;
-          return;
-        }
-        if (oauthResult === "disconnected") cleanedUp = true;
-
-        // 2. Clean up legacy credential keys for common fields
-        const legacyFields = [
-          "access_token",
-          "refresh_token",
-          "client_id",
-          "client_secret",
-        ];
-        for (const field of legacyFields) {
-          const key = credentialKey(providerKey, field);
-          const result = await deleteSecureKeyAsync(key);
-          if (result === "deleted") cleanedUp = true;
-
-          const metaDeleted = deleteCredentialMetadata(providerKey, field);
-          if (metaDeleted) cleanedUp = true;
         }
+      },
+    );
 
-        if (!cleanedUp) {
-          writeOutput(cmd, {
-            ok: false,
-            error: `No OAuth connection or credentials found for "${providerKey}"`,
-          });
-          process.exitCode = 1;
-          return;
-        }
+  // ---------------------------------------------------------------------------
+  // connections connect <provider-key>
+  // ---------------------------------------------------------------------------
 
-        writeOutput(cmd, { ok: true, service: providerKey });
+  connections
+    .command("connect <provider-key>")
+    .description("Initiate an OAuth2 authorization flow for a provider")
+    .option(
+      "--client-id <id>",
+      "Filter by OAuth client ID when multiple apps exist for the provider",
+    )
+    .option(
+      "--scopes <scopes...>",
+      "Additional scopes beyond the provider's defaults",
+    )
+    .option(
+      "--open-browser",
+      "Open the auth URL in the browser and wait for completion",
+    )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider-key   Provider key (e.g. integration:gmail) or alias (e.g. gmail)
 
-        if (!shouldOutputJson(cmd)) {
-          log.info(`Disconnected ${providerKey}`);
+Initiates an OAuth2 authorization flow for the given provider. By default,
+prints the authorization URL to stdout — useful for headless/remote sessions.
+The token exchange completes in the background when the user authorizes.
+
+With --open-browser, opens the authorization URL in your browser and waits
+for completion.
+
+Client credentials are resolved from the OAuth app store. Use --client-id
+to select a specific app when multiple apps exist for the same provider.
+
+Examples:
+  $ assistant oauth connections connect integration:gmail
+  $ assistant oauth connections connect gmail --open-browser
+  $ assistant oauth connections connect integration:slack --client-id abc123
+  $ assistant oauth connections connect integration:gmail --scopes calendar.readonly --json`,
+    )
+    .action(
+      async (
+        providerKey: string,
+        opts: {
+          clientId?: string;
+          scopes?: string[];
+          openBrowser?: boolean;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          // a. Resolve service alias
+          const resolvedServiceKey = resolveService(providerKey);
+
+          // b. Resolve client credentials from the DB
+          const dbApp = opts.clientId
+            ? getAppByProviderAndClientId(resolvedServiceKey, opts.clientId)
+            : getMostRecentAppByProvider(resolvedServiceKey);
+
+          let clientId = opts.clientId;
+          let clientSecret: string | undefined;
+
+          if (dbApp) {
+            if (!clientId) clientId = dbApp.clientId;
+            const storedSecret = getSecureKey(dbApp.clientSecretCredentialPath);
+            if (storedSecret) clientSecret = storedSecret;
+          }
+
+          // c. Validate client_id
+          if (!clientId) {
+            writeOutput(cmd, {
+              ok: false,
+              error:
+                "No client_id found. Provide --client-id or register an app first with 'assistant oauth apps upsert'.",
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          // d. Check if client_secret is required but missing
+          if (clientSecret === undefined) {
+            const providerRow = getProvider(resolvedServiceKey);
+            const behavior = getProviderBehavior(resolvedServiceKey);
+
+            const requiresSecret =
+              behavior?.setup?.requiresClientSecret ??
+              !!(
+                providerRow?.tokenEndpointAuthMethod || providerRow?.extraParams
+              );
+
+            if (requiresSecret) {
+              writeOutput(cmd, {
+                ok: false,
+                error: `client_secret is required for ${resolvedServiceKey} but not found. Store it first with 'assistant oauth apps upsert --client-secret'.`,
+              });
+              process.exitCode = 1;
+              return;
+            }
+          }
+
+          // e. Call the orchestrator
+          const result = await orchestrateOAuthConnect({
+            service: providerKey,
+            clientId,
+            clientSecret,
+            isInteractive: !!opts.openBrowser,
+            openUrl: opts.openBrowser
+              ? (url) => {
+                  if (isMacOS()) {
+                    Bun.spawn(["open", url], {
+                      stdout: "ignore",
+                      stderr: "ignore",
+                    });
+                  } else if (isLinux()) {
+                    Bun.spawn(["xdg-open", url], {
+                      stdout: "ignore",
+                      stderr: "ignore",
+                    });
+                  } else {
+                    // Fallback: print URL for manual opening
+                    process.stdout.write(
+                      `Open this URL to authorize:\n\n${url}\n`,
+                    );
+                  }
+                }
+              : undefined,
+            ...(opts.scopes ? { requestedScopes: opts.scopes } : {}),
+          });
+
+          // f. Handle results
+          if (!result.success) {
+            writeOutput(cmd, { ok: false, error: result.error });
+            process.exitCode = 1;
+            return;
+          }
+
+          if (result.deferred) {
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, {
+                ok: true,
+                deferred: true,
+                authUrl: result.authUrl,
+                service: result.service,
+              });
+            } else {
+              process.stdout.write(
+                `Open this URL to authorize:\n\n${result.authUrl}\n\nThe connection will complete automatically once you authorize.\n`,
+              );
+            }
+            return;
+          }
+
+          // Interactive mode completed
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, {
+              ok: true,
+              grantedScopes: result.grantedScopes,
+              accountInfo: result.accountInfo,
+            });
+          } else {
+            const msg = `Connected to ${resolvedServiceKey}${result.accountInfo ? ` as ${result.accountInfo}` : ""}`;
+            process.stdout.write(msg + "\n");
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
         }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        writeOutput(cmd, { ok: false, error: message });
-        process.exitCode = 1;
-      }
-    });
+      },
+    );
 }

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

@@ -171,6 +171,10 @@ Examples:
       }
       return port;
     })
+    .option(
+      "--ping-url <url>",
+      "Health-check endpoint URL for token validation",
+    )
     .addHelpText(
       "after",
       `
@@ -186,6 +190,9 @@ Arguments (via options):
                         (e.g. "client_secret_post", "client_secret_basic").
   --callback-transport  Transport method for the OAuth callback.
   --loopback-port       Port number for the local loopback callback server (1-65535).
+  --ping-url            Optional URL for a lightweight health-check endpoint.
+                        Used by "connections ping" to validate that a stored token
+                        is still functional (e.g. "https://api.example.com/user").
 
 Registers a new OAuth provider configuration in the local store. This is
 used for custom integrations not covered by the built-in provider seeds.
@@ -200,7 +207,12 @@ Examples:
       --provider-key integration:my-service \\
       --auth-url https://my-service.com/auth \\
       --token-url https://my-service.com/token \\
-      --scopes read,write --json`,
+      --scopes read,write --json
+  $ assistant oauth providers register \\
+      --provider-key integration:custom-api \\
+      --auth-url https://example.com/auth \\
+      --token-url https://example.com/token \\
+      --ping-url https://example.com/user`,
     )
     .action(
       (
@@ -214,6 +226,7 @@ Examples:
           tokenAuthMethod?: string;
           callbackTransport?: string;
           loopbackPort?: number;
+          pingUrl?: string;
         },
         cmd: Command,
       ) => {
@@ -229,6 +242,7 @@ Examples:
             tokenEndpointAuthMethod: opts.tokenAuthMethod,
             callbackTransport: opts.callbackTransport,
             loopbackPort: opts.loopbackPort,
+            pingUrl: opts.pingUrl,
           });
 
           writeOutput(cmd, parseProviderRow(row));

package/src/cli/commands/sessions.ts

@@ -12,7 +12,10 @@ import {
   getMessages,
 } from "../../memory/conversation-crud.js";
 import { listConversations } from "../../memory/conversation-queries.js";
-import { selectEmbeddingBackend } from "../../memory/embedding-backend.js";
+import {
+  selectEmbeddingBackend,
+  SPARSE_EMBEDDING_VERSION,
+} from "../../memory/embedding-backend.js";
 import { initQdrantClient } from "../../memory/qdrant-client.js";
 import { timeAgo } from "../../util/time.js";
 import { initializeDb } from "../db.js";
@@ -226,7 +229,7 @@ Examples:
       const qdrantUrl = getQdrantUrlEnv() || config.memory.qdrant.url;
       const embeddingSelection = selectEmbeddingBackend(config);
       const embeddingModel = embeddingSelection.backend
-        ? `${embeddingSelection.backend.provider}:${embeddingSelection.backend.model}`
+        ? `${embeddingSelection.backend.provider}:${embeddingSelection.backend.model}:sparse-v${SPARSE_EMBEDDING_VERSION}`
         : undefined;
       const qdrant = initQdrantClient({
         url: qdrantUrl,