@vellumai/cli 0.12.3-dev.202609221316.175c45b → 0.12.3-dev.202609221714.83d90c3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.12.3-dev.202609221316.175c45b",
+  "version": "0.12.3-dev.202609221714.83d90c3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/debug-bundle.test.ts

@@ -0,0 +1,257 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Lockfile isolation (mirrors backup.test.ts)
+const testDir = mkdtempSync(join(tmpdir(), "cli-debug-bundle-test-"));
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+import * as assistantConfig from "../lib/assistant-config.js";
+import * as guardianToken from "../lib/guardian-token.js";
+import * as localRuntimeClient from "../lib/local-runtime-client.js";
+import * as platformClient from "../lib/platform-client.js";
+
+const resolveTargetMock = spyOn(
+  assistantConfig,
+  "resolveTargetAssistant",
+).mockImplementation(() => {
+  throw new Error("process.exit:1");
+});
+const readPlatformTokenMock = spyOn(
+  platformClient,
+  "readPlatformToken",
+).mockReturnValue("platform-token");
+const exportMock = spyOn(
+  localRuntimeClient,
+  "localRuntimeExportToGcs",
+).mockResolvedValue({ jobId: "job-1" });
+const identityMock = spyOn(
+  localRuntimeClient,
+  "localRuntimeIdentity",
+).mockResolvedValue({ version: "0.12.3" });
+const pollMock = spyOn(
+  localRuntimeClient,
+  "localRuntimePollJobStatus",
+).mockResolvedValue({
+  jobId: "job-1",
+  type: "export",
+  status: "complete",
+} as unknown as Awaited<
+  ReturnType<typeof localRuntimeClient.localRuntimePollJobStatus>
+>);
+const loadGuardianTokenSpy = spyOn(
+  guardianToken,
+  "loadGuardianToken",
+).mockReturnValue({
+  accessToken: "local-token",
+  accessTokenExpiresAt: new Date(Date.now() + 10 * 60_000).toISOString(),
+} as unknown as ReturnType<typeof guardianToken.loadGuardianToken>);
+const leaseGuardianTokenSpy = spyOn(
+  guardianToken,
+  "leaseGuardianToken",
+).mockResolvedValue({
+  accessToken: "leased-token",
+  accessTokenExpiresAt: new Date(Date.now() + 10 * 60_000).toISOString(),
+} as unknown as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>);
+
+const { debugBundle } = await import("../commands/debug-bundle.js");
+
+const LOCAL_ENTRY = {
+  name: "mine",
+  assistantId: "local-asst-1",
+  runtimeUrl: "http://127.0.0.1:7821",
+  cloud: "local",
+  species: "local",
+  hatchedAt: new Date().toISOString(),
+  platformAssistantId: "11111111-2222-3333-4444-555555555555",
+  platformBaseUrl: "https://platform.vellum.ai",
+  platformOrganizationId: "org-1",
+} as unknown as assistantConfig.AssistantEntry;
+
+let originalFetch: typeof globalThis.fetch;
+let originalExit: typeof process.exit;
+let fetchCalls: { url: string; init?: RequestInit }[] = [];
+let uploadUrlStatus = 201;
+
+beforeEach(() => {
+  process.argv = ["bun", "vellum", "debug-bundle"];
+  originalFetch = globalThis.fetch;
+  originalExit = process.exit;
+  process.exit = mock((code?: number) => {
+    throw new Error(`process.exit:${code}`);
+  }) as unknown as typeof process.exit;
+  fetchCalls = [];
+  uploadUrlStatus = 201;
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      fetchCalls.push({ url: String(input), init });
+      return new Response(
+        JSON.stringify({ url: "https://storage.googleapis.com/b/signed" }),
+        {
+          status: uploadUrlStatus,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    },
+  ) as unknown as typeof globalThis.fetch;
+  resolveTargetMock.mockReset();
+  resolveTargetMock.mockReturnValue(LOCAL_ENTRY);
+  identityMock.mockReset();
+  identityMock.mockResolvedValue({ version: "0.12.3" });
+  leaseGuardianTokenSpy.mockClear();
+  readPlatformTokenMock.mockReset();
+  readPlatformTokenMock.mockReturnValue("platform-token");
+  exportMock.mockClear();
+  pollMock.mockClear();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  process.exit = originalExit;
+});
+
+afterAll(() => {
+  resolveTargetMock.mockRestore();
+  identityMock.mockRestore();
+  leaseGuardianTokenSpy.mockRestore();
+  readPlatformTokenMock.mockRestore();
+  exportMock.mockRestore();
+  pollMock.mockRestore();
+  loadGuardianTokenSpy.mockRestore();
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("vellum debug-bundle", () => {
+  test("mints the URL on the platform, exports with the debug profile, and waits", async () => {
+    await debugBundle();
+
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toBe(
+      "https://platform.vellum.ai/v1/assistants/11111111-2222-3333-4444-555555555555/debug-bundle-upload-url/",
+    );
+    expect(fetchCalls[0].init?.method).toBe("POST");
+    expect(
+      (fetchCalls[0].init?.headers as Record<string, string>)[
+        "Vellum-Organization-Id"
+      ],
+    ).toBe("org-1");
+
+    expect(exportMock).toHaveBeenCalledTimes(1);
+    const [entry, token, params] = exportMock.mock.calls[0];
+    expect(entry).toBe(LOCAL_ENTRY);
+    expect(token).toBe("local-token");
+    expect(params).toEqual({
+      uploadUrl: "https://storage.googleapis.com/b/signed",
+      description: "debug bundle for Vellum staff",
+      profile: "debug",
+    });
+    expect(pollMock).toHaveBeenCalled();
+    // The daemon was checked for the debug profile before the platform call.
+    expect(identityMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("passes an unquoted multi-word display name through to the shared resolver", async () => {
+    process.argv = ["bun", "vellum", "debug-bundle", "Support", "Bot"];
+    await debugBundle();
+    expect(resolveTargetMock).toHaveBeenCalledWith("Support Bot");
+  });
+
+  test("refuses a daemon older than the debug profile before any URL is minted", async () => {
+    // Such a daemon strips `profile` and would upload the owner's
+    // credentials to the staff bucket.
+    identityMock.mockResolvedValue({ version: "0.12.2" });
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("0.12.3");
+    expect(fetchCalls).toHaveLength(0);
+    expect(exportMock).not.toHaveBeenCalled();
+  });
+
+  test("re-leases the guardian token when the daemon answers 401 mid-poll", async () => {
+    pollMock.mockReset();
+    let polls = 0;
+    pollMock.mockImplementation(async (_entry, token) => {
+      polls += 1;
+      if (polls === 1) {
+        throw new Error("Local job status check failed: 401 Unauthorized");
+      }
+      expect(token).toBe("leased-token");
+      return {
+        jobId: "job-1",
+        type: "export",
+        status: "complete",
+      } as unknown as Awaited<
+        ReturnType<typeof localRuntimeClient.localRuntimePollJobStatus>
+      >;
+    });
+
+    await debugBundle();
+
+    expect(leaseGuardianTokenSpy).toHaveBeenCalledTimes(1);
+    expect(polls).toBe(2);
+  });
+
+  test("explains what to turn on when the platform refuses", async () => {
+    uploadUrlStatus = 403;
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("Allow Staff Access");
+    expect(exportMock).not.toHaveBeenCalled();
+  });
+
+  test("refuses a Vellum-hosted assistant, which needs no bundle", async () => {
+    resolveTargetMock.mockReturnValue({
+      ...LOCAL_ENTRY,
+      cloud: "vellum",
+    } as unknown as assistantConfig.AssistantEntry);
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  test("asks for a login when the assistant is not registered", async () => {
+    resolveTargetMock.mockReturnValue({
+      ...LOCAL_ENTRY,
+      platformAssistantId: undefined,
+    } as unknown as assistantConfig.AssistantEntry);
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((msg) => {
+      errors.push(String(msg));
+    });
+    try {
+      await expect(debugBundle()).rejects.toThrow("process.exit:1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+    expect(errors.join("\n")).toContain("vellum login");
+    expect(fetchCalls).toHaveLength(0);
+  });
+});

package/src/commands/debug-bundle.ts

@@ -0,0 +1,221 @@
+/**
+ * `vellum debug-bundle [name]`
+ *
+ * Send Vellum staff a debug bundle of a self-hosted assistant: the
+ * workspace, its logs, and the gateway's own database, with no credentials.
+ * Staff open it on a throwaway debug clone. The platform only hands out the
+ * upload URL while "Allow Staff Access" is on, and the bundle is deleted
+ * after seven days.
+ *
+ * Steps: the daemon is checked for the debug profile, the platform mints
+ * the upload URL, the daemon exports with the debug profile, and this
+ * command waits for the job so the result is real.
+ */
+import {
+  formatAssistantReference,
+  resolveTargetAssistant,
+} from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
+import { pollJobUntilDone } from "../lib/job-polling.js";
+import {
+  MigrationInProgressError,
+  localRuntimeExportToGcs,
+  localRuntimeIdentity,
+  localRuntimePollJobStatus,
+} from "../lib/local-runtime-client.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import {
+  authHeaders,
+  authHeadersForKnownOrganization,
+  getPlatformUrl,
+  readPlatformToken,
+} from "../lib/platform-client.js";
+import { compareVersions } from "../lib/version-compat.js";
+
+// Matches the daemon's own upload deadline (EXPORT_TO_GCS_PUT_TIMEOUT_MS in
+// assistant/src/runtime/routes/migration-routes.ts), so a slow but healthy
+// export is never reported as failed while it is still uploading.
+const EXPORT_TIMEOUT_MS = 60 * 60 * 1000;
+// The daemon release that added `profile: "debug"`. An older daemon strips
+// the field and exports a normal teleport bundle, which carries the owner's
+// credentials. That must never reach the staff bucket.
+export const DEBUG_PROFILE_MIN_VERSION = "0.12.3";
+// Renew a cached guardian token that is about to lapse instead of starting
+// a long export on it.
+const TOKEN_EXPIRY_MARGIN_MS = 60 * 1000;
+
+function printHelp(): void {
+  console.log(`Usage: vellum debug-bundle [name]
+
+Send Vellum staff a debug bundle of a self-hosted assistant so they can
+inspect a copy of it. The bundle holds the assistant's workspace, its
+logs, and the gateway's own database. It never holds credentials.
+
+Arguments:
+  name    Assistant ID or unique display name. Defaults to the active
+          assistant (see 'vellum use'). Multi-word names need no quotes.
+
+Requirements:
+  - 'Allow Staff Access' is on for the assistant (Settings > Privacy).
+  - You are logged in ('vellum login'), which also registers the
+    assistant with the platform.
+  - The assistant runs version ${DEBUG_PROFILE_MIN_VERSION} or newer.
+  - The assistant is self-hosted. Vellum-hosted assistants need no bundle;
+    staff clone them directly.
+
+Side effects:
+  - Uploads the bundle to Vellum's debug-bundle storage, where it is
+    deleted after 7 days. Nothing on this machine changes.
+  - Records a 'debug bundle exported' entry in your account's audit history.
+  - Waits for the upload to finish (up to 60 minutes for a large workspace).
+
+Examples:
+  vellum debug-bundle
+  vellum debug-bundle my-assistant
+  vellum debug-bundle Support Bot
+`);
+}
+
+export async function debugBundle(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const entry = resolveTargetAssistant(parseAssistantTargetArg(args));
+  const reference = formatAssistantReference(entry);
+  if (entry.cloud === "vellum") {
+    console.error(
+      `${reference} is hosted by Vellum, so staff can clone it directly. No bundle is needed.`,
+    );
+    process.exit(1);
+  }
+
+  const platformToken = readPlatformToken();
+  if (!platformToken) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+  const platformAssistantId = entry.platformAssistantId?.trim();
+  if (!platformAssistantId) {
+    console.error(
+      `${reference} is not registered with the platform yet. Run 'vellum login' and retry.`,
+    );
+    process.exit(1);
+  }
+  const platformUrl = entry.platformBaseUrl?.trim() || getPlatformUrl();
+  const organizationId = entry.platformOrganizationId?.trim();
+
+  // Step 1: a guardian token for the daemon, and a check that the daemon
+  // knows the debug profile. This comes before the platform call so a
+  // daemon that would export credentials is refused before any URL exists.
+  let accessToken = await daemonAccessToken(entry, reference, false);
+  const { version } = await localRuntimeIdentity(entry, accessToken);
+  const comparison = compareVersions(version, DEBUG_PROFILE_MIN_VERSION);
+  if (comparison === null || comparison < 0) {
+    console.error(
+      `${reference} runs version ${version || "unknown"}, which cannot build a debug bundle. Update it to ${DEBUG_PROFILE_MIN_VERSION} or newer ('vellum upgrade') and retry.`,
+    );
+    process.exit(1);
+  }
+
+  // Step 2: the platform mints the upload URL, and refuses unless the
+  // owner's staff access grant is active.
+  const headers = organizationId
+    ? authHeadersForKnownOrganization(platformToken, organizationId)
+    : await authHeaders(platformToken, platformUrl);
+  const urlResponse = await loopbackSafeFetch(
+    `${platformUrl}/v1/assistants/${encodeURIComponent(platformAssistantId)}/debug-bundle-upload-url/`,
+    { method: "POST", headers },
+  );
+  if (urlResponse.status === 403) {
+    console.error(
+      "Staff access is off for this assistant. Turn on 'Allow Staff Access' in Settings > Privacy, then retry.",
+    );
+    process.exit(1);
+  }
+  if (!urlResponse.ok) {
+    const detail = await urlResponse.text().catch(() => "");
+    console.error(
+      `Error: Could not get an upload URL (${urlResponse.status}): ${detail || urlResponse.statusText}`,
+    );
+    process.exit(1);
+  }
+  const { url: uploadUrl } = (await urlResponse.json()) as { url: string };
+
+  // Step 3: the daemon builds and uploads the bundle.
+  let jobId: string;
+  try {
+    ({ jobId } = await localRuntimeExportToGcs(entry, accessToken, {
+      uploadUrl,
+      description: "debug bundle for Vellum staff",
+      profile: "debug",
+    }));
+  } catch (err) {
+    if (err instanceof MigrationInProgressError) {
+      console.error(
+        `Error: Another export is already in progress (job ${err.existingJobId}). Wait for it to finish, then retry.`,
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+  console.log(`Export started (job ${jobId})...`);
+
+  // Step 4: wait for the upload so the owner sees a real result. A large
+  // export can outlive the guardian token, so a 401 mid-poll re-leases one.
+  const terminal = await pollJobUntilDone({
+    label: "debug bundle export",
+    poll: () => localRuntimePollJobStatus(entry, accessToken, jobId),
+    timeoutMs: EXPORT_TIMEOUT_MS,
+    refreshOn401: async () => {
+      accessToken = await daemonAccessToken(entry, reference, true);
+    },
+  });
+  if (terminal.status === "failed") {
+    console.error(`Error: Export failed: ${terminal.error}`);
+    process.exit(1);
+  }
+  console.log(
+    "Debug bundle sent to Vellum. Staff can open it for the next 7 days.",
+  );
+}
+
+async function daemonAccessToken(
+  entry: {
+    assistantId: string;
+    runtimeUrl: string;
+    guardianBootstrapSecret?: string;
+  },
+  reference: string,
+  forceRefresh: boolean,
+): Promise<string> {
+  if (!forceRefresh) {
+    const cached = loadGuardianToken(entry.assistantId);
+    if (
+      cached &&
+      new Date(cached.accessTokenExpiresAt).getTime() - Date.now() >
+        TOKEN_EXPIRY_MARGIN_MS
+    ) {
+      return cached.accessToken;
+    }
+  }
+  try {
+    return (
+      await leaseGuardianToken(
+        entry.runtimeUrl,
+        entry.assistantId,
+        entry.guardianBootstrapSecret,
+      )
+    ).accessToken;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      console.error(`Error: Could not connect to ${reference}. Is it running?`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}

package/src/index.ts

@@ -31,6 +31,7 @@ import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
+import { debugBundle } from "./commands/debug-bundle";
 import { teleport } from "./commands/teleport";
 import { terminal } from "./commands/terminal";
 import { tunnel } from "./commands/tunnel";
@@ -45,6 +46,7 @@ import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
+  "debug-bundle": debugBundle,
   backup,
   clean,
   client,
@@ -125,6 +127,9 @@ function printHelp(): void {
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");
+  console.log(
+    "  debug-bundle  Send Vellum staff a debug bundle of a self-hosted assistant",
+  );
   console.log("  teleport Transfer assistant data between environments");
   console.log("  terminal Open a terminal into a managed assistant container");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");

package/src/lib/local-runtime-client.ts

@@ -116,12 +116,23 @@ async function throwIfInProgress(
 export async function localRuntimeExportToGcs(
   entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
   token: string,
-  params: { uploadUrl: string; description?: string },
+  params: {
+    uploadUrl: string;
+    description?: string;
+    /**
+     * `"debug"` builds a bundle for Vellum staff: no credentials, plus the
+     * gateway's database and logs. Omitted means a normal teleport bundle.
+     */
+    profile?: "migration" | "debug";
+  },
 ): Promise<{ jobId: string }> {
   const body: Record<string, unknown> = { upload_url: params.uploadUrl };
   if (params.description !== undefined) {
     body.description = params.description;
   }
+  if (params.profile !== undefined) {
+    body.profile = params.profile;
+  }
 
   const response = await loopbackSafeFetch(
     resolveRuntimeMigrationUrl(entry, "export-to-gcs"),