@vellumai/assistant 0.6.1 → 0.6.3

package/src/cli/commands/platform/__tests__/callback-routes-list.test.ts

@@ -0,0 +1,259 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+let mockResolvePlatformCallbackRegistrationContext: () => Promise<
+  Record<string, unknown>
+> = async () => ({
+  isPlatform: false,
+  platformBaseUrl: "",
+  assistantId: "",
+  hasInternalApiKey: false,
+  hasAssistantApiKey: false,
+  authHeader: null,
+  enabled: false,
+});
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+mock.module("../../../../inbound/platform-callback-registration.js", () => ({
+  resolvePlatformCallbackRegistrationContext: () =>
+    mockResolvePlatformCallbackRegistrationContext(),
+  registerCallbackRoute: async () => "",
+  shouldUsePlatformCallbacks: () => false,
+  resolveCallbackUrl: async () => "",
+}));
+
+mock.module("../../../lib/daemon-credential-client.js", () => ({
+  getSecureKeyViaDaemon: async () => undefined,
+  deleteSecureKeyViaDaemon: async () => "not-found" as const,
+  setSecureKeyViaDaemon: async () => false,
+  getProviderKeyViaDaemon: async () => undefined,
+  getSecureKeyResultViaDaemon: async () => ({
+    value: undefined,
+    unreachable: false,
+  }),
+}));
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+  getCliLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+  initLogger: () => {},
+  truncateForLog: (value: string, maxLen = 500) =>
+    value.length > maxLen ? value.slice(0, maxLen) + "..." : value,
+  pruneOldLogFiles: () => 0,
+}));
+
+mock.module("../../../../config/loader.js", () => ({
+  API_KEY_PROVIDERS: [] as const,
+  getConfig: () => ({
+    permissions: { mode: "workspace" },
+    skills: { load: { extraDirs: [] } },
+    sandbox: { enabled: true },
+  }),
+  loadConfig: () => ({}),
+  invalidateConfigCache: () => {},
+  saveConfig: () => {},
+  loadRawConfig: () => ({}),
+  saveRawConfig: () => {},
+  getNestedValue: () => undefined,
+  setNestedValue: () => {},
+  applyNestedDefaults: (config: unknown) => config,
+  deepMergeMissing: () => false,
+  deepMergeOverwrite: () => {},
+  mergeDefaultWorkspaceConfig: () => {},
+}));
+
+// ---------------------------------------------------------------------------
+// Import shared test utility (after mocks are registered)
+// ---------------------------------------------------------------------------
+
+const { runAssistantCommandFull } =
+  await import("../../../__tests__/run-assistant-command.js");
+
+// ---------------------------------------------------------------------------
+// Fetch mock
+// ---------------------------------------------------------------------------
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function connectedContext(
+  overrides: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    isPlatform: false,
+    platformBaseUrl: "https://dev-platform.vellum.ai",
+    assistantId: "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+    hasInternalApiKey: false,
+    hasAssistantApiKey: true,
+    authHeader: "Api-Key vak_test123",
+    enabled: false,
+    ...overrides,
+  };
+}
+
+function mockFetchJson(body: unknown, status = 200): void {
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    })) as unknown as typeof globalThis.fetch;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("assistant platform callback-routes list", () => {
+  beforeEach(() => {
+    mockResolvePlatformCallbackRegistrationContext = async () =>
+      connectedContext();
+    process.exitCode = 0;
+  });
+
+  afterEach(() => {
+    process.exitCode = 0;
+  });
+
+  test("returns empty list when no routes registered", async () => {
+    mockFetchJson([]);
+
+    const { stdout } = await runAssistantCommandFull(
+      "platform",
+      "callback-routes",
+      "list",
+      "--json",
+    );
+
+    expect(process.exitCode ?? 0).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.routes).toEqual([]);
+  });
+
+  test("returns registered routes", async () => {
+    const routes = [
+      {
+        id: "route-1",
+        assistant_id: "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+        type: "email",
+        callback_path: "019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/email",
+        callback_url:
+          "https://dev-platform.vellum.ai/v1/gateway/callbacks/019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/email/",
+      },
+      {
+        id: "route-2",
+        assistant_id: "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+        type: "telegram",
+        callback_path: "019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/telegram",
+        callback_url:
+          "https://dev-platform.vellum.ai/v1/gateway/callbacks/019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/telegram/",
+      },
+    ];
+    mockFetchJson(routes);
+
+    const { stdout } = await runAssistantCommandFull(
+      "platform",
+      "callback-routes",
+      "list",
+      "--json",
+    );
+
+    expect(process.exitCode ?? 0).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.routes).toHaveLength(2);
+    expect(parsed.routes[0].type).toBe("email");
+    expect(parsed.routes[1].type).toBe("telegram");
+  });
+
+  test("fails when platform credentials are missing", async () => {
+    mockResolvePlatformCallbackRegistrationContext = async () => ({
+      isPlatform: false,
+      platformBaseUrl: "",
+      assistantId: "",
+      hasInternalApiKey: false,
+      hasAssistantApiKey: false,
+      authHeader: null,
+      enabled: false,
+    });
+
+    const { stdout } = await runAssistantCommandFull(
+      "platform",
+      "callback-routes",
+      "list",
+      "--json",
+    );
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toContain("Platform credentials not available");
+  });
+
+  test("handles platform HTTP error", async () => {
+    mockFetchJson({ detail: "Unauthorized" }, 401);
+
+    const { stdout } = await runAssistantCommandFull(
+      "platform",
+      "callback-routes",
+      "list",
+      "--json",
+    );
+
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toContain("HTTP 401");
+  });
+
+  test("works for self-hosted assistants with connected credentials", async () => {
+    mockResolvePlatformCallbackRegistrationContext = async () =>
+      connectedContext({ isPlatform: false, enabled: false });
+
+    mockFetchJson([
+      {
+        id: "route-1",
+        assistant_id: "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+        type: "email",
+        callback_path: "019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/email",
+        callback_url:
+          "https://dev-platform.vellum.ai/v1/gateway/callbacks/019d6d4f-6dbd-779f-91d3-cb273b9429a5/webhooks/email/",
+      },
+    ]);
+
+    const { stdout } = await runAssistantCommandFull(
+      "platform",
+      "callback-routes",
+      "list",
+      "--json",
+    );
+
+    expect(process.exitCode ?? 0).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.routes).toHaveLength(1);
+  });
+});

