@vellumai/assistant 0.11.1 → 0.11.2-staging.2

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

@@ -1,79 +1,13 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 
-import { Command } from "commander";
+import { runPlatform, setupPlatformIpcMock } from "./helpers.js";
 
-// ---------------------------------------------------------------------------
-// Mock state
-// ---------------------------------------------------------------------------
-
-let mockCalls: Array<[string, Record<string, unknown>]> = [];
-let mockResponse: unknown = {
-  ok: true,
-  result: {
-    plans: [
-      {
-        id: "base",
-        name: "Base",
-        price_cents: 0,
-        billing_interval: "month",
-        included_features: ["Pay-as-you-go credits"],
-      },
-      {
-        id: "pro",
-        name: "Pro",
-        base_price_cents: 2000,
-        billing_interval: "month",
-        included_features: ["Configurable machine size"],
-      },
-    ],
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Mocks
-// ---------------------------------------------------------------------------
-
-mock.module("../../../../ipc/cli-client.js", () => ({
-  cliIpcCall: async (method: string, params: Record<string, unknown>) => {
-    mockCalls.push([method, params]);
-    return mockResponse;
-  },
-  exitFromIpcResult: (_r: unknown, _cmd: unknown) => {
-    throw new Error("exitFromIpcResult called");
-  },
-}));
-
-const { registerPlatformCommand } = await import("../index.js");
-
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride();
-  registerPlatformCommand(program);
-  return program;
-}
-
-function captureStdout(fn: () => Promise<void>): Promise<string[]> {
-  const chunks: string[] = [];
-  const origWrite = process.stdout.write.bind(process.stdout);
-  process.stdout.write = ((chunk: unknown) => {
-    chunks.push(typeof chunk === "string" ? chunk : String(chunk));
-    return true;
-  }) as typeof process.stdout.write;
-  return fn()
-    .then(() => chunks)
-    .finally(() => {
-      process.stdout.write = origWrite;
-    });
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
+const ipc = setupPlatformIpcMock();
 
 describe("assistant platform plans", () => {
   beforeEach(() => {
-    mockCalls = [];
-    mockResponse = {
+    ipc.calls = [];
+    ipc.response = {
       ok: true,
       result: {
         plans: [
@@ -94,22 +28,12 @@ describe("assistant platform plans", () => {
         ],
       },
     };
-    process.exitCode = 0;
   });
 
   test("calls platform_plans and emits catalog JSON with --json", async () => {
-    const out = await captureStdout(async () => {
-      const program = buildProgram();
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "plans",
-        "--json",
-      ]);
-    });
+    const out = await runPlatform(["plans", "--json"]);
 
-    expect(mockCalls[0][0]).toBe("platform_plans");
+    expect(ipc.calls[0][0]).toBe("platform_plans");
 
     const parsed = JSON.parse(out.join(""));
     expect(parsed.plans).toHaveLength(2);
@@ -118,12 +42,9 @@ describe("assistant platform plans", () => {
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {
-    const out = await captureStdout(async () => {
-      const program = buildProgram();
-      await program.parseAsync(["node", "assistant", "platform", "plans"]);
-    });
+    const out = await runPlatform(["plans"]);
 
-    // Plain-text mode logs via log.info — verify writeOutput (JSON) was NOT called
+    // Plain-text mode logs via log.info; verify writeOutput (JSON) was NOT called
     expect(() => JSON.parse(out.join("").trim())).toThrow();
   });
 });

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

@@ -1,57 +1,13 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 
-import { Command } from "commander";
+import { runPlatform, setupPlatformIpcMock } from "./helpers.js";
 
-// ---------------------------------------------------------------------------
-// Mock state
-// ---------------------------------------------------------------------------
-
-let mockCalls: Array<[string, Record<string, unknown>]> = [];
-let mockResponse: unknown = {
-  ok: true,
-  result: {
-    isPlatform: false,
-    baseUrl: "",
-    assistantId: "",
-    hasAssistantApiKey: false,
-    hasWebhookSecret: false,
-    available: false,
-    organizationId: null,
-    userId: null,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Mocks
-// ---------------------------------------------------------------------------
-
-mock.module("../../../../ipc/cli-client.js", () => ({
-  cliIpcCall: async (method: string, params: Record<string, unknown>) => {
-    mockCalls.push([method, params]);
-    return mockResponse;
-  },
-  exitFromIpcResult: (_r: unknown, _cmd: unknown) => {
-    throw new Error("exitFromIpcResult called");
-  },
-}));
-
-const { registerPlatformCommand } = await import("../index.js");
-
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride();
-  registerPlatformCommand(program);
-  return program;
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
+const ipc = setupPlatformIpcMock();
 
 describe("assistant platform status", () => {
   beforeEach(() => {
-    mockCalls = [];
-    mockResponse = {
+    ipc.calls = [];
+    ipc.response = {
       ok: true,
       result: {
         isPlatform: false,
@@ -64,11 +20,10 @@ describe("assistant platform status", () => {
         userId: null,
       },
     };
-    process.exitCode = 0;
   });
 
   test("platform pod returns full status from context", async () => {
-    mockResponse = {
+    ipc.response = {
       ok: true,
       result: {
         isPlatform: true,
@@ -82,29 +37,11 @@ describe("assistant platform status", () => {
       },
     };
 
-    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;
+    const out = await runPlatform(["status", "--json"]);
 
-    try {
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "status",
-        "--json",
-      ]);
-    } finally {
-      process.stdout.write = origWrite;
-    }
+    expect(ipc.calls[0][0]).toBe("platform_status");
 
-    expect(mockCalls[0][0]).toBe("platform_status");
-
-    const parsed = JSON.parse(stdoutChunks.join(""));
+    const parsed = JSON.parse(out.join(""));
     expect(parsed.isPlatform).toBe(true);
     expect(parsed.baseUrl).toBe("https://platform.vellum.ai");
     expect(parsed.assistantId).toBe("asst-abc-123");
@@ -116,21 +53,9 @@ describe("assistant platform status", () => {
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {
-    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"]);
-    } finally {
-      process.stdout.write = origWrite;
-    }
+    const out = await runPlatform(["status"]);
 
-    // Plain-text mode logs via log.info — verify writeOutput (JSON) was NOT called
-    expect(() => JSON.parse(stdoutChunks.join("").trim())).toThrow();
+    // Plain-text mode logs via log.info; verify writeOutput (JSON) was NOT called
+    expect(() => JSON.parse(out.join("").trim())).toThrow();
   });
 });

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

@@ -1,72 +1,13 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 
-import { Command } from "commander";
+import { runPlatform, setupPlatformIpcMock } from "./helpers.js";
 
-// ---------------------------------------------------------------------------
-// Mock state
-// ---------------------------------------------------------------------------
-
-let mockCalls: Array<[string, Record<string, unknown>]> = [];
-let mockResponse: unknown = {
-  ok: true,
-  result: {
-    planId: "pro",
-    status: "active",
-    renewalDate: "2026-08-01T00:00:00.000Z",
-    currentPeriodEnd: "2026-08-01T00:00:00.000Z",
-    cancelAtPeriodEnd: false,
-    cancelAt: null,
-    selectedCreditTier: "credits_50",
-    package: { key: "super", name: "Super", version: 2, customized: false },
-    entitlements: { managedEmail: true, phoneNumber: false },
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Mocks
-// ---------------------------------------------------------------------------
-
-mock.module("../../../../ipc/cli-client.js", () => ({
-  cliIpcCall: async (method: string, params: Record<string, unknown>) => {
-    mockCalls.push([method, params]);
-    return mockResponse;
-  },
-  exitFromIpcResult: (_r: unknown, _cmd: unknown) => {
-    throw new Error("exitFromIpcResult called");
-  },
-}));
-
-const { registerPlatformCommand } = await import("../index.js");
-
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride();
-  registerPlatformCommand(program);
-  return program;
-}
-
-function captureStdout(fn: () => Promise<void>): Promise<string[]> {
-  const chunks: string[] = [];
-  const origWrite = process.stdout.write.bind(process.stdout);
-  process.stdout.write = ((chunk: unknown) => {
-    chunks.push(typeof chunk === "string" ? chunk : String(chunk));
-    return true;
-  }) as typeof process.stdout.write;
-  return fn()
-    .then(() => chunks)
-    .finally(() => {
-      process.stdout.write = origWrite;
-    });
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
+const ipc = setupPlatformIpcMock();
 
 describe("assistant platform subscription", () => {
   beforeEach(() => {
-    mockCalls = [];
-    mockResponse = {
+    ipc.calls = [];
+    ipc.response = {
       ok: true,
       result: {
         planId: "pro",
@@ -80,22 +21,12 @@ describe("assistant platform subscription", () => {
         entitlements: { managedEmail: true, phoneNumber: false },
       },
     };
-    process.exitCode = 0;
   });
 
   test("calls platform_subscription and emits plan JSON with --json", async () => {
-    const out = await captureStdout(async () => {
-      const program = buildProgram();
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "subscription",
-        "--json",
-      ]);
-    });
+    const out = await runPlatform(["subscription", "--json"]);
 
-    expect(mockCalls[0][0]).toBe("platform_subscription");
+    expect(ipc.calls[0][0]).toBe("platform_subscription");
 
     const parsed = JSON.parse(out.join(""));
     expect(parsed.planId).toBe("pro");
@@ -105,17 +36,9 @@ describe("assistant platform subscription", () => {
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {
-    const out = await captureStdout(async () => {
-      const program = buildProgram();
-      await program.parseAsync([
-        "node",
-        "assistant",
-        "platform",
-        "subscription",
-      ]);
-    });
+    const out = await runPlatform(["subscription"]);
 
-    // Plain-text mode logs via log.info — verify writeOutput (JSON) was NOT called
+    // Plain-text mode logs via log.info; verify writeOutput (JSON) was NOT called
     expect(() => JSON.parse(out.join("").trim())).toThrow();
   });
 });

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

@@ -23,6 +23,7 @@ Examples:
   $ assistant platform credits --json
   $ assistant platform subscription --json
   $ assistant platform plans --json
+  $ assistant platform invoices list --json
   $ assistant platform connect
   $ assistant platform disconnect
   $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json`,
@@ -145,6 +146,97 @@ Examples:
   $ assistant platform plans
   $ assistant platform plans --json`,
     },
+    {
+      name: "invoices",
+      description: "Read the organization's Stripe invoice history",
+      helpText: `
+Invoices are read from the platform's billing invoices endpoint using this
+assistant's platform API key. Amounts are Stripe-scaled integers; see
+'assistant platform invoices list --help' for the scaling rules. 'created'
+is a Unix timestamp in seconds.
+
+The platform returns one page of invoices at a time (newest first). When
+the response's 'has_more' is true, pass the last invoice's id via
+--starting-after to fetch the next (older) page.
+
+Requires platform credentials (run 'assistant platform connect' first or
+ensure VELLUM_PLATFORM_URL is set and credentials are stored).
+
+Examples:
+  $ assistant platform invoices list --json
+  $ assistant platform invoices list --starting-after in_1AbCdEfGh
+  $ assistant platform invoices get in_1AbCdEfGh --json`,
+      subcommands: [
+        {
+          name: "list",
+          description:
+            "List one page of the organization's Stripe invoices, newest first",
+          options: [
+            {
+              flags: "--starting-after <invoice-id>",
+              description:
+                "Cursor: return invoices older than this invoice id (use the last id from the previous page)",
+            },
+          ],
+          helpText: `
+Fetches one page of the org's Stripe invoice history from the platform,
+newest first.
+
+Fields:
+  invoices            One page of invoices, each with the fields below
+  id                  Stripe invoice ID; pass it to 'assistant platform
+                      invoices get' or to --starting-after
+  number              Human-readable invoice number, or null
+  status              Stripe status (draft, open, paid, uncollectible,
+                      void), or null
+  currency            Lowercase ISO currency code (e.g. usd)
+  amount_due          Amount due as a Stripe-scaled integer: divide by
+                      100 for most currencies, by 1 for Stripe
+                      zero-decimal currencies (e.g. JPY, KRW), and by
+                      1000 for three-decimal ones (e.g. BHD); ISK, HUF,
+                      TWD, and UGX are two-decimal for charges and
+                      invoices (Stripe treats them as zero-decimal
+                      only for payouts)
+  amount_paid         Amount paid, same Stripe scaling as amount_due
+  amount_remaining    Amount still owed, same Stripe scaling as amount_due
+  created             Creation time as a Unix timestamp in seconds
+  hosted_invoice_url  Link to the hosted Stripe invoice page, or null
+  invoice_pdf         Link to the invoice PDF, or null
+  has_more            True when older invoices exist beyond this page;
+                      fetch them with --starting-after
+
+Requires platform credentials (run 'assistant platform connect' first or
+ensure VELLUM_PLATFORM_URL is set and credentials are stored).
+
+Examples:
+  $ assistant platform invoices list --json
+  $ assistant platform invoices list --starting-after in_1AbCdEfGh --json`,
+        },
+        {
+          name: "get",
+          description: "Show a single Stripe invoice by ID",
+          arguments: [
+            {
+              name: "<invoice-id>",
+              description:
+                "Stripe invoice ID (e.g. in_1AbCdEfGh); run 'assistant platform invoices list' to find it",
+            },
+          ],
+          helpText: `
+The platform has no per-invoice endpoint, so the assistant pages through
+the org's invoice list (newest first) until the ID matches. The lookup
+searches the most recent 2,500 invoices (25 pages) and errors if the ID
+is not found within that range.
+
+Requires platform credentials (run 'assistant platform connect' first or
+ensure VELLUM_PLATFORM_URL is set and credentials are stored).
+
+Examples:
+  $ assistant platform invoices get in_1AbCdEfGh
+  $ assistant platform invoices get in_1AbCdEfGh --json`,
+        },
+      ],
+    },
     {
       name: "disconnect",
       description:

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

@@ -14,6 +14,7 @@ import { shouldOutputJson, writeOutput } from "../../output.js";
 import { registerPlatformConnectCommand } from "./connect.js";
 import { registerPlatformDisconnectCommand } from "./disconnect.js";
 import { platformHelp } from "./index.help.js";
+import { registerPlatformInvoicesCommands } from "./invoices.js";
 
 interface PlatformStatusResult {
   isPlatform: boolean;
@@ -236,6 +237,12 @@ export function registerPlatformCommand(program: Command): void {
         },
       );
 
+      // -----------------------------------------------------------------------
+      // invoices
+      // -----------------------------------------------------------------------
+
+      registerPlatformInvoicesCommands(platform);
+
       // -----------------------------------------------------------------------
       // disconnect
       // -----------------------------------------------------------------------

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

@@ -0,0 +1,132 @@
+import { stripeScaleDigits } from "@vellumai/service-contracts/stripe-currency";
+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";
+
+interface PlatformInvoice {
+  id: string;
+  number: string | null;
+  status: string | null;
+  currency: string;
+  amount_due: number;
+  amount_paid: number;
+  amount_remaining: number;
+  created: number;
+  hosted_invoice_url: string | null;
+  invoice_pdf: string | null;
+}
+
+interface PlatformInvoicesListResult {
+  invoices: PlatformInvoice[];
+  has_more: boolean;
+}
+
+/**
+ * Render a Stripe minor-unit amount as major units, e.g. "USD 12.34". The
+ * display fraction digits are forced to match stripeScaleDigits so Intl's
+ * ISO metadata cannot apply a different scale (see the currency sets in
+ * @vellumai/service-contracts/stripe-currency). Unknown currency codes fall
+ * back to the raw minor-unit amount.
+ */
+function formatInvoiceAmount(
+  amountMinorUnits: number,
+  currency: string,
+): string {
+  const code = currency.toUpperCase();
+  const digits = stripeScaleDigits(code);
+  try {
+    const formatter = new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: code,
+      currencyDisplay: "code",
+      minimumFractionDigits: digits,
+      maximumFractionDigits: digits,
+    });
+    // Intl separates the code and number with U+00A0; use a plain space.
+    return formatter
+      .format(amountMinorUnits / 10 ** digits)
+      .replace(/\u00a0/g, " ");
+  } catch {
+    // Intl.NumberFormat throws a RangeError on invalid currency codes.
+    return `${amountMinorUnits} ${code} (minor units)`;
+  }
+}
+
+function logInvoice(invoice: PlatformInvoice, includePdf: boolean): void {
+  log.info(invoice.number ?? invoice.id);
+  log.info(`  Status:  ${invoice.status ?? "unknown"}`);
+  log.info(
+    `  Amount:  ${formatInvoiceAmount(invoice.amount_due, invoice.currency)}`,
+  );
+  log.info(
+    `  Created: ${new Date(invoice.created * 1000).toISOString().slice(0, 10)}`,
+  );
+  if (invoice.hosted_invoice_url) {
+    log.info(`  URL:     ${invoice.hosted_invoice_url}`);
+  }
+  if (includePdf && invoice.invoice_pdf) {
+    log.info(`  PDF:     ${invoice.invoice_pdf}`);
+  }
+}
+
+export function registerPlatformInvoicesCommands(platform: Command): void {
+  const invoices = subcommand(platform, "invoices");
+
+  subcommand(invoices, "list").action(
+    async (opts: { startingAfter?: string }, cmd: Command) => {
+      const r = await cliIpcCall<PlatformInvoicesListResult>(
+        "platform_invoices_list",
+        opts.startingAfter
+          ? { queryParams: { starting_after: opts.startingAfter } }
+          : {},
+      );
+      if (!r.ok) {
+        return exitFromIpcResult(r, cmd);
+      }
+
+      const result = r.result!;
+
+      if (shouldOutputJson(cmd)) {
+        writeOutput(cmd, result);
+      } else {
+        if (result.invoices.length === 0) {
+          log.info("No invoices found.");
+        } else {
+          for (const invoice of result.invoices) {
+            logInvoice(invoice, false);
+            log.info("");
+          }
+        }
+        const lastId = result.invoices.at(-1)?.id;
+        if (result.has_more && lastId) {
+          log.info(
+            `More invoices available. Run 'assistant platform invoices list --starting-after ${lastId}' for the next page.`,
+          );
+        }
+      }
+    },
+  );
+
+  subcommand(invoices, "get").action(
+    async (invoiceId: string, _opts: Record<string, unknown>, cmd: Command) => {
+      const r = await cliIpcCall<PlatformInvoice>(
+        "platform_invoices_by_id_get",
+        {
+          pathParams: { id: invoiceId },
+        },
+      );
+      if (!r.ok) {
+        return exitFromIpcResult(r, cmd);
+      }
+
+      if (shouldOutputJson(cmd)) {
+        writeOutput(cmd, r.result!);
+      } else {
+        logInvoice(r.result!, true);
+      }
+    },
+  );
+}

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

@@ -125,7 +125,7 @@ Grouping dimensions:
   inference_profile  Groups by inference profile; unset historical rows are
                      shown as Default / Unset
   provider           Groups by LLM provider (anthropic, openai, etc.)
-  model              Groups by model name (claude-sonnet-4-20250514, etc.)
+  model              Groups by model name (claude-sonnet-5, etc.)
   conversation       Groups by conversation ID
   actor              Legacy/internal subsystem grouping (main_agent, etc.)
 

package/src/cli/lib/list-installed-plugins.ts

@@ -14,6 +14,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import { parsePluginIcon } from "./plugin-artifact.js";
@@ -27,7 +28,7 @@ import { readValidatedPluginIcon } from "./plugin-icon-file.js";
  * dependencies in test environments).
  */
 const DEFAULT_PLUGINS_DIR = join(
-  dirname(new URL(import.meta.url).pathname),
+  dirname(fileURLToPath(import.meta.url)),
   "..",
   "..",
   "plugins",