@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/commands/inference.ts

@@ -13,8 +13,10 @@ import type { Command } from "commander";
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
 import { readStdinSync } from "../../util/read-stdin.js";
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { inferenceHelp, llmHelp } from "./inference.help.js";
 import { attachCallsitesSubcommand } from "./inference-callsites.js";
 import { attachModelsSubcommand } from "./inference-models.js";
 import { attachProfilesSubcommand } from "./inference-profiles.js";
@@ -83,143 +85,109 @@ function writeCliError(message: string, jsonOutput?: boolean): void {
 // ── Send subcommand ──────────────────────────────────────────────────
 
 /**
- * Attach the `send` subcommand to the given command group (`inference` or
- * `llm`). Both groups share the same implementation.
+ * Attach the `send` subcommand's action to the given command group
+ * (`inference` or `llm`). Both groups share the same implementation.
  */
 function attachSendSubcommand(group: Command): void {
-  group
-    .command("send")
-    .description("Send a message to the configured LLM and print the response")
-    .option("--system-prompt <text>", "System prompt for the model")
-    .option("--model <model-id>", "Model override")
-    .option(
-      "--profile <name>",
-      "Apply a named inference profile from llm.profiles for this single call",
-    )
-    .option("--max-tokens <n>", "Max response tokens", undefined)
-    .option(
-      "--timeout-seconds <seconds>",
-      "Maximum time to wait for the inference response",
-      undefined,
-    )
-    .option("--json", "Output structured JSON")
-    .argument("[message...]", "User message (joined with spaces)")
-    .addHelpText(
-      "after",
-      `
-Behavioral notes:
-  - If no message argument is provided, reads from stdin.
-  - If --model is omitted, uses the configured default model.
-  - --profile applies a named profile from llm.profiles for this single call
-    only. It does NOT open a session — to pin a profile to a conversation,
-    use 'assistant inference profile open <name>'.
-  - --profile layers below --model: --model still wins on the model field.
-  - Long-running requests wait up to 32 minutes by default. Use
-    --timeout-seconds to adjust the wait budget for this call.
-  - Requires a configured LLM provider (see 'assistant config set').
-
-Examples:
-  $ assistant inference send "What is 2+2?"
-  $ echo "Summarize this" | assistant inference send
-  $ assistant llm send --system-prompt "You are a poet" "Write a haiku"
-  $ assistant inference send --timeout-seconds 300 "Draft a long memo"
-  $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
-  $ assistant inference send --profile balanced "Explain RFC 1149"`,
-    )
-    .action(
-      async (
-        messageParts: string[],
-        opts: {
-          systemPrompt?: string;
-          model?: string;
-          profile?: string;
-          maxTokens?: string;
-          timeoutSeconds?: string;
-          json?: boolean;
-        },
-      ) => {
-        const { systemPrompt, model, profile, json: jsonOutput } = opts;
-        const parsedMaxTokens = parsePositiveIntegerOption(
-          opts.maxTokens,
-          "--max-tokens",
-        );
-        const parsedTimeoutSeconds = parsePositiveIntegerOption(
-          opts.timeoutSeconds,
-          "--timeout-seconds",
-          { max: MAX_INFERENCE_TIMEOUT_SECONDS },
-        );
-
-        if (!parsedMaxTokens.ok) {
-          writeCliError(parsedMaxTokens.error, jsonOutput);
-          return;
-        }
-
-        if (!parsedTimeoutSeconds.ok) {
-          writeCliError(parsedTimeoutSeconds.error, jsonOutput);
-          return;
-        }
-
-        const maxTokens = parsedMaxTokens.value;
-        const timeoutMs =
-          parsedTimeoutSeconds.value !== undefined
-            ? parsedTimeoutSeconds.value * 1000
-            : DEFAULT_INFERENCE_IPC_TIMEOUT_MS;
-
-        // Determine user message: positional args or stdin.
-        let messageText = messageParts.length > 0 ? messageParts.join(" ") : "";
-
-        if (!messageText && !process.stdin.isTTY) {
-          try {
-            messageText = readStdinSync().trim();
-          } catch {
-            // stdin not available or empty
-          }
-        }
+  subcommand(group, "send").action(
+    async (
+      messageParts: string[],
+      opts: {
+        systemPrompt?: string;
+        model?: string;
+        profile?: string;
+        maxTokens?: string;
+        timeoutSeconds?: string;
+        json?: boolean;
+      },
+    ) => {
+      const { systemPrompt, model, profile, json: jsonOutput } = opts;
+      const parsedMaxTokens = parsePositiveIntegerOption(
+        opts.maxTokens,
+        "--max-tokens",
+      );
+      const parsedTimeoutSeconds = parsePositiveIntegerOption(
+        opts.timeoutSeconds,
+        "--timeout-seconds",
+        { max: MAX_INFERENCE_TIMEOUT_SECONDS },
+      );
 
-        if (!messageText) {
-          const msg =
-            "No message provided. Pass a message as an argument or pipe via stdin.";
-          writeCliError(msg, jsonOutput);
-          return;
+      if (!parsedMaxTokens.ok) {
+        writeCliError(parsedMaxTokens.error, jsonOutput);
+        return;
+      }
+
+      if (!parsedTimeoutSeconds.ok) {
+        writeCliError(parsedTimeoutSeconds.error, jsonOutput);
+        return;
+      }
+
+      const maxTokens = parsedMaxTokens.value;
+      const timeoutMs =
+        parsedTimeoutSeconds.value !== undefined
+          ? parsedTimeoutSeconds.value * 1000
+          : DEFAULT_INFERENCE_IPC_TIMEOUT_MS;
+
+      // Determine user message: positional args or stdin.
+      let messageText = messageParts.length > 0 ? messageParts.join(" ") : "";
+
+      if (!messageText && !process.stdin.isTTY) {
+        try {
+          messageText = readStdinSync().trim();
+        } catch {
+          // stdin not available or empty
         }
+      }
+
+      if (!messageText) {
+        const msg =
+          "No message provided. Pass a message as an argument or pipe via stdin.";
+        writeCliError(msg, jsonOutput);
+        return;
+      }
+
+      // Build IPC body
+      const body: Record<string, unknown> = { message: messageText };
+      if (systemPrompt) {
+        body.systemPrompt = systemPrompt;
+      }
+      if (model) {
+        body.model = model;
+      }
+      if (profile) {
+        body.profile = profile;
+      }
+      if (maxTokens) {
+        body.maxTokens = maxTokens;
+      }
+
+      const ipcResult = await cliIpcCall<InferenceSendResult>(
+        "inference_send",
+        { body },
+        { timeoutMs },
+      );
 
-        // Build IPC body
-        const body: Record<string, unknown> = { message: messageText };
-        if (systemPrompt) body.systemPrompt = systemPrompt;
-        if (model) body.model = model;
-        if (profile) body.profile = profile;
-        if (maxTokens) body.maxTokens = maxTokens;
-
-        const ipcResult = await cliIpcCall<InferenceSendResult>(
-          "inference_send",
-          { body },
-          { timeoutMs },
+      if (!ipcResult.ok) {
+        writeCliError(ipcResult.error ?? "Unknown error occurred", jsonOutput);
+        return;
+      }
+
+      const result = ipcResult.result!;
+
+      if (jsonOutput) {
+        process.stdout.write(
+          JSON.stringify({
+            ok: true,
+            response: result.response,
+            model: result.model,
+            usage: result.usage,
+          }) + "\n",
         );
-
-        if (!ipcResult.ok) {
-          writeCliError(
-            ipcResult.error ?? "Unknown error occurred",
-            jsonOutput,
-          );
-          return;
-        }
-
-        const result = ipcResult.result!;
-
-        if (jsonOutput) {
-          process.stdout.write(
-            JSON.stringify({
-              ok: true,
-              response: result.response,
-              model: result.model,
-              usage: result.usage,
-            }) + "\n",
-          );
-        } else {
-          process.stdout.write(result.response + "\n");
-        }
-      },
-    );
+      } else {
+        process.stdout.write(result.response + "\n");
+      }
+    },
+  );
 }
 
 // ── Registration ─────────────────────────────────────────────────────
@@ -230,23 +198,11 @@ Examples:
  */
 export function registerInferenceCommand(program: Command): void {
   registerCommand(program, {
-    name: "inference",
+    name: inferenceHelp.name,
     transport: "ipc",
-    description: "LLM inference operations",
+    description: inferenceHelp.description,
     build: (inference) => {
-      inference.addHelpText(
-        "after",
-        `
-The inference command group sends requests to your configured LLM provider.
-The provider is resolved from your assistant config (llm.default.provider).
-
-Examples:
-  $ assistant inference send "What is the capital of France?"
-  $ echo "Explain quantum computing" | assistant inference send
-  $ assistant llm send --system-prompt "Be concise" "What is TCP?"
-  $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
-  $ assistant inference send --profile balanced "Explain RFC 1149"`,
-      );
+      applyCommandHelp(inference, inferenceHelp);
 
       attachSendSubcommand(inference);
       attachSessionSubcommand(inference);
@@ -257,24 +213,7 @@ Examples:
     },
   });
 
-  const llm = program
-    .command("llm")
-    .description("LLM inference operations (alias for 'inference send')");
-
-  llm.addHelpText(
-    "after",
-    `
-The llm command group is a shorthand for 'assistant inference send'. It sends
-requests to your configured LLM provider, resolved from your assistant config
-(llm.default.provider). For profile session management, use 'assistant inference session'.
-
-Examples:
-  $ assistant llm send "What is the capital of France?"
-  $ echo "Explain quantum computing" | assistant llm send
-  $ assistant llm send --system-prompt "Be concise" "What is TCP?"
-  $ assistant llm send --model claude-sonnet-4-20250514 --json "Hello"
-  $ assistant llm send --profile balanced "Explain RFC 1149"`,
-  );
-
+  const llm = program.command(llmHelp.name).description(llmHelp.description);
+  applyCommandHelp(llm, llmHelp);
   attachSendSubcommand(llm);
 }

package/src/cli/commands/keys.help.ts

@@ -0,0 +1,46 @@
+/** Declarative help for the `assistant keys` command. */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const keysHelp: CliCommandHelp = {
+  name: "keys",
+  description: "Manage API keys in secure storage",
+  subcommands: [
+    {
+      name: "list",
+      description: "List all stored API key names",
+    },
+    {
+      name: "set",
+      args: "<provider> <key>",
+      description:
+        "Store an API key (e.g. assistant keys set anthropic sk-ant-...)",
+      helpText: `
+Arguments:
+  provider   Provider name (e.g. anthropic, openai, gemini)
+  key        The API key value to store
+
+If a key already exists for the given provider, it is silently overwritten.
+
+Examples:
+  $ assistant keys set anthropic sk-ant-abc123
+  $ assistant keys set openai sk-proj-xyz789
+  $ assistant keys set fireworks fw-abc123`,
+    },
+    {
+      name: "delete",
+      args: "<provider>",
+      description: "Delete a stored API key",
+      helpText: `
+Arguments:
+  provider   Provider name whose key should be removed from secure storage
+
+Removes the API key for the given provider from secure local storage. If
+no key exists for the provider, exits with an error.
+
+Examples:
+  $ assistant keys delete openai
+  $ assistant keys delete anthropic`,
+    },
+  ],
+};

package/src/cli/commands/keys.ts

@@ -2,8 +2,10 @@ import { createRequire } from "node:module";
 
 import type { Command } from "commander";
 
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { keysHelp } from "./keys.help.js";
 
 const loadModule = createRequire(import.meta.url);
 
@@ -21,10 +23,15 @@ function apiKeyProviders(): readonly string[] {
 
 export function registerKeysCommand(program: Command): void {
   registerCommand(program, {
-    name: "keys",
+    name: keysHelp.name,
     transport: "local",
-    description: "Manage API keys in secure storage",
+    description: keysHelp.description,
     build: (keys) => {
+      applyCommandHelp(keys, keysHelp);
+
+      // These help texts interpolate the lazily-loaded provider catalog at
+      // render time, so they stay imperative here rather than in the
+      // declarative help module.
       keys.addHelpText(
         "after",
         () => `
@@ -39,9 +46,7 @@ Examples:
   $ assistant keys delete openai`,
       );
 
-      keys
-        .command("list")
-        .description("List all stored API key names")
+      subcommand(keys, "list")
         .addHelpText(
           "after",
           () => `
@@ -75,73 +80,34 @@ Examples:
           }
         });
 
-      keys
-        .command("set <provider> <key>")
-        .description(
-          "Store an API key (e.g. assistant keys set anthropic sk-ant-...)",
-        )
-        .addHelpText(
-          "after",
-          `
-Arguments:
-  provider   Provider name (e.g. anthropic, openai, gemini)
-  key        The API key value to store
-
-If a key already exists for the given provider, it is silently overwritten.
-
-Examples:
-  $ assistant keys set anthropic sk-ant-abc123
-  $ assistant keys set openai sk-proj-xyz789
-  $ assistant keys set fireworks fw-abc123`,
-        )
-        .action(async (provider: string, key: string) => {
-          const { setSecureKeyViaDaemon } =
-            await import("../lib/daemon-credential-client.js");
-          const setResult = await setSecureKeyViaDaemon(
-            "api_key",
-            provider,
-            key,
-          );
-          if (setResult.ok) {
-            log.info(`Stored API key for "${provider}"`);
-          } else {
-            const detail = setResult.error ? `: ${setResult.error}` : "";
-            log.error(`Failed to store API key for "${provider}"${detail}`);
-            process.exit(1);
-          }
-        });
-
-      keys
-        .command("delete <provider>")
-        .description("Delete a stored API key")
-        .addHelpText(
-          "after",
-          `
-Arguments:
-  provider   Provider name whose key should be removed from secure storage
-
-Removes the API key for the given provider from secure local storage. If
-no key exists for the provider, exits with an error.
+      subcommand(keys, "set").action(async (provider: string, key: string) => {
+        const { setSecureKeyViaDaemon } =
+          await import("../lib/daemon-credential-client.js");
+        const setResult = await setSecureKeyViaDaemon("api_key", provider, key);
+        if (setResult.ok) {
+          log.info(`Stored API key for "${provider}"`);
+        } else {
+          const detail = setResult.error ? `: ${setResult.error}` : "";
+          log.error(`Failed to store API key for "${provider}"${detail}`);
+          process.exit(1);
+        }
+      });
 
-Examples:
-  $ assistant keys delete openai
-  $ assistant keys delete anthropic`,
-        )
-        .action(async (provider: string) => {
-          const { deleteSecureKeyViaDaemon } =
-            await import("../lib/daemon-credential-client.js");
-          const delResult = await deleteSecureKeyViaDaemon("api_key", provider);
-          if (delResult.result === "deleted") {
-            log.info(`Deleted API key for "${provider}"`);
-          } else if (delResult.result === "error") {
-            const detail = delResult.error ? `: ${delResult.error}` : "";
-            log.error(`Failed to delete API key for "${provider}"${detail}`);
-            process.exit(1);
-          } else {
-            log.error(`No API key found for "${provider}"`);
-            process.exit(1);
-          }
-        });
+      subcommand(keys, "delete").action(async (provider: string) => {
+        const { deleteSecureKeyViaDaemon } =
+          await import("../lib/daemon-credential-client.js");
+        const delResult = await deleteSecureKeyViaDaemon("api_key", provider);
+        if (delResult.result === "deleted") {
+          log.info(`Deleted API key for "${provider}"`);
+        } else if (delResult.result === "error") {
+          const detail = delResult.error ? `: ${delResult.error}` : "";
+          log.error(`Failed to delete API key for "${provider}"${detail}`);
+          process.exit(1);
+        } else {
+          log.error(`No API key found for "${provider}"`);
+          process.exit(1);
+        }
+      });
     },
   });
 }

package/src/cli/commands/mcp.help.ts

@@ -0,0 +1,167 @@
+/** Declarative help for the `assistant mcp` command. */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const mcpHelp: CliCommandHelp = {
+  name: "mcp",
+  description: "Manage MCP (Model Context Protocol) servers",
+  helpText: `
+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
+
+MCP server configuration changes are detected automatically by the running
+assistant. You can also run 'vellum mcp reload' to trigger a manual reload.
+
+Examples:
+  $ 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`,
+  subcommands: [
+    {
+      name: "list",
+      description: "List configured MCP servers and their status",
+      options: [{ flags: "--json", description: "Output as JSON" }],
+      helpText: `
+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)
+
+Health checks run on the daemon side. With --json, outputs the raw server
+list including health status.
+
+Examples:
+  $ assistant mcp list
+  $ assistant mcp list --json`,
+    },
+    {
+      name: "reload",
+      description: "Reload MCP server connections in the running assistant",
+      helpText: `
+Signals the running assistant to disconnect and reconnect all MCP servers
+using the current configuration from disk. Active sessions pick up new tools
+on their next turn automatically. The assistant must be running.
+
+Examples:
+  $ vellum mcp reload
+  $ vellum mcp reload   # after editing config.json to add a new server
+  $ vellum mcp reload   # after running "vellum mcp auth <server>"`,
+    },
+    {
+      // NOTE: the repeatable `-H, --header` collector option and the trailing
+      // `--disabled` are registered imperatively in `mcp.ts` (array-accumulating
+      // parser functions are not expressible as plain help data).
+      name: "add",
+      args: "<name>",
+      description: "Add an MCP server configuration",
+      options: [
+        {
+          flags: "-t, --transport-type <type>",
+          description: "Transport type: stdio, sse, or streamable-http",
+          required: true,
+        },
+        {
+          flags: "-u, --url <url>",
+          description: "Server URL (for sse/streamable-http)",
+        },
+        {
+          flags: "-c, --command <cmd>",
+          description: "Command to run (for stdio)",
+        },
+        {
+          flags: "-a, --args <args...>",
+          description: "Command arguments (for stdio)",
+        },
+        {
+          flags: "-r, --risk <level>",
+          description: "Default risk level: low, medium, or high",
+          defaultValue: "high",
+        },
+      ],
+      helpText: `
+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.
+
+The --header (-H) flag adds custom HTTP headers to sse/streamable-http
+transports. Use it for Bearer Token or API Key authentication. The flag
+is repeatable — pass multiple -H flags for multiple headers.
+
+If a server with the same name already exists, the command fails. Remove the
+existing server first with "assistant mcp remove <name>".
+
+Examples:
+  $ 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
+  $ assistant mcp add authed-api -t sse -u https://api.example.com/mcp -H 'Authorization: Bearer tok123'
+  $ assistant mcp add apikey-srv -t streamable-http -u https://srv.example.com/mcp -H 'X-API-Key: sk_live_abc'`,
+    },
+    {
+      name: "auth",
+      args: "<name>",
+      description: "Authenticate with an MCP server via OAuth",
+      helpText: `
+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. The
+running assistant handles the OAuth callback and token exchange.
+
+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, the running assistant detects the change
+automatically. You can also run 'vellum mcp reload' to apply immediately.
+
+Examples:
+  $ assistant mcp auth my-server
+  $ assistant mcp auth remote-api`,
+    },
+    {
+      name: "remove",
+      args: "<name>",
+      description: "Remove an MCP server configuration",
+      helpText: `
+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, the running assistant detects the change automatically. You
+can also run 'vellum mcp reload' to apply immediately.
+
+Examples:
+  $ assistant mcp remove my-server
+  $ assistant mcp remove legacy-sse`,
+    },
+  ],
+};