package/src/cli/commands/platform/__tests__/connect.test.ts

@@ -109,7 +109,7 @@ async function runCommand(
   process.exitCode = 0;
 
   try {
-    const program = buildCliProgram();
+    const program = await buildCliProgram();
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {},

package/src/cli/commands/platform/__tests__/disconnect.test.ts

@@ -130,7 +130,7 @@ async function runCommand(
   process.exitCode = 0;
 
   try {
-    const program = buildCliProgram();
+    const program = await buildCliProgram();
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {},

package/src/cli/commands/platform/__tests__/status.test.ts

@@ -110,7 +110,7 @@ async function runCommand(
   process.exitCode = 0;
 
   try {
-    const program = buildCliProgram();
+    const program = await buildCliProgram();
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {},

package/src/cli/commands/platform/index.ts

@@ -24,9 +24,10 @@ The platform subsystem manages the connection to Vellum Platform. Use
 'connect', 'status', and 'disconnect' to manage platform credentials.
 Any assistant using the managed LLM proxy can use these commands.
 
-When IS_PLATFORM=true (platform-managed deployments), external service
-callbacks (Telegram webhooks, Twilio webhooks, OAuth redirects) also
-route through the platform's gateway proxy via 'callback-routes'.
+External service callbacks (Telegram webhooks, Twilio webhooks, email,
+OAuth redirects) route through the platform's gateway proxy via
+'callback-routes'. Works for both platform-managed and self-hosted
+assistants.
 
 Examples:
   $ assistant platform status --json
@@ -64,6 +65,8 @@ Fields:
   hasInternalApiKey   Whether PLATFORM_INTERNAL_API_KEY is set (boolean,
                       value not disclosed)
   hasAssistantApiKey  Whether a stored assistant API key is available
+  hasWebhookSecret    Whether a stored webhook secret is available (needed
+                      for email and other inbound webhook channels)
   available           Whether callback registration prerequisites are satisfied
   connected           Whether platform credentials are stored (boolean)
   organizationId      The platform organization ID (from stored credentials)
@@ -109,6 +112,10 @@ Examples:
             )
           )?.trim() ?? "";
 
+        const hasWebhookSecret = !!(await getSecureKeyViaDaemon(
+          credentialKey("vellum", "webhook_secret"),
+        ));
+
         const connected = !!storedBaseUrl && hasStoredApiKey;
 
         const result = {
@@ -117,6 +124,7 @@ Examples:
           assistantId: context.assistantId,
           hasInternalApiKey: context.hasInternalApiKey,
           hasAssistantApiKey: context.hasAssistantApiKey,
+          hasWebhookSecret,
           available: context.enabled,
           connected,
           organizationId: organizationId || null,
@@ -135,6 +143,9 @@ Examples:
           log.info(
             `Assistant API key: ${result.hasAssistantApiKey ? "set" : "not set"}`,
           );
+          log.info(
+            `Webhook secret: ${result.hasWebhookSecret ? "set" : "not set (run ensure-registration to provision)"}`,
+          );
           log.info(
             `Callback registration available: ${result.available ? "yes" : "no"}`,
           );
@@ -167,11 +178,13 @@ Examples:
     "after",
     `
 Callback routes tell the platform gateway how to forward inbound provider
-webhooks to the correct platform-managed assistant instance. Each route maps a
-callback path and type to a stable external URL that external services
-(Telegram, Twilio, OAuth providers) should use.
+webhooks to the correct assistant instance. Each route maps a callback path
+and type to a stable external URL that external services (Telegram, Twilio,
+email, OAuth providers) should use.
 
 Examples:
+  $ assistant platform callback-routes list
+  $ assistant platform callback-routes list --json
   $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
   $ assistant platform callback-routes register --path webhooks/twilio/voice --type twilio_voice --json`,
   );
@@ -210,9 +223,10 @@ Known callback path/type combinations:
   --path webhooks/twilio/status     --type twilio_status
   --path oauth/callback             --type oauth
 
-Requires a platform-managed environment (IS_PLATFORM=true) with
-VELLUM_PLATFORM_URL and PLATFORM_ASSISTANT_ID configured. Returns the
-platform-provided stable callback URL that external services should use.
+Works for both platform-managed and self-hosted assistants. Requires
+VELLUM_PLATFORM_URL and PLATFORM_ASSISTANT_ID (from environment or stored
+credentials via 'assistant platform connect'). Returns the platform-provided
+stable callback URL that external services should use.
 
 Examples:
   $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
@@ -225,7 +239,7 @@ Examples:
           writeOutput(cmd, {
             ok: false,
             error:
-              "Platform callbacks not available — missing platform registration context",
+              "Platform callbacks not available — missing platform base URL, assistant ID, or API key. Run 'assistant platform connect' or ensure credentials are configured.",
           });
           process.exitCode = 1;
           return;
@@ -249,4 +263,87 @@ Examples:
         process.exitCode = 1;
       }
     });
+
+  // ---------------------------------------------------------------------------
+  // callback-routes list
+  // ---------------------------------------------------------------------------
+
+  callbackRoutes
+    .command("list")
+    .description("List registered callback routes for this assistant")
+    .addHelpText(
+      "after",
+      `
+Lists all callback routes registered with the platform for this assistant.
+Shows the route type, callback URL, and path for each registered webhook.
+
+Requires platform credentials (run 'assistant platform connect' first or
+ensure IS_PLATFORM, VELLUM_PLATFORM_URL, and PLATFORM_ASSISTANT_ID are set).
+
+Examples:
+  $ assistant platform callback-routes list
+  $ assistant platform callback-routes list --json`,
+    )
+    .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      try {
+        const context = await resolvePlatformCallbackRegistrationContext();
+        if (!context.platformBaseUrl || !context.authHeader) {
+          writeOutput(cmd, {
+            ok: false,
+            error:
+              "Platform credentials not available — run 'assistant platform connect' or set VELLUM_PLATFORM_URL",
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        const url = `${context.platformBaseUrl}/v1/internal/gateway/callback-routes/`;
+        const response = await fetch(url, {
+          method: "GET",
+          headers: {
+            Authorization: context.authHeader,
+            Accept: "application/json",
+          },
+          signal: AbortSignal.timeout(10_000),
+        });
+
+        if (!response.ok) {
+          const detail = await response.text().catch(() => "");
+          writeOutput(cmd, {
+            ok: false,
+            error: `Failed to list callback routes (HTTP ${response.status}): ${detail}`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        const routes = (await response.json()) as Array<{
+          id: string;
+          assistant_id: string;
+          type: string;
+          callback_path: string;
+          callback_url: string;
+        }>;
+
+        if (shouldOutputJson(cmd)) {
+          writeOutput(cmd, { ok: true, routes });
+        } else {
+          if (routes.length === 0) {
+            log.info("No callback routes registered.");
+          } else {
+            log.info(`${routes.length} callback route(s) registered:\n`);
+            for (const route of routes) {
+              log.info(`  Type: ${route.type}`);
+              log.info(`  URL:  ${route.callback_url}`);
+              log.info(`  Path: ${route.callback_path}`);
+              log.info("");
+            }
+          }
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
 }

package/src/cli/commands/usage.ts

@@ -267,24 +267,25 @@ Examples:
 
   usage
     .command("breakdown")
-    .description("Grouped breakdown by actor, provider, or model")
+    .description("Grouped breakdown by actor, provider, model, or conversation")
     .option(...rangeOption)
     .option(...fromOption)
     .option(...toOption)
     .option(...jsonOption)
     .option(
       "-g, --group-by <dimension>",
-      "Grouping dimension: actor, provider, model",
+      "Grouping dimension: actor, provider, model, conversation",
       "model",
     )
     .addHelpText(
       "after",
       `
 Grouping dimensions:
-  actor     Groups by the subsystem that made the call (main_agent,
-            title_generator, etc.)
-  provider  Groups by LLM provider (anthropic, openai, etc.)
-  model     Groups by model name (claude-sonnet-4-20250514, etc.)
+  actor          Groups by the subsystem that made the call (main_agent,
+                 title_generator, etc.)
+  provider       Groups by LLM provider (anthropic, openai, etc.)
+  model          Groups by model name (claude-sonnet-4-20250514, etc.)
+  conversation   Groups by conversation ID
 
 Shows one row per group with input/output tokens, estimated cost, and
 call count. Rows are sorted by cost descending.
@@ -302,10 +303,10 @@ Examples:
         json?: boolean;
         groupBy: string;
       }) => {
-        const validDimensions = new Set(["actor", "provider", "model"]);
+        const validDimensions = new Set(["actor", "provider", "model", "conversation"]);
         if (!validDimensions.has(opts.groupBy)) {
           log.error(
-            `Invalid --group-by value: '${opts.groupBy}'. Must be one of: actor, provider, model`,
+            `Invalid --group-by value: '${opts.groupBy}'. Must be one of: actor, provider, model, conversation`,
           );
           process.exit(1);
         }
@@ -313,7 +314,7 @@ Examples:
         const { from, to } = resolveRange(opts);
         const breakdown = getUsageGroupBreakdown(
           { from, to },
-          opts.groupBy as "actor" | "provider" | "model",
+          opts.groupBy as "actor" | "provider" | "model" | "conversation",
         );
         if (opts.json) {
           log.info(JSON.stringify({ breakdown }, null, 2));

package/src/cli/lib/daemon-credential-client.ts

@@ -30,6 +30,9 @@ import { getLogger } from "../../util/logger.js";
 const log = getLogger("daemon-credential-client");
 const CREDENTIAL_KEY_PREFIX = "credential/";
 
+/** Hard timeout for daemon HTTP requests to prevent CLI commands from hanging. */
+const DAEMON_FETCH_TIMEOUT_MS = 60_000;
+
 const PROVIDER_ENV_VARS: Record<string, string> = PROVIDER_ENV_VAR_NAMES;
 
 // ---------------------------------------------------------------------------
@@ -64,6 +67,7 @@ async function daemonFetch(
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
       },
+      signal: AbortSignal.timeout(DAEMON_FETCH_TIMEOUT_MS),
     });
 
     if (!res.ok) {

package/src/cli/program.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 
+import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getConfig } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
 import { registerHooksCommand } from "../hooks/cli.js";
@@ -33,13 +34,19 @@ import { registerSkillsCommand } from "./commands/skills.js";
 import { registerTrustCommand } from "./commands/trust.js";
 import { registerUsageCommand } from "./commands/usage.js";
 
-export function buildCliProgram(): Command {
+/**
+ * Build the CLI program tree. Pre-populates the feature flag cache from
+ * the gateway so flag-gated commands are registered correctly.
+ */
+export async function buildCliProgram(): Promise<Command> {
+  await initFeatureFlagOverrides();
   const program = new Command();
 
   program
     .name("assistant")
     .description("Local AI assistant")
-    .version(APP_VERSION);
+    .version(APP_VERSION)
+    .allowExcessArguments(true);
 
   program.addHelpText(
     "after",
@@ -53,6 +60,7 @@ Examples:
 
   registerDefaultAction(program);
   registerBashCommand(program);
+  registerBrowserRelayCommand(program);
   registerConversationsCommand(program);
   registerConfigCommand(program);
   registerKeysCommand(program);
@@ -78,7 +86,6 @@ Examples:
   registerOAuthCommand(program);
   registerRoutesCommand(program);
   registerSkillsCommand(program);
-  registerBrowserRelayCommand(program);
   registerUsageCommand(program);
 
   registerShotgunCommand(program);