@vellumai/cli 0.12.1 → 0.12.2-dev.202609162314.7778bc8

package/node_modules/@vellumai/environments/src/shell.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
@@ -38,6 +39,26 @@ describe("buildShellInvocation", () => {
   });
 });
 
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
 describe("path list handling", () => {
   test("uses the platform delimiter", () => {
     expect(pathListDelimiter("win32")).toBe(";");

package/node_modules/@vellumai/environments/src/shell.ts

@@ -5,6 +5,11 @@ export interface ShellInvocation {
   args: string[];
 }
 
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
 const WINDOWS_UTF8_PREAMBLE =
   "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
   "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
@@ -43,6 +48,25 @@ export function buildShellInvocation(
   return { command: "bash", args: ["-c", "--", command] };
 }
 
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
 export function pathListDelimiter(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string {

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/environments/src/shell.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
@@ -38,6 +39,26 @@ describe("buildShellInvocation", () => {
   });
 });
 
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
 describe("path list handling", () => {
   test("uses the platform delimiter", () => {
     expect(pathListDelimiter("win32")).toBe(";");

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/environments/src/shell.ts

@@ -5,6 +5,11 @@ export interface ShellInvocation {
   args: string[];
 }
 
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
 const WINDOWS_UTF8_PREAMBLE =
   "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
   "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
@@ -43,6 +48,25 @@ export function buildShellInvocation(
   return { command: "bash", args: ["-c", "--", command] };
 }
 
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
 export function pathListDelimiter(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string {

package/node_modules/@vellumai/local-mode/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./contract": "./src/lockfile-contract.ts"
+    "./contract": "./src/lockfile-contract.ts",
+    "./teleport-backup-policy": "./src/teleport-backup-policy.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/src/teleport-backup-policy.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  hasRecentBackup,
+  managedBackupIsReady,
+  readyManagedBackupCreatedAts,
+  RECENT_BACKUP_MAX_AGE_MS,
+} from "./teleport-backup-policy";
+
+const NOW = Date.parse("2026-09-15T12:00:00Z");
+
+function ago(ms: number): string {
+  return new Date(NOW - ms).toISOString();
+}
+
+describe("hasRecentBackup", () => {
+  test("true when a backup is within the max age", () => {
+    expect(hasRecentBackup([ago(5 * 60_000)], NOW)).toBe(true);
+    expect(hasRecentBackup([ago(RECENT_BACKUP_MAX_AGE_MS)], NOW)).toBe(true);
+  });
+
+  test("false when every backup is older than the max age", () => {
+    expect(hasRecentBackup([ago(RECENT_BACKUP_MAX_AGE_MS + 1)], NOW)).toBe(
+      false,
+    );
+    expect(hasRecentBackup([ago(2 * 24 * 60 * 60_000)], NOW)).toBe(false);
+  });
+
+  test("false with no backups", () => {
+    expect(hasRecentBackup([], NOW)).toBe(false);
+  });
+
+  test("ignores empty, missing, unparseable and future timestamps", () => {
+    expect(
+      hasRecentBackup(["", undefined, null, "garbage", ago(-60_000)], NOW),
+    ).toBe(false);
+    expect(hasRecentBackup(["", "garbage", ago(60_000)], NOW)).toBe(true);
+  });
+
+  test("finds a recent backup anywhere in the list", () => {
+    expect(
+      hasRecentBackup(
+        [ago(3 * RECENT_BACKUP_MAX_AGE_MS), ago(30 * 60_000)],
+        NOW,
+      ),
+    ).toBe(true);
+  });
+
+  test("honors a custom max age", () => {
+    expect(hasRecentBackup([ago(10 * 60_000)], NOW, 5 * 60_000)).toBe(false);
+    expect(hasRecentBackup([ago(10 * 60_000)], NOW, 15 * 60_000)).toBe(true);
+  });
+});
+
+describe("readyManagedBackupCreatedAts", () => {
+  test("keeps ready snapshots and drops pending ones", () => {
+    expect(
+      readyManagedBackupCreatedAts([
+        {
+          snapshot_name: "a",
+          created_at: "2026-09-15T11:00:00Z",
+          ready_to_use: true,
+        },
+        {
+          snapshot_name: "b",
+          created_at: "2026-09-15T11:30:00Z",
+          ready_to_use: false,
+        },
+        { snapshot_name: "c", created_at: "2026-09-15T10:00:00Z" },
+      ]),
+    ).toEqual(["2026-09-15T11:00:00Z", "2026-09-15T10:00:00Z"]);
+  });
+});
+
+describe("managedBackupIsReady", () => {
+  const backups = [
+    { snapshot_name: "ready", ready_to_use: true },
+    { snapshot_name: "pending", ready_to_use: false },
+    { snapshot_name: "unknown" },
+  ];
+
+  test("true only for a snapshot explicitly marked ready", () => {
+    expect(managedBackupIsReady(backups, "ready")).toBe(true);
+    expect(managedBackupIsReady(backups, "pending")).toBe(false);
+    expect(managedBackupIsReady(backups, "unknown")).toBe(false);
+    expect(managedBackupIsReady(backups, "missing")).toBe(false);
+  });
+});

package/node_modules/@vellumai/local-mode/src/teleport-backup-policy.ts

@@ -0,0 +1,74 @@
+/**
+ * Pre-teleport backup policy shared by every teleport surface (CLI and web).
+ *
+ * A teleport ends with the source assistant being retired, so each surface
+ * snapshots the source before any data leaves it. This module holds the
+ * decisions those surfaces must agree on: how fresh an existing backup has to
+ * be to stand in for a new one, and how a platform (PVC) snapshot is judged
+ * restorable. Transport lives with each client; nothing here touches the
+ * network or the filesystem.
+ */
+
+/** A backup at most this old satisfies the pre-teleport backup requirement. */
+export const RECENT_BACKUP_MAX_AGE_MS = 60 * 60 * 1000;
+
+/** How long to wait for a freshly cut platform snapshot to become restorable. */
+export const MANAGED_BACKUP_READY_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** How often to re-list platform snapshots while waiting for readiness. */
+export const MANAGED_BACKUP_READY_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Whether any of `createdAts` (ISO-8601 timestamps; empty, missing and
+ * unparseable values are ignored) falls within `maxAgeMs` of `now`.
+ */
+export function hasRecentBackup(
+  createdAts: Iterable<string | null | undefined>,
+  now: number = Date.now(),
+  maxAgeMs: number = RECENT_BACKUP_MAX_AGE_MS,
+): boolean {
+  for (const createdAt of createdAts) {
+    if (!createdAt) {
+      continue;
+    }
+    const createdMs = Date.parse(createdAt);
+    if (Number.isNaN(createdMs)) {
+      continue;
+    }
+    const age = now - createdMs;
+    if (age >= 0 && age <= maxAgeMs) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** The fields of a platform backup listing entry the policy reads. */
+export interface ManagedBackupEntry {
+  snapshot_name?: string;
+  created_at?: string;
+  ready_to_use?: boolean;
+}
+
+/**
+ * `created_at` of every restorable platform snapshot. A snapshot still being
+ * cut (`ready_to_use: false`) never counts as a usable restore point.
+ */
+export function readyManagedBackupCreatedAts(
+  backups: readonly ManagedBackupEntry[],
+): Array<string | undefined> {
+  return backups
+    .filter((backup) => backup.ready_to_use !== false)
+    .map((backup) => backup.created_at);
+}
+
+/** Whether the listing shows `snapshotName` as restorable. */
+export function managedBackupIsReady(
+  backups: readonly ManagedBackupEntry[],
+  snapshotName: string,
+): boolean {
+  return backups.some(
+    (backup) =>
+      backup.snapshot_name === snapshotName && backup.ready_to_use === true,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.12.1",
+  "version": "0.12.2-dev.202609162314.7778bc8",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/backup-ops-matching.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+
+import { assistantBackupFilenamePattern } from "../lib/backup-ops.js";
+
+const STAMP = "2026-09-15T14-27-28-123Z";
+
+describe("assistantBackupFilenamePattern", () => {
+  test("matches this CLI's backups for exactly the given assistant", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`alpha-pre-teleport-${STAMP}.vbundle`)).toBe(true);
+  });
+
+  test("does not match an assistant whose id extends this one", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-prod-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-prod-pre-teleport-${STAMP}.vbundle`)).toBe(
+      false,
+    );
+  });
+
+  test("does not match a shorter id's backups from a longer id", () => {
+    const pattern = assistantBackupFilenamePattern("alpha-prod");
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+  });
+
+  test("ignores user-named vellum backup files and other kinds", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-manual-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle.enc`)).toBe(false);
+  });
+
+  test("restricts to the requested kinds", () => {
+    const pattern = assistantBackupFilenamePattern("alpha", ["pre-teleport"]);
+    expect(pattern.test(`alpha-pre-teleport-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+    expect(
+      pattern.test(`alpha-pre-teleport-prod-pre-teleport-${STAMP}.vbundle`),
+    ).toBe(false);
+  });
+
+  test("escapes regex metacharacters in ids", () => {
+    const pattern = assistantBackupFilenamePattern("a.b");
+    expect(pattern.test(`a.b-pre-upgrade-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`axb-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+  });
+});

package/src/__tests__/teleport-backup.test.ts

@@ -0,0 +1,208 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+
+import * as platformClient from "../lib/platform-client.js";
+import {
+  createPlatformBackup,
+  listPlatformBackups,
+} from "../lib/teleport-backup.js";
+
+const authHeadersSpy = spyOn(platformClient, "authHeaders").mockResolvedValue({
+  "Content-Type": "application/json",
+  "X-Session-Token": "platform-token",
+  "Vellum-Organization-Id": "org-1",
+});
+const invalidateOrgIdCacheSpy = spyOn(
+  platformClient,
+  "invalidateOrgIdCache",
+).mockImplementation(() => {});
+
+afterAll(() => {
+  authHeadersSpy.mockRestore();
+  invalidateOrgIdCacheSpy.mockRestore();
+});
+
+let originalFetch: typeof globalThis.fetch;
+let fetchCalls: Array<{ url: string; method: string }>;
+let responses: Array<() => Response>;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+  fetchCalls = [];
+  responses = [];
+  globalThis.fetch = mock(
+    async (url: string | URL | Request, init?: RequestInit) => {
+      fetchCalls.push({
+        url: typeof url === "string" ? url : url.toString(),
+        method: init?.method ?? "GET",
+      });
+      const next = responses.shift();
+      if (!next) {
+        throw new Error("unexpected fetch");
+      }
+      return next();
+    },
+  ) as unknown as typeof globalThis.fetch;
+  authHeadersSpy.mockClear();
+  invalidateOrgIdCacheSpy.mockClear();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+const ENTRY = {
+  runtimeUrl: "https://platform.vellum.ai",
+  assistantId: "11111111-2222-3333-4444-555555555555",
+};
+const BACKUPS_URL = `https://platform.vellum.ai/v1/assistants/${ENTRY.assistantId}/backups/`;
+const FAST_POLL = { pollIntervalMs: 1, timeoutMs: 200 };
+
+function json(body: unknown, status = 200): () => Response {
+  return () => Response.json(body, { status });
+}
+
+describe("listPlatformBackups", () => {
+  test("returns created_at of ready snapshots only", async () => {
+    responses.push(
+      json({
+        backups: [
+          { created_at: "2026-09-15T11:00:00Z", ready_to_use: true },
+          { created_at: "2026-09-15T11:30:00Z", ready_to_use: false },
+          { created_at: "2026-09-15T10:00:00Z" },
+        ],
+      }),
+    );
+
+    const result = await listPlatformBackups(ENTRY, "platform-token");
+
+    expect(result).toEqual(["2026-09-15T11:00:00Z", "2026-09-15T10:00:00Z"]);
+    expect(fetchCalls[0]).toEqual({ url: BACKUPS_URL, method: "GET" });
+    expect(authHeadersSpy).toHaveBeenCalledWith(
+      "platform-token",
+      "https://platform.vellum.ai",
+    );
+  });
+
+  test("refreshes the org id cache and retries once on 401", async () => {
+    responses.push(() => new Response("unauthorized", { status: 401 }));
+    responses.push(json({ backups: [] }));
+
+    const result = await listPlatformBackups(ENTRY, "platform-token");
+
+    expect(result).toEqual([]);
+    expect(fetchCalls).toHaveLength(2);
+    expect(invalidateOrgIdCacheSpy).toHaveBeenCalledWith(
+      "platform-token",
+      "https://platform.vellum.ai",
+    );
+  });
+
+  test("throws on a persistent error", async () => {
+    responses.push(() => new Response("Bad gateway", { status: 502 }));
+
+    await expect(listPlatformBackups(ENTRY, "platform-token")).rejects.toThrow(
+      "Platform backup list failed (502): Bad gateway",
+    );
+  });
+});
+
+describe("createPlatformBackup", () => {
+  test("returns immediately when the POST reports the snapshot ready", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: true }, 201));
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls).toEqual([{ url: BACKUPS_URL, method: "POST" }]);
+  });
+
+  test("polls the listing until the new snapshot is ready", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: false }, 201));
+    responses.push(
+      json({ backups: [{ snapshot_name: "snap-1", ready_to_use: false }] }),
+    );
+    responses.push(
+      json({
+        backups: [
+          { snapshot_name: "older", ready_to_use: true },
+          { snapshot_name: "snap-1", ready_to_use: true },
+        ],
+      }),
+    );
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls.map((call) => call.method)).toEqual([
+      "POST",
+      "GET",
+      "GET",
+    ]);
+  });
+
+  test("another ready snapshot does not satisfy the wait", async () => {
+    responses.push(json({ snapshot_name: "snap-1" }, 201));
+    responses.push(
+      json({ backups: [{ snapshot_name: "older", ready_to_use: true }] }),
+    );
+    responses.push(
+      json({ backups: [{ snapshot_name: "snap-1", ready_to_use: true }] }),
+    );
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls).toHaveLength(3);
+  });
+
+  test("throws when the snapshot is not ready before the timeout", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: false }, 201));
+    const pending = json({
+      backups: [{ snapshot_name: "snap-1", ready_to_use: false }],
+    });
+    for (let i = 0; i < 1000; i++) {
+      responses.push(pending);
+    }
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", {
+        pollIntervalMs: 1,
+        timeoutMs: 30,
+      }),
+    ).rejects.toThrow("Platform backup snap-1 was not ready after 0s");
+  });
+
+  test("throws when the POST fails", async () => {
+    responses.push(
+      () => new Response('{"detail":"Bad gateway"}', { status: 502 }),
+    );
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("Platform backup create failed (502)");
+    expect(fetchCalls).toHaveLength(1);
+  });
+
+  test("throws when the POST returns no snapshot name", async () => {
+    responses.push(json({}, 201));
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("no snapshot name");
+  });
+
+  test("a listing failure while waiting is fatal", async () => {
+    responses.push(json({ snapshot_name: "snap-1" }, 201));
+    responses.push(() => new Response("Bad gateway", { status: 502 }));
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("Platform backup list failed (502)");
+  });
+});