@vellumai/cli 0.8.6 → 0.8.7-dev.202606052135.3e62c5a

package/node_modules/@vellumai/local-mode/src/retire.ts

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+const RETIRE_TIMEOUT_MS = 60_000;
+
+export type RetireResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+export function runRetire(
+  invocation: CliInvocation,
+  assistantId: string,
+): Promise<RetireResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "retire", assistantId, "--yes"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: RetireResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, status: 500, error: "Retire timed out after 60 seconds" });
+    }, RETIRE_TIMEOUT_MS);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        finish({ ok: true });
+      } else {
+        finish({ ok: false, status: 500, error: stderr || stdout });
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+    });
+  });
+}

package/node_modules/@vellumai/local-mode/src/util.ts

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const CLI_PACKAGE_NAME = "@vellumai/cli";
+
+/**
+ * How to invoke the Vellum CLI as a child process: a base command plus the
+ * leading arguments that precede the subcommand. Each host resolves its own
+ * invocation — the dev hosts run the CLI from source via `bun run <entry>`,
+ * a packaged host would point at its bundled runtime — and the shared
+ * lifecycle ops (`runHatch`, `runRetire`, guardian-token refresh) append
+ * their subcommand args to `baseArgs`.
+ */
+export interface CliInvocation {
+  command: string;
+  baseArgs: string[];
+}
+
+const SENSITIVE_FIELDS = [
+  "signingKey",
+  "bearerToken",
+  "guardianBootstrapSecret",
+] as const;
+
+export function stripSensitiveFields(data: Record<string, unknown>): void {
+  const assistants = data.assistants;
+  if (!Array.isArray(assistants)) return;
+  for (const assistant of assistants) {
+    if (assistant && typeof assistant === "object") {
+      const entry = assistant as Record<string, unknown>;
+      for (const field of SENSITIVE_FIELDS) {
+        delete entry[field];
+      }
+      const resources = entry.resources;
+      if (resources && typeof resources === "object") {
+        for (const field of SENSITIVE_FIELDS) {
+          delete (resources as Record<string, unknown>)[field];
+        }
+      }
+    }
+  }
+}
+
+export function isLoopbackAddr(addr: string): boolean {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1]! : addr;
+  if (normalized.includes(".")) {
+    return normalized.startsWith("127.");
+  }
+  return normalized === "::1";
+}
+
+let _resolvedCliPath: string | undefined;
+
+/**
+ * Resolve the CLI entry point.
+ *
+ * 1. Source tree — `<baseDir>/cli/src/index.ts` (dev mode in monorepo).
+ * 2. Installed package — `require.resolve("@vellumai/cli/package.json")`.
+ */
+function resolveCliPath(baseDir: string, importMetaUrl?: string): string {
+  if (_resolvedCliPath) return _resolvedCliPath;
+
+  const sourceTreePath = path.join(baseDir, "cli", "src", "index.ts");
+  if (fs.existsSync(sourceTreePath)) {
+    _resolvedCliPath = sourceTreePath;
+    return _resolvedCliPath;
+  }
+
+  const _require = createRequire(importMetaUrl ?? `file://${baseDir}/`);
+  try {
+    const pkgPath = _require.resolve(`${CLI_PACKAGE_NAME}/package.json`);
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { bin?: Record<string, string> };
+    const binEntry = pkg.bin?.["vellum"];
+    if (binEntry) {
+      const entryPoint = path.resolve(path.dirname(pkgPath), binEntry);
+      if (fs.existsSync(entryPoint)) {
+        _resolvedCliPath = entryPoint;
+        return _resolvedCliPath;
+      }
+    }
+  } catch {
+    // Not found in node_modules
+  }
+
+  throw new Error(
+    `Vellum CLI not found. Looked for source tree at ${sourceTreePath} and npm package ${CLI_PACKAGE_NAME}.`,
+  );
+}
+
+/**
+ * Build the CLI invocation used by the dev hosts (CLI client server and the
+ * web dev-server middleware), which run the CLI from source via Bun:
+ * `bun run <cli-entry> <subcommand> …`.
+ */
+export function resolveDevCliInvocation(
+  baseDir: string,
+  importMetaUrl?: string,
+): CliInvocation {
+  return { command: "bun", baseArgs: ["run", resolveCliPath(baseDir, importMetaUrl)] };
+}

