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

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

@@ -18,7 +18,6 @@ let mockResponse: unknown = {
     available: false,
     organizationId: null,
     userId: null,
-    velayTunnel: null,
   },
 };
 
@@ -63,7 +62,6 @@ describe("assistant platform status", () => {
         available: false,
         organizationId: null,
         userId: null,
-        velayTunnel: null,
       },
     };
     process.exitCode = 0;
@@ -81,7 +79,6 @@ describe("assistant platform status", () => {
         available: true,
         organizationId: "org-456",
         userId: "user-789",
-        velayTunnel: null,
       },
     };
 
@@ -116,93 +113,6 @@ describe("assistant platform status", () => {
     expect(parsed.available).toBe(true);
     expect(parsed.organizationId).toBe("org-456");
     expect(parsed.userId).toBe("user-789");
-    expect(parsed.velayTunnel).toBeNull();
-  });
-
-  test("velayTunnel connected with publicUrl is returned when gateway is live", async () => {
-    mockResponse = {
-      ok: true,
-      result: {
-        isPlatform: false,
-        baseUrl: "",
-        assistantId: "",
-        hasAssistantApiKey: false,
-        hasWebhookSecret: false,
-        available: false,
-        organizationId: null,
-        userId: null,
-        velayTunnel: {
-          connected: true,
-          publicUrl: "https://abc123.vellum.ai",
-        },
-      },
-    };
-
-    const program = buildProgram();
-    const stdoutChunks: string[] = [];
-    const origWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = ((chunk: unknown) => {
-      stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
-      return true;
-    }) as typeof process.stdout.write;
-
-    try {
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "status",
-        "--json",
-      ]);
-    } finally {
-      process.stdout.write = origWrite;
-    }
-
-    const parsed = JSON.parse(stdoutChunks.join(""));
-    expect(parsed.velayTunnel).toEqual({
-      connected: true,
-      publicUrl: "https://abc123.vellum.ai",
-    });
-  });
-
-  test("velayTunnel disconnected when gateway reports no active connection", async () => {
-    mockResponse = {
-      ok: true,
-      result: {
-        isPlatform: false,
-        baseUrl: "",
-        assistantId: "",
-        hasAssistantApiKey: false,
-        hasWebhookSecret: false,
-        available: false,
-        organizationId: null,
-        userId: null,
-        velayTunnel: { connected: false, publicUrl: null },
-      },
-    };
-
-    const program = buildProgram();
-    const stdoutChunks: string[] = [];
-    const origWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = ((chunk: unknown) => {
-      stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
-      return true;
-    }) as typeof process.stdout.write;
-
-    try {
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "status",
-        "--json",
-      ]);
-    } finally {
-      process.stdout.write = origWrite;
-    }
-
-    const parsed = JSON.parse(stdoutChunks.join(""));
-    expect(parsed.velayTunnel).toEqual({ connected: false, publicUrl: null });
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {

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

@@ -1,35 +1,23 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { subcommand } from "../../lib/cli-command-help.js";
 import { log } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 
 export function registerPlatformConnectCommand(platform: Command): void {
-  platform
-    .command("connect")
-    .description(
-      "Connect this assistant to the Vellum Platform by storing credentials",
-    )
-    .addHelpText(
-      "after",
-      `
-Initiates a platform connection flow. Emits a signal for connected clients
-to show a platform login UI where the user can sign in and store credentials.
-
-Use 'assistant platform status' to check the current connection state and
-'assistant platform disconnect' to remove stored credentials.
-
-Examples:
-  $ assistant platform connect
-  $ assistant platform connect --json`,
-    )
-    .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+  subcommand(platform, "connect").action(
+    async (_opts: Record<string, unknown>, cmd: Command) => {
       const r = await cliIpcCall<{
         alreadyConnected?: boolean;
         baseUrl?: string;
         showPlatformLogin?: boolean;
       }>("platform_connect", {});
-      if (!r.ok) return exitFromIpcResult({ ok: false, error: r.error, statusCode: r.statusCode }, cmd);
+      if (!r.ok)
+        return exitFromIpcResult(
+          { ok: false, error: r.error, statusCode: r.statusCode },
+          cmd,
+        );
 
       writeOutput(cmd, { ok: true, ...r.result });
 
@@ -46,5 +34,6 @@ Examples:
           );
         }
       }
-    });
+    },
+  );
 }

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

