@vellumai/assistant 0.4.35 → 0.4.37

package/src/cli/map.ts

@@ -5,10 +5,7 @@
  * the given domain, then analyzes captured network traffic into a deduplicated API map.
  */
 
-import { spawn as spawnChild } from "node:child_process";
 import * as net from "node:net";
-import { homedir } from "node:os";
-import { join as pathJoin } from "node:path";
 
 import { Command } from "commander";
 import { parse as parseTld } from "tldts";
@@ -19,6 +16,7 @@ import {
   printApiMapTable,
   saveApiMap,
 } from "../tools/browser/api-map.js";
+import { ensureChromeWithCdp } from "../tools/browser/chrome-cdp.js";
 import { loadRecording } from "../tools/browser/recording-store.js";
 import { getCliLogger } from "../util/logger.js";
 import { getSocketPath, readSessionToken } from "../util/platform.js";
@@ -59,34 +57,16 @@ function getJson(cmd: Command): boolean {
   return false;
 }
 
-// ---------------------------------------------------------------------------
-// Chrome CDP helpers
-// ---------------------------------------------------------------------------
-
-const CDP_BASE = "http://localhost:9222";
-const CHROME_DATA_DIR = pathJoin(
-  homedir(),
-  "Library/Application Support/Google/Chrome-CDP",
-);
-
-async function isCdpReady(): Promise<boolean> {
-  try {
-    const res = await fetch(`${CDP_BASE}/json/version`);
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Bring the Chrome CDP tab to the foreground so the user sees the right window.
  * Optionally navigates to a URL first (used when Chrome was already running).
  */
 async function bringChromeToFront(
+  cdpBase: string,
   navigateUrl?: string,
 ): Promise<string | null> {
   try {
-    const res = await fetch(`${CDP_BASE}/json/list`);
+    const res = await fetch(`${cdpBase}/json/list`);
     if (!res.ok) return null;
     const targets = (await res.json()) as Array<{
       type: string;
@@ -156,35 +136,6 @@ async function bringChromeToFront(
   }
 }
 
-async function ensureChromeWithCDP(domain: string): Promise<void> {
-  // Already running with CDP?
-  if (await isCdpReady()) return;
-
-  // Launch a separate Chrome instance with CDP flags alongside any existing Chrome.
-  const chromeApp =
-    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
-  spawnChild(
-    chromeApp,
-    [
-      `--remote-debugging-port=9222`,
-      `--force-renderer-accessibility`,
-      `--user-data-dir=${CHROME_DATA_DIR}`,
-      `https://${domain}/`,
-    ],
-    {
-      detached: true,
-      stdio: "ignore",
-    },
-  ).unref();
-
-  // Wait for CDP to be ready
-  for (let i = 0; i < 30; i++) {
-    await new Promise((r) => setTimeout(r, 500));
-    if (await isCdpReady()) return;
-  }
-  throw new Error("Chrome started but CDP endpoint not responding after 15s");
-}
-
 // ---------------------------------------------------------------------------
 // Ride Shotgun learn session helper
 // ---------------------------------------------------------------------------
@@ -200,10 +151,15 @@ async function startLearnSession(
   durationSeconds: number,
   autoNavigate: boolean = true,
 ): Promise<LearnResult> {
-  await ensureChromeWithCDP(navigateDomain);
+  const cdpSession = await ensureChromeWithCdp({
+    startUrl: `https://${navigateDomain}/`,
+  });
 
   // Activate the Chrome window so the user knows which tab to watch
-  const tabUrl = await bringChromeToFront(`https://${navigateDomain}/`);
+  const tabUrl = await bringChromeToFront(
+    cdpSession.baseUrl,
+    `https://${navigateDomain}/`,
+  );
   if (tabUrl) {
     process.stderr.write(`Chrome is ready — using tab at ${tabUrl}\n`);
   }
@@ -276,6 +232,13 @@ async function startLearnSession(
           continue;
         }
 
+        if (m.type === "ride_shotgun_error") {
+          clearTimeout(timeoutHandle);
+          socket.destroy();
+          reject(new Error((m as { message: string }).message));
+          continue;
+        }
+
         if (m.type === "ride_shotgun_result") {
           clearTimeout(timeoutHandle);
           socket.destroy();
@@ -321,6 +284,35 @@ export function registerMapCommand(program: Command): void {
       "Manual mode: browse the site yourself while network traffic is recorded",
     )
     .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  domain   The domain to map (e.g. example.com, open.spotify.com). Subdomains
+           are navigated directly but network traffic is recorded for the
+           entire base domain (e.g. open.spotify.com navigates that subdomain
+           but records all *.spotify.com traffic).
+
+Two modes of operation:
+  auto (default)   The assistant auto-navigates the site using Ride Shotgun,
+                   clicking links and exploring pages autonomously. Default
+                   duration: 120 seconds.
+  --manual         You browse the site yourself while network traffic is
+                   recorded in the background. Default duration: 60 seconds.
+
+How it works:
+  1. Launches Chrome with Chrome DevTools Protocol (CDP) enabled
+  2. Starts a Ride Shotgun learn session to capture network traffic
+  3. Deduplicates captured requests into unique API endpoints
+  4. Saves the API map to disk and prints a summary table
+
+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`,
+    )
     .action(
       async (
         domain: string,

package/src/cli/mcp.ts

@@ -57,10 +57,55 @@ export function registerMcpCommand(program: Command): void {
     .command("mcp")
     .description("Manage MCP (Model Context Protocol) servers");
 
+  mcp.addHelpText(
+    "after",
+    `
+MCP servers extend the assistant's capabilities with external tools. Servers
+are configured in the assistant's config.json under the mcp.servers key. Each
+server uses one of three transport types:
+
+  stdio             Local process communicating over stdin/stdout
+  sse               Remote server using Server-Sent Events
+  streamable-http   Remote server using Streamable HTTP transport
+
+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`,
+  );
+
   mcp
     .command("list")
     .description("List configured MCP servers and their status")
     .option("--json", "Output as JSON")
+    .addHelpText(
+      "after",
+      `
+Shows each configured MCP server with its current status and configuration:
+
+  Name         The server identifier used in config.json
+  Status       Health check result:
+                 ✓  Connected and responding
+                 ✗  Error or disabled
+                 !  Needs authentication (OAuth required)
+  Transport    stdio, sse, or streamable-http
+  URL/Command  The server URL (sse/streamable-http) or command (stdio)
+  Risk         Default risk level: low, medium, or high
+  Allowed      Tool allowlist filter (if configured)
+  Blocked      Tool blocklist filter (if configured)
+
+When output is a TTY, health checks run in parallel with live status updates.
+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`,
+    )
     .action(async (opts: { json?: boolean }) => {
       const raw = loadRawConfig();
       const mcpConfig = raw.mcp as Partial<McpConfig> | undefined;
@@ -217,6 +262,29 @@ export function registerMcpCommand(program: Command): void {
       "high",
     )
     .option("--disabled", "Add as disabled")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  name   Unique identifier for the server (used as the key in config.json)
+
+Transport-specific requirements:
+  stdio             Requires --command (and optional --args for arguments)
+  sse               Requires --url pointing to the SSE endpoint
+  streamable-http   Requires --url pointing to the HTTP endpoint
+
+The --risk flag sets the default risk level for all tools from this server
+(defaults to "high" if not specified). The server starts enabled unless
+--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>".
+
+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`,
+    )
     .action(
       (
         name: string,
@@ -293,7 +361,7 @@ export function registerMcpCommand(program: Command): void {
         saveRawConfig(raw);
         log.info(`Added MCP server "${name}" (${opts.transportType})`);
         log.info(
-          "Restart the daemon for changes to take effect: vellum sleep && vellum wake",
+          "Restart the assistant for changes to take effect: vellum sleep && vellum wake",
         );
       },
     );
@@ -301,6 +369,28 @@ export function registerMcpCommand(program: Command): void {
   mcp
     .command("auth <name>")
     .description("Authenticate with an MCP server via OAuth")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  name   Name of a configured MCP server to authenticate with
+
+Only works with sse or streamable-http transports (stdio servers do not use
+OAuth). Opens a browser for OAuth authorization with the remote server and
+starts a local callback server to receive the authorization code.
+
+The command waits up to 2.5 minutes for the user to complete the browser-based
+OAuth flow. If the server already has valid cached tokens, the command succeeds
+immediately without opening a browser. Tokens are cached locally for future use
+by the assistant.
+
+After successful authentication, restart the assistant for changes to take effect
+(vellum sleep && vellum wake).
+
+Examples:
+  $ vellum mcp auth my-server
+  $ vellum mcp auth remote-api`,
+    )
     .action(async (name: string) => {
       const raw = loadRawConfig();
       const mcpConfig = raw.mcp as Partial<McpConfig> | undefined;
@@ -454,7 +544,7 @@ export function registerMcpCommand(program: Command): void {
 
       log.info(`Authentication successful for "${name}".`);
       log.info(
-        "Restart the daemon for changes to take effect: vellum sleep && vellum wake",
+        "Restart the assistant for changes to take effect: vellum sleep && vellum wake",
       );
       process.exit(0);
     });
@@ -462,6 +552,24 @@ export function registerMcpCommand(program: Command): void {
   mcp
     .command("remove <name>")
     .description("Remove an MCP server configuration")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  name   Name of the MCP server to remove
+
+Removes the server entry from config.json and performs best-effort cleanup of
+any stored OAuth credentials (tokens, client info, discovery metadata) for
+sse/streamable-http servers. If no OAuth credentials exist, the cleanup is
+silently skipped.
+
+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`,
+    )
     .action(async (name: string) => {
       const raw = loadRawConfig();
       const mcpConfig = raw.mcp as Record<string, unknown> | undefined;
@@ -490,7 +598,7 @@ export function registerMcpCommand(program: Command): void {
       saveRawConfig(raw);
       log.info(`Removed MCP server "${name}".`);
       log.info(
-        "Restart the daemon for changes to take effect: vellum sleep && vellum wake",
+        "Restart the assistant for changes to take effect: vellum sleep && vellum wake",
       );
     });
 }