package/node_modules/@vellumai/local-mode/src/wake.ts

@@ -0,0 +1,78 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+// `wake` cold-starts a stopped assistant, so it can legitimately run far
+// longer than a teardown like `retire`: the CLI waits up to 60s for the daemon
+// to answer (plus another 60s if it falls back to a source daemon) and up to
+// 30s for the gateway. The wrapper timeout is a safety net for a truly hung
+// process, so it must sit above those documented readiness windows — otherwise
+// a slow-but-succeeding wake gets killed and misreported as a timeout.
+const WAKE_TIMEOUT_MS = 180_000;
+
+export type WakeResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+/**
+ * Start (or restart) a local assistant's daemon and gateway via the CLI's
+ * `wake`, which also re-seeds the guardian token from a sibling environment.
+ *
+ * This is the non-destructive repair primitive: it revives a stopped or
+ * mis-seeded local assistant in place without touching its data or identity,
+ * the same way the native client re-pairs on a failed connection. Mirrors
+ * {@link runRetire}'s never-reject contract so each host wires transport once
+ * and surfaces a structured failure rather than a thrown error.
+ */
+export function runWake(
+  invocation: CliInvocation,
+  assistantId: string,
+): Promise<WakeResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "wake", assistantId],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: WakeResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        status: 500,
+        error: `Wake timed out after ${WAKE_TIMEOUT_MS / 1000} seconds`,
+      });
+    }, WAKE_TIMEOUT_MS);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        finish({ ok: true });
+      } else {
+        finish({ ok: false, status: 500, error: stderr || stdout });
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+    });
+  });
+}

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

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.6",
+  "version": "0.8.7-dev.202606052135.3e62c5a",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -8,6 +8,10 @@
     "./package.json": "./package.json",
     "./src/components/DefaultMainScreen": "./src/components/DefaultMainScreen.tsx",
     "./src/lib/constants": "./src/lib/constants.ts",
+    "./src/lib/hatch-local": "./src/lib/hatch-local.ts",
+    "./src/lib/retire-local": "./src/lib/retire-local.ts",
+    "./src/lib/guardian-token": "./src/lib/guardian-token.ts",
+    "./src/lib/lifecycle-reporter": "./src/lib/lifecycle-reporter.ts",
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
@@ -18,18 +22,25 @@
     "format:check": "prettier --check .",
     "lint": "eslint",
     "lint:unused": "knip --include files,dependencies,unlisted",
+    "prepack": "node ../scripts/prepack-bundled-deps.mjs",
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit"
   },
   "author": "Vellum AI",
   "license": "MIT",
   "dependencies": {
+    "@vellumai/environments": "file:../packages/environments",
+    "@vellumai/local-mode": "file:../packages/local-mode",
     "chalk": "5.6.2",
     "ink": "6.8.0",
     "nanoid": "5.1.7",
     "react": "19.2.4",
     "react-devtools-core": "6.1.5"
   },