@@ -1,44 +1,29 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { subcommand } from "../../lib/cli-command-help.js";
 import { log } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 
 export function registerPlatformDisconnectCommand(platform: Command): void {
-  platform
-    .command("disconnect")
-    .description(
-      "Disconnect from the Vellum Platform by removing stored credentials",
-    )
-    .addHelpText(
-      "after",
-      `
-Removes all stored platform credentials from the assistant's secure
-credential store. After disconnecting, platform-managed features (managed
-proxy, managed OAuth, callback routing) will no longer be available until
-you reconnect with 'assistant platform connect'.
-
-Use 'assistant platform status' to check the current connection state
-before disconnecting.
-
-Examples:
-  $ assistant platform disconnect
-  $ assistant platform disconnect --json`,
-    )
-    .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+  subcommand(platform, "disconnect").action(
+    async (_opts: Record<string, unknown>, cmd: Command) => {
       const r = await cliIpcCall<{
         disconnected: boolean;
         previousBaseUrl: string | null;
       }>("platform_disconnect", {});
-      if (!r.ok) return exitFromIpcResult({ ok: false, error: r.error, statusCode: r.statusCode }, cmd);
+      if (!r.ok)
+        return exitFromIpcResult(
+          { ok: false, error: r.error, statusCode: r.statusCode },
+          cmd,
+        );
 
       writeOutput(cmd, { ok: true, ...r.result });
 
       if (!shouldOutputJson(cmd)) {
         const prev = r.result?.previousBaseUrl;
-        log.info(
-          `Disconnected from platform${prev ? ` at ${prev}` : ""}`,
-        );
+        log.info(`Disconnected from platform${prev ? ` at ${prev}` : ""}`);
       }
-    });
+    },
+  );
 }

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

@@ -0,0 +1,187 @@
+/** Declarative help for the `assistant platform` command. */
+
+import type { CliCommandHelp } from "../../lib/cli-command-help.js";
+
+export const platformHelp: CliCommandHelp = {
+  name: "platform",
+  description: "Manage Vellum Platform integration",
+  options: [
+    { flags: "--json", description: "Machine-readable compact JSON output" },
+  ],
+  helpText: `
+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.
+
+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
+  $ assistant platform credits --json
+  $ assistant platform connect
+  $ assistant platform disconnect
+  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json`,
+  subcommands: [
+    {
+      name: "connect",
+      description:
+        "Connect this assistant to the Vellum Platform by storing credentials",
+      helpText: `
+Initiates a platform connection flow. Emits a signal for connected clients
+to show a platform login UI where the user can sign in and store credentials.
+
+Use 'assistant platform status' to check the current connection state and
+'assistant platform disconnect' to remove stored credentials.
+
+Examples:
+  $ assistant platform connect
+  $ assistant platform connect --json`,
+    },
+    {
+      name: "status",
+      description:
+        "Show current platform deployment context and connection status",
+      helpText: `
+Reads platform-related environment variables and stored credentials to report
+the current platform deployment context and connection state.
+
+Fields:
+  isPlatform          Whether IS_PLATFORM is set (boolean)
+  baseUrl             VELLUM_PLATFORM_URL — the platform gateway base URL
+  assistantId         This assistant's platform UUID
+  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
+  organizationId      The platform organization ID (from stored credentials)
+  userId              The platform user ID (from stored credentials)
+
+For the Velay tunnel state (only relevant for Twilio webhooks and live
+voice/audio), use 'assistant gateway status' instead.
+
+Examples:
+  $ assistant platform status
+  $ assistant platform status --json`,
+    },
+    {
+      name: "credits",
+      description: "Show the organization's remaining credit balance",
+      helpText: `
+Fetches the org's credit balance from the platform billing summary.
+
+Fields:
+  remaining   Effective balance (settled minus pending charges) in USD
+  settled     On-ledger balance in USD
+  pending     Estimated pending compute charges not yet settled, in USD
+  unit        Balance currency (USD)
+  stale       True when pending-charge data may be stale or unavailable
+  as_of       When this balance was read (response receipt time)
+
+Combine with 'assistant usage daily' to compute runway (remaining divided
+by rolling daily average) and warn before credits run out.
+
+Requires platform credentials (run 'assistant platform connect' first or
+ensure VELLUM_PLATFORM_URL is set and credentials are stored).
+
+Examples:
+  $ assistant platform credits
+  $ assistant platform credits --json`,
+    },
+    {
+      name: "disconnect",
+      description:
+        "Disconnect from the Vellum Platform by removing stored credentials",
+      helpText: `
+Removes all stored platform credentials from the assistant's secure
+credential store. After disconnecting, platform-managed features (managed
+proxy, managed OAuth, callback routing) will no longer be available until
+you reconnect with 'assistant platform connect'.
+
+Use 'assistant platform status' to check the current connection state
+before disconnecting.
+
+Examples:
+  $ assistant platform disconnect
+  $ assistant platform disconnect --json`,
+    },
+    {
+      name: "callback-routes",
+      description: "Manage platform callback route registrations",
+      helpText: `
+Callback routes tell the platform gateway how to forward inbound provider
+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`,
+      subcommands: [
+        {
+          name: "register",
+          description: "Register a callback route with the platform gateway",
+          options: [
+            {
+              flags: "--path <path>",
+              description:
+                "Callback path (e.g. webhooks/telegram, webhooks/twilio/voice)",
+              required: true,
+            },
+            {
+              flags: "--type <type>",
+              description:
+                "Route type identifier (e.g. telegram, twilio_voice, twilio_status, oauth)",
+              required: true,
+            },
+          ],
+          helpText: `
+Registers a callback route with the platform's internal gateway endpoint so
+the platform knows how to forward inbound provider webhooks to this
+platform-managed assistant instance.
+
+Arguments:
+  --path    The path portion after the ingress base URL. Leading/trailing
+            slashes are stripped by the platform.
+  --type    The route type identifier used by the platform to classify and
+            route the callback.
+
+Known callback path/type combinations:
+  --path webhooks/telegram          --type telegram
+  --path webhooks/twilio/voice      --type twilio_voice
+  --path webhooks/twilio/status     --type twilio_status
+  --path webhooks/resend            --type resend
+  --path webhooks/mailgun           --type mailgun
+  --path webhooks/email             --type email
+  --path oauth/callback             --type oauth
+
+Works for both platform-managed and self-hosted assistants. Requires
+VELLUM_PLATFORM_URL and a platform assistant ID. Returns the platform-provided
+stable callback URL that external services should use.
+
+Examples:
+  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
+  $ assistant platform callback-routes register --path webhooks/twilio/voice --type twilio_voice --json`,
+        },
+        {
+          name: "list",
+          description: "List registered callback routes for this assistant",
+          helpText: `
+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 and VELLUM_PLATFORM_URL are set and credentials are stored).
+
+Examples:
+  $ assistant platform callback-routes list
+  $ assistant platform callback-routes list --json`,
+        },
+      ],
+    },
+  ],
+};

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

