@vellumai/cli 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/teleport.test.ts

@@ -64,7 +64,6 @@ mock.module("../lib/guardian-token.js", () => ({
 }));
 
 const readPlatformTokenMock = mock((): string | null => "platform-token");
-const fetchOrganizationIdMock = mock(async () => "org-123");
 const getPlatformUrlMock = mock(() => "https://platform.vellum.ai");
 const hatchAssistantMock = mock(async () => ({
   id: "platform-new-id",
@@ -142,7 +141,6 @@ const platformImportBundleFromGcsMock = mock(async () => ({
 
 mock.module("../lib/platform-client.js", () => ({
   readPlatformToken: readPlatformTokenMock,
-  fetchOrganizationId: fetchOrganizationIdMock,
   getPlatformUrl: getPlatformUrlMock,
   hatchAssistant: hatchAssistantMock,
   platformInitiateExport: platformInitiateExportMock,
@@ -240,8 +238,6 @@ beforeEach(() => {
 
   readPlatformTokenMock.mockReset();
   readPlatformTokenMock.mockReturnValue("platform-token");
-  fetchOrganizationIdMock.mockReset();
-  fetchOrganizationIdMock.mockResolvedValue("org-123");
   getPlatformUrlMock.mockReset();
   getPlatformUrlMock.mockReturnValue("https://platform.vellum.ai");
   hatchAssistantMock.mockReset();
@@ -757,10 +753,7 @@ describe("resolveOrHatchTarget", () => {
     findAssistantByNameMock.mockReturnValue(null);
 
     const result = await resolveOrHatchTarget("platform", "nonexistent");
-    expect(hatchAssistantMock).toHaveBeenCalledWith(
-      "platform-token",
-      "org-123",
-    );
+    expect(hatchAssistantMock).toHaveBeenCalledWith("platform-token");
     expect(saveAssistantEntryMock).toHaveBeenCalledWith(
       expect.objectContaining({
         assistantId: "platform-new-id",
@@ -1099,7 +1092,6 @@ describe("signed-URL upload flow", () => {
       expect(platformImportBundleFromGcsMock).toHaveBeenCalledWith(
         "bundle-key-123",
         "platform-token",
-        "org-123",
         "https://platform.vellum.ai",
       );
       // Inline import should NOT be called
@@ -1145,7 +1137,6 @@ describe("signed-URL upload flow", () => {
       expect(platformImportPreflightFromGcsMock).toHaveBeenCalledWith(
         "bundle-key-123",
         "platform-token",
-        "org-123",
         "https://platform.vellum.ai",
       );
       // Inline preflight should NOT be called
@@ -1284,7 +1275,7 @@ describe("signed-URL upload flow", () => {
 // ---------------------------------------------------------------------------
 
 describe("platform teleport org ID and reordered flow", () => {
-  test("hatchAssistant is called with the org ID from fetchOrganizationId", async () => {
+  test("hatchAssistant is called without orgId (authHeaders fetches it internally)", async () => {
     setArgv("--from", "my-local", "--platform");
 
     const localEntry = makeEntry("my-local", { cloud: "local" });
@@ -1294,21 +1285,14 @@ describe("platform teleport org ID and reordered flow", () => {
       return null;
     });
 
-    fetchOrganizationIdMock.mockResolvedValue("test-org-456");
-
     const originalFetch = globalThis.fetch;
     globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
 
-      // fetchOrganizationId should have been called
-      expect(fetchOrganizationIdMock).toHaveBeenCalled();
-      // hatchAssistant must be called with (token, orgId)
-      expect(hatchAssistantMock).toHaveBeenCalledWith(
-        "platform-token",
-        "test-org-456",
-      );
+      // hatchAssistant should be called with just the token (orgId is resolved internally by authHeaders)
+      expect(hatchAssistantMock).toHaveBeenCalledWith("platform-token");
     } finally {
       globalThis.fetch = originalFetch;
     }
@@ -1432,7 +1416,6 @@ describe("platform teleport org ID and reordered flow", () => {
         "pre-uploaded-key-789",
         "platform-token",
         expect.any(String),
-        expect.any(String),
       );
       // Inline import should NOT be used since signed upload succeeded
       expect(platformImportBundleMock).not.toHaveBeenCalled();

package/src/__tests__/version-compat.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  parseVersion,
+  compareVersions,
+  isVersionCompatible,
+} from "../lib/version-compat.js";
+
+describe("parseVersion", () => {
+  test("parses basic semver", () => {
+    expect(parseVersion("1.2.3")).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 3,
+      pre: null,
+    });
+  });
+
+  test("strips v prefix", () => {
+    expect(parseVersion("v1.2.3")).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 3,
+      pre: null,
+    });
+  });
+
+  test("strips V prefix", () => {
+    expect(parseVersion("V1.2.3")).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 3,
+      pre: null,
+    });
+  });
+
+  test("defaults missing patch to 0", () => {
+    expect(parseVersion("1.2")).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 0,
+      pre: null,
+    });
+  });
+
+  test("captures pre-release suffix", () => {
+    expect(parseVersion("0.6.0-staging.5")).toEqual({
+      major: 0,
+      minor: 6,
+      patch: 0,
+      pre: "staging.5",
+    });
+  });
+
+  test("captures pre-release with v prefix", () => {
+    expect(parseVersion("v0.6.0-staging.1")).toEqual({
+      major: 0,
+      minor: 6,
+      patch: 0,
+      pre: "staging.1",
+    });
+  });
+
+  test("captures hyphenated pre-release suffix", () => {
+    expect(parseVersion("1.0.0-pre-release-1")).toEqual({
+      major: 1,
+      minor: 0,
+      patch: 0,
+      pre: "pre-release-1",
+    });
+  });
+
+  test("returns null for single segment", () => {
+    expect(parseVersion("1")).toBeNull();
+  });
+
+  test("returns null for non-numeric segments", () => {
+    expect(parseVersion("abc.def")).toBeNull();
+  });
+
+  test("returns null for empty string", () => {
+    expect(parseVersion("")).toBeNull();
+  });
+});
+
+describe("compareVersions", () => {
+  // ── Basic numeric comparison ──────────────────────────────────────
+  test("equal versions return 0", () => {
+    expect(compareVersions("1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("higher major returns positive", () => {
+    expect(compareVersions("2.0.0", "1.0.0")).toBeGreaterThan(0);
+  });
+
+  test("lower major returns negative", () => {
+    expect(compareVersions("1.0.0", "2.0.0")).toBeLessThan(0);
+  });
+
+  test("higher minor returns positive", () => {
+    expect(compareVersions("1.3.0", "1.2.0")).toBeGreaterThan(0);
+  });
+
+  test("higher patch returns positive", () => {
+    expect(compareVersions("1.2.4", "1.2.3")).toBeGreaterThan(0);
+  });
+
+  // ── v prefix handling ─────────────────────────────────────────────
+  test("strips v prefix for comparison", () => {
+    expect(compareVersions("v1.2.3", "1.2.3")).toBe(0);
+  });
+
+  // ── Pre-release vs release ────────────────────────────────────────
+  test("pre-release sorts lower than release", () => {
+    expect(compareVersions("0.6.0-staging.1", "0.6.0")).toBeLessThan(0);
+  });
+
+  test("release sorts higher than pre-release", () => {
+    expect(compareVersions("0.6.0", "0.6.0-staging.1")).toBeGreaterThan(0);
+  });
+
+  // ── Pre-release numeric comparison ────────────────────────────────
+  test("staging.1 < staging.2", () => {
+    expect(compareVersions("0.6.0-staging.1", "0.6.0-staging.2")).toBeLessThan(
+      0,
+    );
+  });
+
+  test("staging.10 > staging.2 (numeric, not lexical)", () => {
+    expect(
+      compareVersions("0.6.0-staging.10", "0.6.0-staging.2"),
+    ).toBeGreaterThan(0);
+  });
+
+  // ── Pre-release lexical comparison ────────────────────────────────
+  test("alpha < beta (lexical)", () => {
+    expect(compareVersions("1.0.0-alpha", "1.0.0-beta")).toBeLessThan(0);
+  });
+
+  // ── Mixed numeric vs non-numeric per §11.4.4 ─────────────────────
+  test("numeric identifier sorts lower than non-numeric", () => {
+    expect(compareVersions("1.0.0-1", "1.0.0-alpha")).toBeLessThan(0);
+  });
+
+  // ── Fewer pre-release identifiers sorts earlier ───────────────────
+  test("fewer pre-release identifiers sorts earlier", () => {
+    expect(compareVersions("1.0.0-alpha", "1.0.0-alpha.1")).toBeLessThan(0);
+  });
+
+  // ── Returns null for unparseable input ────────────────────────────
+  test("returns null if first version is unparseable", () => {
+    expect(compareVersions("bad", "1.0.0")).toBeNull();
+  });
+
+  test("returns null if second version is unparseable", () => {
+    expect(compareVersions("1.0.0", "bad")).toBeNull();
+  });
+
+  // ── Different major.minor.patch trumps pre-release ────────────────
+  test("higher patch wins regardless of pre-release", () => {
+    expect(compareVersions("0.6.1", "0.6.0-staging.99")).toBeGreaterThan(0);
+  });
+
+  // ── Sort integration ──────────────────────────────────────────────
+  test("Array.sort produces correct semver order", () => {
+    const versions = [
+      "0.6.0",
+      "0.6.0-staging.2",
+      "0.5.9",
+      "0.6.0-staging.10",
+      "v0.6.0-staging.1",
+      "0.6.1",
+    ];
+    const sorted = [...versions].sort((a, b) => compareVersions(a, b) ?? 0);
+    expect(sorted).toEqual([
+      "0.5.9",
+      "v0.6.0-staging.1",
+      "0.6.0-staging.2",
+      "0.6.0-staging.10",
+      "0.6.0",
+      "0.6.1",
+    ]);
+  });
+});
+
+describe("isVersionCompatible", () => {
+  test("same major.minor are compatible", () => {
+    expect(isVersionCompatible("1.2.3", "1.2.5")).toBe(true);
+  });
+
+  test("different minor are incompatible", () => {
+    expect(isVersionCompatible("1.2.3", "1.3.0")).toBe(false);
+  });
+
+  test("different major are incompatible", () => {
+    expect(isVersionCompatible("1.2.3", "2.2.3")).toBe(false);
+  });
+
+  test("pre-release on same major.minor is compatible", () => {
+    expect(isVersionCompatible("0.6.0-staging.5", "0.6.0")).toBe(true);
+  });
+
+  test("returns false for unparseable input", () => {
+    expect(isVersionCompatible("bad", "1.0.0")).toBe(false);
+  });
+});

package/src/commands/backup.ts

@@ -6,7 +6,6 @@ import { getBackupsDir, formatSize } from "../lib/backup-ops.js";
 import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
 import {
   readPlatformToken,
-  fetchOrganizationId,
   platformInitiateExport,
   platformPollExportStatus,
   platformDownloadExport,
@@ -196,24 +195,11 @@ async function backupPlatform(
     process.exit(1);
   }
 
-  let orgId: string;
-  try {
-    orgId = await fetchOrganizationId(token, runtimeUrl);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-      process.exit(1);
-    }
-    throw err;
-  }
-
   // Step 2 — Initiate export job
   let jobId: string;
   try {
     const result = await platformInitiateExport(
       token,
-      orgId,
       "CLI backup",
       runtimeUrl,
     );
@@ -244,7 +230,7 @@ async function backupPlatform(
   while (Date.now() < deadline) {
     let status: { status: string; downloadUrl?: string; error?: string };
     try {
-      status = await platformPollExportStatus(jobId, token, orgId, runtimeUrl);
+      status = await platformPollExportStatus(jobId, token, runtimeUrl);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       // Let non-transient errors (e.g. 404 "job not found") propagate immediately

package/src/commands/events.ts

@@ -0,0 +1,146 @@
+/**
+ * `vellum events [assistant]`
+ *
+ * Subscribe to assistant events via the SSE endpoint and stream them
+ * to stdout.  By default, events are rendered as human-readable
+ * markdown.  Pass `--json` to emit one JSON object per event,
+ * separated by newlines.
+ */
+
+import { extractFlag } from "../lib/arg-utils.js";
+import { AssistantClient } from "../lib/assistant-client.js";
+
+function printUsage(): void {
+  console.log(`vellum events - Stream events from a running assistant
+
+USAGE:
+    vellum events [assistant] [options]
+
+ARGUMENTS:
+    [assistant]    Instance name (default: active assistant)
+
+OPTIONS:
+    --conversation-key <key>  Scope to a single conversation
+    --json                    Output raw JSON events (one per line)
+    -h, --help                Show this help message
+
+EXAMPLES:
+    vellum events
+    vellum events my-assistant
+    vellum events --json
+    vellum events --conversation-key my-thread
+`);
+}
+
+interface AssistantEvent {
+  id: string;
+  assistantId: string;
+  conversationId?: string;
+  emittedAt: string;
+  message: {
+    type: string;
+    text?: string;
+    thinking?: string;
+    toolName?: string;
+    input?: Record<string, unknown>;
+    result?: string;
+    isError?: boolean;
+    content?: string;
+    message?: string;
+    chunk?: string;
+    conversationId?: string;
+    [key: string]: unknown;
+  };
+}
+
+/** Render an event as human-readable markdown to stdout. */
+function renderMarkdown(event: AssistantEvent): void {
+  const msg = event.message;
+  switch (msg.type) {
+    case "assistant_text_delta":
+      process.stdout.write(msg.text ?? "");
+      break;
+    case "assistant_thinking_delta":
+      process.stdout.write(msg.thinking ?? "");
+      break;
+    case "tool_use_start":
+      console.log(`\n> **Tool call:** \`${msg.toolName}\``);
+      if (msg.input && Object.keys(msg.input).length > 0) {
+        console.log("```json");
+        console.log(JSON.stringify(msg.input, null, 2));
+        console.log("```");
+      }
+      break;
+    case "tool_input_delta":
+      process.stdout.write(msg.content ?? "");
+      break;
+    case "tool_result":
+      if (msg.isError) {
+        console.log(`\n> **Tool error** (\`${msg.toolName}\`): ${msg.result}`);
+      } else {
+        console.log(`\n> **Tool result** (\`${msg.toolName}\`): ${msg.result}`);
+      }
+      break;
+    case "tool_output_chunk":
+      process.stdout.write(msg.chunk ?? "");
+      break;
+    case "message_complete":
+      console.log("\n");
+      break;
+    case "error":
+      console.error(`\n**Error:** ${msg.message}`);
+      break;
+    case "user_message_echo":
+      console.log(`\n**You:** ${msg.text}`);
+      break;
+    default:
+      // Silently skip events that don't have a markdown representation
+      // (e.g. heartbeat comments, activity states, etc.)
+      break;
+  }
+}
+
+export async function events(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const jsonOutput = rawArgs.includes("--json");
+  let args = rawArgs.filter((a) => a !== "--json");
+
+  const [conversationKey, filteredArgs] = extractFlag(
+    args,
+    "--conversation-key",
+  );
+  args = filteredArgs;
+
+  const assistantId = args[0];
+
+  const client = new AssistantClient({ assistantId });
+
+  // Use an explicit AbortController so we can clean up on SIGINT
+  const controller = new AbortController();
+  process.on("SIGINT", () => {
+    controller.abort();
+    process.exit(0);
+  });
+
+  const query: Record<string, string> = {};
+  if (conversationKey) {
+    query.conversationKey = conversationKey;
+  }
+
+  for await (const event of client.stream<AssistantEvent>("/events", {
+    signal: controller.signal,
+    query,
+  })) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(event));
+    } else {
+      renderMarkdown(event);
+    }
+  }
+}

package/src/commands/hatch.ts

@@ -21,7 +21,6 @@ import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { hatchLocal } from "../lib/hatch-local";
 import {
-  fetchOrganizationId,
   getPlatformUrl,
   hatchAssistant,
   readPlatformToken,
@@ -594,19 +593,7 @@ async function hatchVellumPlatform(): Promise<void> {
   console.log("   Hatching assistant on Vellum platform...");
   console.log("");
 
-  let orgId: string;
-  try {
-    orgId = await fetchOrganizationId(token);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-      process.exit(1);
-    }
-    throw err;
-  }
-
-  const result = await hatchAssistant(token, orgId);
+  const result = await hatchAssistant(token);
 
   const platformUrl = getPlatformUrl();
 

package/src/commands/message.ts

@@ -0,0 +1,105 @@
+/**
+ * `vellum message <assistant> <message>`
+ *
+ * Send a message to a running assistant via its runtime HTTP API and
+ * print the result.  This is a fire-and-send command — it does NOT
+ * subscribe to SSE events (use `vellum events` for that).
+ */
+
+import { extractFlag } from "../lib/arg-utils.js";
+import { AssistantClient } from "../lib/assistant-client.js";
+
+function printUsage(): void {
+  console.log(`vellum message - Send a message to a running assistant
+
+USAGE:
+    vellum message [assistant] <message>
+
+ARGUMENTS:
+    [assistant]    Instance name (default: active assistant)
+    <message>      Message content to send
+
+OPTIONS:
+    --conversation-key <key>  Conversation key (default: stable key per channel/interface)
+    --json                    Output raw JSON response
+
+EXAMPLES:
+    vellum message "hello"
+    vellum message my-assistant "ping"
+    vellum message --conversation-key my-thread "hello"
+    vellum message --json "hello"
+`);
+}
+
+export async function message(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const jsonOutput = rawArgs.includes("--json");
+  let args = rawArgs.filter((a) => a !== "--json");
+
+  const [conversationKey, filteredArgs] = extractFlag(
+    args,
+    "--conversation-key",
+  );
+  args = filteredArgs;
+
+  let assistantId: string | undefined;
+  let messageContent: string | undefined;
+
+  if (args.length >= 2) {
+    // vellum message <assistant> <message>
+    assistantId = args[0];
+    messageContent = args[1];
+  } else if (args.length === 1) {
+    // vellum message <message>  (uses active/latest assistant)
+    messageContent = args[0];
+  }
+
+  if (!messageContent) {
+    console.error("Error: message content is required.");
+    console.error("");
+    printUsage();
+    process.exit(1);
+  }
+
+  const client = new AssistantClient({ assistantId });
+
+  const payload: Record<string, string> = {
+    content: messageContent,
+    sourceChannel: "vellum",
+    interface: "cli",
+  };
+  if (conversationKey) {
+    payload.conversationKey = conversationKey;
+  }
+
+  const response = await client.post("/messages/", payload);
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    console.error(
+      `Error: HTTP ${response.status}: ${body || response.statusText}`,
+    );
+    process.exit(1);
+  }
+
+  const result = (await response.json()) as {
+    accepted: boolean;
+    messageId: string;
+  };
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.accepted) {
+      console.log(`Message accepted (id: ${result.messageId})`);
+    } else {
+      console.log(`Message rejected (id: ${result.messageId})`);
+    }
+  }
+}

package/src/commands/restore.ts

@@ -8,7 +8,6 @@ import {
 } from "../lib/guardian-token.js";
 import {
   readPlatformToken,
-  fetchOrganizationId,
   rollbackPlatformAssistant,
   platformImportPreflight,
   platformImportBundle,
@@ -177,18 +176,6 @@ async function restorePlatform(
     process.exit(1);
   }
 
-  let orgId: string;
-  try {
-    orgId = await fetchOrganizationId(token, entry.runtimeUrl);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-      process.exit(1);
-    }
-    throw err;
-  }
-
   // Step 2 — Dry-run path
   if (opts.dryRun) {
     if (opts.version) {
@@ -205,7 +192,6 @@ async function restorePlatform(
       preflightResult = await platformImportPreflight(
         new Uint8Array(bundleData),
         token,
-        orgId,
         entry.runtimeUrl,
       );
     } catch (err) {
@@ -316,12 +302,7 @@ async function restorePlatform(
     );
 
     try {
-      await rollbackPlatformAssistant(
-        token,
-        orgId,
-        opts.version,
-        entry.runtimeUrl,
-      );
+      await rollbackPlatformAssistant(token, opts.version, entry.runtimeUrl);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes("401") || msg.includes("403")) {
@@ -345,7 +326,6 @@ async function restorePlatform(
     importResult = await platformImportBundle(
       new Uint8Array(bundleData),
       token,
-      orgId,
       entry.runtimeUrl,
     );
   } catch (err) {