+  "bundledDependencies": [
+    "@vellumai/environments",
+    "@vellumai/local-mode"
+  ],
   "devDependencies": {
     "@types/bun": "1.3.11",
     "@types/react": "19.2.14",

package/src/__tests__/assistant-client-refresh.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for AssistantClient's reactive 401 -> refresh -> retry: a paired/local
+ * guardian access token that 401s is refreshed once via the stored refresh
+ * credential and the request retried. Self-gating (no refresh token => no
+ * retry) and never applied to the platform session-auth path.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testDir = mkdtempSync(join(tmpdir(), "client-refresh-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_FETCH = globalThis.fetch;
+
+import { AssistantClient } from "../lib/assistant-client.js";
+import { saveAssistantEntry } from "../lib/assistant-config.js";
+import { loadGuardianToken, saveGuardianToken } from "../lib/guardian-token.js";
+
+const RUNTIME = "http://10.0.0.9:7830";
+const FUTURE = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString();
+
+function seedPaired(refreshToken: string): void {
+  saveAssistantEntry({
+    assistantId: "px",
+    name: "Paired",
+    runtimeUrl: RUNTIME,
+    cloud: "paired",
+    paired: true,
+    species: "vellum",
+  });
+  saveGuardianToken("px", {
+    guardianPrincipalId: "imported",
+    accessToken: "old-acc",
+    accessTokenExpiresAt: FUTURE,
+    refreshToken,
+    refreshTokenExpiresAt: refreshToken ? FUTURE : 0,
+    refreshAfter: "",
+    isNew: false,
+    deviceId: "dev",
+    leasedAt: new Date().toISOString(),
+  });
+}
+
+interface Call {
+  url: string;
+  headers: Record<string, string>;
+}
+
+/** Replace global fetch with a URL-routed stub; returns the call log. */
+function stubFetch(handler: (url: string, calls: Call[]) => Response): Call[] {
+  const calls: Call[] = [];
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : String(input);
+    calls.push({
+      url,
+      headers: (init?.headers ?? {}) as Record<string, string>,
+    });
+    return handler(url, calls);
+  }) as typeof fetch;
+  return calls;
+}
+
+const isRefresh = (url: string) => url.includes("/v1/guardian/refresh");
+
+function refreshResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      accessToken: "new-acc",
+      refreshToken: "new-ref",
+      accessTokenExpiresAt: FUTURE,
+      refreshTokenExpiresAt: FUTURE,
+      refreshAfter: "",
+    }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+}
+
+describe("AssistantClient 401 -> refresh -> retry", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    process.env.XDG_CONFIG_HOME = testDir;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = ORIGINAL_FETCH;
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    if (ORIGINAL_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_CONFIG_HOME;
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("refreshes and retries once on 401, persisting the new token", async () => {
+    seedPaired("refresh-tok");
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: assistantAttempts === 1 ? 401 : 200 });
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(200);
+    expect(assistantAttempts).toBe(2); // original + one retry
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(1);
+    // The retry carried the refreshed bearer token.
+    const assistantCalls = calls.filter((c) => !isRefresh(c.url));
+    expect(assistantCalls[1].headers["Authorization"]).toBe("Bearer new-acc");
+    // refreshGuardianToken persisted the rotated token.
+    expect(loadGuardianToken("px")?.accessToken).toBe("new-acc");
+  });
+
+  test("does not retry when there is no stored refresh token", async () => {
+    seedPaired(""); // access-only
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 });
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(1); // no retry
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0);
+  });
+
+  test("never refreshes on the platform session-auth path", async () => {
+    seedPaired("refresh-tok"); // entry must exist; session auth ignores it
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 });
+    });
+
+    const client = new AssistantClient({
+      assistantId: "px",
+      sessionToken: "sess-tok",
+      orgId: "org-1",
+    });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(1);
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(0);
+  });
+
+  test("retries at most once (second 401 is not refreshed again)", async () => {
+    seedPaired("refresh-tok");
+    let assistantAttempts = 0;
+    const calls = stubFetch((url) => {
+      if (isRefresh(url)) return refreshResponse();
+      assistantAttempts++;
+      return new Response("", { status: 401 }); // always 401
+    });
+
+    const client = new AssistantClient({ assistantId: "px" });
+    const res = await client.get("/messages/");
+
+    expect(res.status).toBe(401);
+    expect(assistantAttempts).toBe(2); // original + one retry, no more
+    expect(calls.filter((c) => isRefresh(c.url))).toHaveLength(1);
+  });
+});

package/src/__tests__/clean.test.ts