@@ -7,11 +7,13 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../../ipc/cli-client.js";
+import { applyCommandHelp, subcommand } from "../../lib/cli-command-help.js";
 import { registerCommand } from "../../lib/register-command.js";
 import { log } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 import { registerPlatformConnectCommand } from "./connect.js";
 import { registerPlatformDisconnectCommand } from "./disconnect.js";
+import { platformHelp } from "./index.help.js";
 
 interface PlatformStatusResult {
   isPlatform: boolean;
@@ -22,7 +24,6 @@ interface PlatformStatusResult {
   available: boolean;
   organizationId: string | null;
   userId: string | null;
-  velayTunnel: { connected: boolean; publicUrl: string | null } | null;
 }
 
 interface PlatformCreditsResult {
@@ -36,31 +37,11 @@ interface PlatformCreditsResult {
 
 export function registerPlatformCommand(program: Command): void {
   registerCommand(program, {
-    name: "platform",
+    name: platformHelp.name,
     transport: "ipc",
-    description: "Manage Vellum Platform integration",
+    description: platformHelp.description,
     build: (platform) => {
-      platform.option("--json", "Machine-readable compact JSON output");
-
-      platform.addHelpText(
-        "after",
-        `
-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.
-
-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
-  $ assistant platform credits --json
-  $ assistant platform connect
-  $ assistant platform disconnect
-  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json`,
-      );
+      applyCommandHelp(platform, platformHelp);
 
       // -----------------------------------------------------------------------
       // connect
@@ -72,35 +53,8 @@ Examples:
       // status
       // -----------------------------------------------------------------------
 
-      platform
-        .command("status")
-        .description(
-          "Show current platform deployment context and connection status",
-        )
-        .addHelpText(
-          "after",
-          `
-Reads platform-related environment variables and stored credentials to report
-the current platform deployment context and connection state.
-
-Fields:
-  isPlatform          Whether IS_PLATFORM is set (boolean)
-  baseUrl             VELLUM_PLATFORM_URL — the platform gateway base URL
-  assistantId         This assistant's platform UUID
-  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
-  organizationId      The platform organization ID (from stored credentials)
-  userId              The platform user ID (from stored credentials)
-  velayTunnel         Live Velay tunnel status from the gateway IPC socket
-                      (null when the gateway is not running)
-
-Examples:
-  $ assistant platform status
-  $ assistant platform status --json`,
-        )
-        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      subcommand(platform, "status").action(
+        async (_opts: Record<string, unknown>, cmd: Command) => {
           const r = await cliIpcCall<PlatformStatusResult>(
             "platform_status",
             {},
@@ -132,48 +86,16 @@ Examples:
               `Organization ID: ${result.organizationId || "(not set)"}`,
             );
             log.info(`User ID: ${result.userId || "(not set)"}`);
-            if (result.velayTunnel !== null) {
-              const tunnelState = result.velayTunnel.connected
-                ? `connected${result.velayTunnel.publicUrl ? ` (${result.velayTunnel.publicUrl})` : ""}`
-                : "disconnected";
-              log.info(`Velay tunnel: ${tunnelState}`);
-            } else {
-              log.info(`Velay tunnel: (gateway not running)`);
-            }
           }
-        });
+        },
+      );
 
       // -----------------------------------------------------------------------
       // credits
       // -----------------------------------------------------------------------
 
-      platform
-        .command("credits")
-        .description("Show the organization's remaining credit balance")
-        .addHelpText(
-          "after",
-          `
-Fetches the org's credit balance from the platform billing summary.
-
-Fields:
-  remaining   Effective balance (settled minus pending charges) in USD
-  settled     On-ledger balance in USD
-  pending     Estimated pending compute charges not yet settled, in USD
-  unit        Balance currency (USD)
-  stale       True when pending-charge data may be stale or unavailable
-  as_of       When this balance was read (response receipt time)
-
-Combine with 'assistant usage daily' to compute runway (remaining divided
-by rolling daily average) and warn before credits run out.
-
-Requires platform credentials (run 'assistant platform connect' first or
-ensure VELLUM_PLATFORM_URL is set and credentials are stored).
-
-Examples:
-  $ assistant platform credits
-  $ assistant platform credits --json`,
-        )
-        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      subcommand(platform, "credits").action(
+        async (_opts: Record<string, unknown>, cmd: Command) => {
           const r = await cliIpcCall<PlatformCreditsResult>(
             "platform_credits",
             {},
@@ -199,7 +121,8 @@ Examples:
               `Settled:   $${result.settled.toFixed(2)}   Pending: $${result.pending.toFixed(2)}`,
             );
           }
-        });
+        },
+      );
 
       // -----------------------------------------------------------------------
       // disconnect
@@ -211,71 +134,14 @@ Examples:
       // callback-routes
       // -----------------------------------------------------------------------
 
-      const callbackRoutes = platform
-        .command("callback-routes")
-        .description("Manage platform callback route registrations");
-
-      callbackRoutes.addHelpText(
-        "after",
-        `
-Callback routes tell the platform gateway how to forward inbound provider
-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`,
-      );
+      const callbackRoutes = subcommand(platform, "callback-routes");
 
       // -----------------------------------------------------------------------
       // callback-routes register
       // -----------------------------------------------------------------------
 
-      callbackRoutes
-        .command("register")
-        .description("Register a callback route with the platform gateway")
-        .requiredOption(
-          "--path <path>",
-          "Callback path (e.g. webhooks/telegram, webhooks/twilio/voice)",
-        )
-        .requiredOption(
-          "--type <type>",
-          "Route type identifier (e.g. telegram, twilio_voice, twilio_status, oauth)",
-        )
-        .addHelpText(
-          "after",
-          `
-Registers a callback route with the platform's internal gateway endpoint so
-the platform knows how to forward inbound provider webhooks to this
-platform-managed assistant instance.
-
-Arguments:
-  --path    The path portion after the ingress base URL. Leading/trailing
-            slashes are stripped by the platform.
-  --type    The route type identifier used by the platform to classify and
-            route the callback.
-
-Known callback path/type combinations:
-  --path webhooks/telegram          --type telegram
-  --path webhooks/twilio/voice      --type twilio_voice
-  --path webhooks/twilio/status     --type twilio_status
-  --path webhooks/resend            --type resend
-  --path webhooks/mailgun           --type mailgun
-  --path webhooks/email             --type email
-  --path oauth/callback             --type oauth
-
-Works for both platform-managed and self-hosted assistants. Requires
-VELLUM_PLATFORM_URL and a platform assistant ID. Returns the platform-provided
-stable callback URL that external services should use.
-
-Examples:
-  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
-  $ assistant platform callback-routes register --path webhooks/twilio/voice --type twilio_voice --json`,
-        )
-        .action(async (opts: { path: string; type: string }, cmd: Command) => {
+      subcommand(callbackRoutes, "register").action(
+        async (opts: { path: string; type: string }, cmd: Command) => {
           const r = await cliIpcCall<{
             callbackUrl: string;
             callbackPath: string;
@@ -294,29 +160,15 @@ Examples:
           if (!shouldOutputJson(cmd)) {
             log.info(`Callback route registered: ${r.result!.callbackUrl}`);
           }
-        });
+        },
+      );
 
       // -----------------------------------------------------------------------
       // 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 and VELLUM_PLATFORM_URL are set and credentials are stored).
-
-Examples:
-  $ assistant platform callback-routes list
-  $ assistant platform callback-routes list --json`,
-        )
-        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      subcommand(callbackRoutes, "list").action(
+        async (_opts: Record<string, unknown>, cmd: Command) => {
           const r = await cliIpcCall<{
             routes: Array<{
               id: string;
@@ -349,7 +201,8 @@ Examples:
               }
             }
           }
-        });
+        },
+      );
     },
   });
 }