@@ -0,0 +1,179 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+
+import type { OrphanedProcess } from "../lib/orphan-detection.js";
+
+// ── Module mocks (must be set up before importing the command) ───────────────
+
+const detectOrphansMock = mock(async (): Promise<OrphanedProcess[]> => []);
+const stopProcessMock = mock(
+  async (_pid: number, _label: string): Promise<boolean> => true,
+);
+
+beforeAll(() => {
+  mock.module("../lib/orphan-detection.js", () => ({
+    detectOrphanedProcesses: detectOrphansMock,
+  }));
+  mock.module("../lib/process.js", () => ({
+    stopProcess: stopProcessMock,
+  }));
+});
+
+import { clean } from "../commands/clean.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeOrphan(
+  name: string,
+  pid: string,
+  source = "process table",
+): OrphanedProcess {
+  return { name, pid, source };
+}
+
+const originalArgv = [...process.argv];
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+let exitSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+  consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  exitSpy = spyOn(process, "exit").mockImplementation((_code?: number) => {
+    throw new Error(`process.exit(${_code})`);
+  });
+  detectOrphansMock.mockClear();
+  stopProcessMock.mockClear();
+});
+
+afterEach(() => {
+  process.argv = [...originalArgv];
+  consoleLogSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  exitSpy.mockRestore();
+});
+
+afterAll(() => {
+  process.argv = [...originalArgv];
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("vellum clean --help", () => {
+  test("prints usage and exits 0", async () => {
+    process.argv = ["bun", "vellum", "clean", "--help"];
+    await expect(clean()).rejects.toThrow("process.exit(0)");
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Usage: vellum clean");
+    expect(output).toContain("orphaned");
+  });
+
+  test("-h is accepted as an alias for --help", async () => {
+    process.argv = ["bun", "vellum", "clean", "-h"];
+    await expect(clean()).rejects.toThrow("process.exit(0)");
+  });
+});
+
+describe("vellum clean — no orphans", () => {
+  test("prints nothing-to-do message when no orphans are found", async () => {
+    detectOrphansMock.mockResolvedValueOnce([]);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("No orphaned processes found.");
+    expect(stopProcessMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("vellum clean — single orphan", () => {
+  test("kills the orphan and prints singular 'process'", async () => {
+    detectOrphansMock.mockResolvedValueOnce([makeOrphan("assistant", "12345")]);
+    stopProcessMock.mockResolvedValueOnce(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    expect(stopProcessMock).toHaveBeenCalledTimes(1);
+    expect(stopProcessMock).toHaveBeenCalledWith(
+      12345,
+      "assistant (PID 12345)",
+    );
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 1 orphaned process");
+    expect(output).not.toContain("processes");
+    expect(output).toContain("Cleaned up 1 process.");
+    expect(output).not.toContain("processes.");
+  });
+
+  test("reports 0 cleaned when stopProcess returns false", async () => {
+    detectOrphansMock.mockResolvedValueOnce([makeOrphan("gateway", "99999")]);
+    stopProcessMock.mockResolvedValueOnce(false);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Cleaned up 0 process");
+  });
+});
+
+describe("vellum clean — multiple orphans", () => {
+  test("uses plural 'processes' with multiple orphans", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "1001"),
+      makeOrphan("gateway", "1002"),
+      makeOrphan("qdrant", "1003"),
+    ]);
+    stopProcessMock.mockResolvedValue(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    expect(stopProcessMock).toHaveBeenCalledTimes(3);
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 3 orphaned processes");
+    expect(output).toContain("Cleaned up 3 processes.");
+  });
+
+  test("counts only successfully stopped processes in the total", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "2001"),
+      makeOrphan("qdrant", "2002"),
+      makeOrphan("gateway", "2003"),
+    ]);
+    // Only the first and third succeed
+    stopProcessMock
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(false)
+      .mockResolvedValueOnce(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Found 3 orphaned processes");
+    expect(output).toContain("Cleaned up 2 processes.");
+  });
+
+  test("passes the correct PID and label to stopProcess for each orphan", async () => {
+    detectOrphansMock.mockResolvedValueOnce([
+      makeOrphan("assistant", "3001"),
+      makeOrphan("gateway", "3002"),
+    ]);
+    stopProcessMock.mockResolvedValue(true);
+    process.argv = ["bun", "vellum", "clean"];
+    await clean();
+
+    const calls = stopProcessMock.mock.calls as [number, string][];
+    expect(calls[0]).toEqual([3001, "assistant (PID 3001)"]);
+    expect(calls[1]).toEqual([3002, "gateway (PID 3002)"]);
+  });
+});