@vellumai/cli 0.8.12 → 0.9.0-staging.1

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -31,6 +31,7 @@
  */
 
 export interface LocalAssistantResources {
+  instanceDir?: string;
   gatewayPort: number;
   daemonPort: number;
 }
@@ -42,8 +43,6 @@ export interface LockfileAssistant {
   runtimeUrl?: string;
   species?: string;
   hatchedAt?: string;
-  /** Installed release version (no `v` prefix), written by the CLI at hatch/upgrade. */
-  version?: string;
   /** Owning org for platform assistants; absent for local ones. */
   organizationId?: string;
   resources?: LocalAssistantResources;
@@ -71,7 +70,13 @@ function parseResources(value: unknown): LocalAssistantResources | undefined {
   if (!isRecord(value)) return undefined;
   if (typeof value.gatewayPort !== "number") return undefined;
   if (typeof value.daemonPort !== "number") return undefined;
-  return { gatewayPort: value.gatewayPort, daemonPort: value.daemonPort };
+  return {
+    ...(typeof value.instanceDir === "string"
+      ? { instanceDir: value.instanceDir }
+      : {}),
+    gatewayPort: value.gatewayPort,
+    daemonPort: value.daemonPort,
+  };
 }
 
 /**
@@ -91,7 +96,6 @@ function parseAssistant(value: unknown): LockfileAssistant | null {
   if (typeof value.runtimeUrl === "string") assistant.runtimeUrl = value.runtimeUrl;
   if (typeof value.species === "string") assistant.species = value.species;
   if (typeof value.hatchedAt === "string") assistant.hatchedAt = value.hatchedAt;
-  if (typeof value.version === "string") assistant.version = value.version;
   if (typeof value.organizationId === "string") assistant.organizationId = value.organizationId;
   const resources = parseResources(value.resources);
   if (resources) assistant.resources = resources;

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

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+// The CLI's `sleep` command uses a 120s SIGKILL ceiling for the assistant
+// daemon (WAL checkpoint can be slow on large databases) plus 7s for the
+// gateway drain window. The wrapper timeout must sit above that total so a
+// slow-but-succeeding sleep isn't killed and misreported as a timeout.
+const SLEEP_TIMEOUT_MS = 150_000;
+
+export type SleepResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+/**
+ * Stop a local assistant's daemon and gateway via the CLI's `sleep --force`.
+ *
+ * Uses `--force` to bypass the active-call-lease guard — the restart flow
+ * immediately follows with a `wake`, so the brief interruption is expected
+ * and user-confirmed at the UI level.
+ *
+ * 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 runSleep(
+  invocation: CliInvocation,
+  assistantId: string,
+): Promise<SleepResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "sleep", assistantId, "--force"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: SleepResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        status: 500,
+        error: `Sleep timed out after ${SLEEP_TIMEOUT_MS / 1000} seconds`,
+      });
+    }, SLEEP_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/status.ts

@@ -0,0 +1,342 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import http from "node:http";
+import path from "node:path";
+
+import { SEEDS } from "@vellumai/environments";
+
+import type {
+  LockfileAssistant,
+} from "./lockfile-contract";
+import { getLockfileData } from "./lockfile";
+
+const HEALTH_TIMEOUT_MS = 1_500;
+const STARTING_GRACE_MS = 60_000;
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+const DEFAULT_PORTS = {
+  daemon: 7821,
+  gateway: 7830,
+};
+
+export type LocalAssistantRuntimeState =
+  | "healthy"
+  | "sleeping"
+  | "starting"
+  | "crashed"
+  | "unknown";
+
+export type LocalAssistantStatusResult =
+  | {
+      ok: true;
+      state: LocalAssistantRuntimeState;
+      detail?: string;
+      pid?: number;
+    }
+  | { ok: false; status: number; error: string };
+
+type PidState =
+  | { state: "missing" }
+  | { state: "starting"; updatedAtMs: number }
+  | { state: "alive"; pid: number; updatedAtMs: number }
+  | { state: "dead"; pid: number; updatedAtMs: number }
+  | { state: "invalid"; value: string; updatedAtMs: number };
+
+interface StatusResources {
+  instanceDir: string;
+  gatewayPort: number;
+  daemonPort: number;
+}
+
+function getDaemonPidPath(instanceDir: string): string {
+  return path.join(instanceDir, ".vellum", "workspace", "vellum.pid");
+}
+
+function getGatewayPidPath(instanceDir: string): string {
+  return path.join(instanceDir, ".vellum", "gateway.pid");
+}
+
+function readPidState(pidFile: string): PidState {
+  if (!existsSync(pidFile)) return { state: "missing" };
+
+  const updatedAtMs = statSync(pidFile).mtimeMs;
+  const value = readFileSync(pidFile, "utf-8").trim();
+  if (!value) return { state: "missing" };
+  if (value === "starting") return { state: "starting", updatedAtMs };
+
+  const pid = Number(value);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { state: "invalid", value, updatedAtMs };
+  }
+
+  try {
+    process.kill(pid, 0);
+    return { state: "alive", pid, updatedAtMs };
+  } catch {
+    return { state: "dead", pid, updatedAtMs };
+  }
+}
+
+function isFreshPidState(
+  pidState: PidState,
+  observedAtMs: number,
+): boolean {
+  return (
+    "updatedAtMs" in pidState &&
+    observedAtMs - pidState.updatedAtMs <= STARTING_GRACE_MS
+  );
+}
+
+function httpHealthCheck(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/healthz",
+        timeout: HEALTH_TIMEOUT_MS,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            resolve(false);
+            return;
+          }
+
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString()) as {
+              status?: string;
+            };
+            resolve(
+              body.status === undefined ||
+                body.status === "healthy" ||
+                body.status === "ok",
+            );
+          } catch {
+            resolve(true);
+          }
+        });
+      },
+    );
+
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on("error", () => resolve(false));
+  });
+}
+
+function localOnlyEntry(
+  entry: LockfileAssistant | undefined,
+): LockfileAssistant | null {
+  if (!entry || (entry.cloud != null && entry.cloud !== "local")) return null;
+  return entry;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string") return undefined;
+  try {
+    const parsed = new URL(url);
+    const port = Number(parsed.port);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultPorts(env: Record<string, string | undefined>): {
+  daemon: number;
+  gateway: number;
+} {
+  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
+  const seed = SEEDS[envName] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME];
+  return {
+    daemon: seed?.portsOverride?.daemon ?? DEFAULT_PORTS.daemon,
+    gateway: seed?.portsOverride?.gateway ?? DEFAULT_PORTS.gateway,
+  };
+}
+
+function defaultInstanceDir(
+  env: Record<string, string | undefined>,
+  assistantId: string,
+): string {
+  const envName = env.VELLUM_ENVIRONMENT?.trim() || PRODUCTION_ENVIRONMENT_NAME;
+  const xdgDataHome =
+    env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), ".local", "share");
+  const dataRoot =
+    envName === PRODUCTION_ENVIRONMENT_NAME ? "vellum" : `vellum-${envName}`;
+  return path.join(xdgDataHome, dataRoot, "assistants", assistantId);
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+function firstNumber(...values: unknown[]): number | undefined {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+function findRawAssistant(
+  lockfilePaths: string[],
+  assistantId: string,
+): Record<string, unknown> | null {
+  for (const candidate of lockfilePaths) {
+    let data: unknown;
+    try {
+      data = JSON.parse(readFileSync(candidate, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (!isRecord(data) || !Array.isArray(data.assistants)) return null;
+    const entry = data.assistants.find(
+      (assistant) =>
+        isRecord(assistant) && assistant.assistantId === assistantId,
+    );
+    return isRecord(entry) ? entry : null;
+  }
+  return null;
+}
+
+function resolveStatusResources(
+  entry: LockfileAssistant,
+  rawEntry: Record<string, unknown> | null,
+  env: Record<string, string | undefined>,
+): StatusResources {
+  const rawResources = isRecord(rawEntry?.resources)
+    ? rawEntry.resources
+    : undefined;
+  const ports = defaultPorts(env);
+  const instanceDir =
+    firstString(
+      entry.resources?.instanceDir,
+      rawResources?.instanceDir,
+      rawEntry?.baseDataDir,
+    ) ?? defaultInstanceDir(env, entry.assistantId);
+  return {
+    instanceDir,
+    daemonPort:
+      firstNumber(entry.resources?.daemonPort, rawResources?.daemonPort) ??
+      ports.daemon,
+    gatewayPort:
+      firstNumber(entry.resources?.gatewayPort, rawResources?.gatewayPort) ??
+      parsePortFromUrl(rawEntry?.localUrl) ??
+      parsePortFromUrl(rawEntry?.runtimeUrl ?? entry.runtimeUrl) ??
+      ports.gateway,
+  };
+}
+
+async function runtimeStatusForEntry(
+  entry: LockfileAssistant,
+  rawEntry: Record<string, unknown> | null,
+  env: Record<string, string | undefined>,
+): Promise<LocalAssistantStatusResult> {
+  const resources = resolveStatusResources(entry, rawEntry, env);
+  const observedAtMs = Date.now();
+
+  const assistantPid = readPidState(getDaemonPidPath(resources.instanceDir));
+  if (assistantPid.state === "missing") {
+    return { ok: true, state: "sleeping" };
+  }
+  if (assistantPid.state === "starting") {
+    return { ok: true, state: "starting" };
+  }
+  if (assistantPid.state === "dead") {
+    return { ok: true, state: "sleeping", pid: assistantPid.pid };
+  }
+  if (assistantPid.state === "invalid") {
+    return {
+      ok: true,
+      state: "crashed",
+      detail: "assistant PID file is invalid",
+    };
+  }
+
+  const assistantHealthy = await httpHealthCheck(resources.daemonPort);
+  if (!assistantHealthy) {
+    if (isFreshPidState(assistantPid, observedAtMs)) {
+      return { ok: true, state: "starting", pid: assistantPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: assistantPid.pid,
+      detail: "assistant process is not responding",
+    };
+  }
+
+  const gatewayPid = readPidState(getGatewayPidPath(resources.instanceDir));
+  if (gatewayPid.state === "starting") {
+    return { ok: true, state: "starting", pid: assistantPid.pid };
+  }
+  if (gatewayPid.state !== "alive") {
+    if (
+      isFreshPidState(assistantPid, observedAtMs) ||
+      isFreshPidState(gatewayPid, observedAtMs)
+    ) {
+      return { ok: true, state: "starting", pid: assistantPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: assistantPid.pid,
+      detail: "gateway process is not running",
+    };
+  }
+
+  const gatewayHealthy = await httpHealthCheck(resources.gatewayPort);
+  if (!gatewayHealthy) {
+    if (isFreshPidState(gatewayPid, observedAtMs)) {
+      return { ok: true, state: "starting", pid: gatewayPid.pid };
+    }
+    return {
+      ok: true,
+      state: "crashed",
+      pid: gatewayPid.pid,
+      detail: "gateway process is not responding",
+    };
+  }
+
+  return { ok: true, state: "healthy", pid: assistantPid.pid };
+}
+
+export async function getLocalAssistantStatus(
+  lockfilePaths: string[],
+  assistantId: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<LocalAssistantStatusResult> {
+  const result = getLockfileData(lockfilePaths);
+  if (!result.ok) {
+    return {
+      ok: false,
+      status: result.status,
+      error: result.error ?? "Failed to read lockfile",
+    };
+  }
+
+  const entry = localOnlyEntry(
+    result.data.assistants.find(
+      (assistant) => assistant.assistantId === assistantId,
+    ),
+  );
+  if (!entry) {
+    return { ok: false, status: 404, error: "Local assistant not found" };
+  }
+
+  return runtimeStatusForEntry(
+    entry,
+    findRawAssistant(lockfilePaths, assistantId),
+    env,
+  );
+}

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

@@ -14,6 +14,11 @@ export type WakeResult =
   | { ok: true }
   | { ok: false; status: number; error: string };
 
+export interface WakeOptions {
+  /** Pass --repair-guardian to re-provision a missing/expired guardian token. Revokes the assistant's other device-bound tokens, so callers must gate this behind explicit user confirmation. */
+  repairGuardian?: boolean;
+}
+
 /**
  * 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.
@@ -27,11 +32,17 @@ export type WakeResult =
 export function runWake(
   invocation: CliInvocation,
   assistantId: string,
+  options?: WakeOptions,
 ): Promise<WakeResult> {
   return new Promise((resolve) => {
     const child = spawn(
       invocation.command,
-      [...invocation.baseArgs, "wake", assistantId],
+      [
+        ...invocation.baseArgs,
+        "wake",
+        assistantId,
+        ...(options?.repairGuardian ? ["--repair-guardian"] : []),
+      ],
       { stdio: ["ignore", "pipe", "pipe"] },
     );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.12",
+  "version": "0.9.0-staging.1",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -23,6 +23,7 @@
     "lint": "eslint",
     "lint:unused": "knip --include files,dependencies,unlisted",
     "prepack": "node ../scripts/prepack-bundled-deps.mjs",
+    "compile:check": "bun build --compile --external react-devtools-core src/index.ts --outfile /dev/null",
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit"
   },
@@ -34,8 +35,7 @@
     "chalk": "5.6.2",
     "ink": "6.8.0",
     "nanoid": "5.1.7",
-    "react": "19.2.4",
-    "react-devtools-core": "6.1.5"
+    "react": "19.2.4"
   },
   "bundledDependencies": [
     "@vellumai/environments",

package/src/__tests__/assistant-config.test.ts

@@ -75,12 +75,11 @@ describe("assistant-config", () => {
   });
 
   test("saveAssistantEntry and loadAllAssistants round-trip", () => {
-    const entry = makeEntry("test-1", undefined, { version: "0.7.0" });
+    const entry = makeEntry("test-1");
     saveAssistantEntry(entry);
     const all = loadAllAssistants();
     expect(all).toHaveLength(1);
     expect(all[0].assistantId).toBe("test-1");
-    expect(all[0].version).toBe("0.7.0");
   });
 
   test("findAssistantByName returns matching entry", () => {

package/src/__tests__/device-id.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   existsSync,
   mkdirSync,
@@ -11,22 +11,17 @@ import {
 import { tmpdir } from "os";
 import { join } from "path";
 
-// Bun's os.homedir() ignores runtime HOME changes, so mock it (same pattern
-// as multi-local.test.ts) to keep production-path tests off the real ~/.vellum.
+// Bun's os.homedir() ignores runtime HOME changes, so mock it (via the shared
+// helper) to keep production-path tests off the real ~/.vellum.
 let fakeHome: string | undefined;
-const realOs = await import("node:os");
-const osMock = () => ({
-  ...realOs,
-  homedir: () => fakeHome ?? realOs.homedir(),
-});
-mock.module("node:os", osMock);
-mock.module("os", osMock);
+await mockOsHomedir((realHomedir) => () => fakeHome ?? realHomedir());
 
 import {
   getOrCreateHostDeviceId,
   resetHostDeviceIdCache,
 } from "../lib/device-id.js";
 import { snapshotEnv } from "./helpers/env.js";
+import { mockOsHomedir } from "./helpers/os-mock.js";
 
 const UUID_RE =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -154,10 +149,7 @@ describe("getOrCreateHostDeviceId (production)", () => {
 
   test("reuses an existing ~/.vellum/device.json", () => {
     mkdirSync(join(tempHome, ".vellum"), { recursive: true });
-    writeFileSync(
-      deviceFile,
-      JSON.stringify({ deviceId: "shared-prod-id" }),
-    );
+    writeFileSync(deviceFile, JSON.stringify({ deviceId: "shared-prod-id" }));
 
     expect(getOrCreateHostDeviceId()).toBe("shared-prod-id");
     expect(readFileSync(deviceFile, "utf-8")).toBe(

package/src/__tests__/helpers/os-mock.ts

@@ -0,0 +1,27 @@
+import { mock } from "bun:test";
+
+/**
+ * Mock `os.homedir()` (both the `"os"` and `"node:os"` specifiers) while
+ * keeping every other os export intact.
+ *
+ * The factory passed to `mock.module()` must only close over plain snapshots
+ * captured before the mock is installed. When another test file has already
+ * loaded "os", `mock.module()` patches the live namespace in place — a
+ * factory that spreads or calls back through that namespace resolves to the
+ * mock itself and recurses forever, a synchronous spin that froze the whole
+ * suite (and CI) at whichever file loaded next. This helper owns that
+ * invariant so test files don't have to.
+ *
+ * @param makeHomedir Receives the real (pre-mock) `homedir` and returns the
+ *   replacement implementation.
+ */
+export async function mockOsHomedir(
+  makeHomedir: (realHomedir: () => string) => () => string,
+): Promise<void> {
+  const realOs = await import("node:os");
+  const realOsSnapshot = { ...realOs };
+  const homedir = makeHomedir(realOs.homedir);
+  const factory = () => ({ ...realOsSnapshot, homedir });
+  mock.module("node:os", factory);
+  mock.module("os", factory);
+}

package/src/__tests__/login-loopback.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+
+import { startLoopbackListener } from "../commands/login.js";
+
+/** Resolve "settled"/"pending" — proves whether `waitForCode` resolved. */
+async function settleState(p: Promise<unknown>): Promise<"settled" | "pending"> {
+  return Promise.race([
+    p.then(
+      () => "settled" as const,
+      () => "settled" as const,
+    ),
+    new Promise<"pending">((r) => setTimeout(() => r("pending"), 50)),
+  ]);
+}
+
+describe("startLoopbackListener", () => {
+  test("rejects a state-mismatched callback (CSRF) without settling", async () => {
+    const listener = await startLoopbackListener("expected-state");
+    try {
+      // Wrong state — the load-bearing CSRF check. Any local process can
+      // hit the loopback port, so a mismatched state must NOT deliver a code.
+      const res = await fetch(`${listener.redirectUri}?code=evil&state=wrong`);
+      expect(res.status).toBe(404);
+      expect(await settleState(listener.waitForCode)).toBe("pending");
+
+      // Wrong path on the right port is also ignored.
+      const noise = await fetch(
+        `${listener.redirectUri.replace("/auth/callback", "/evil")}?state=expected-state&code=c`,
+      );
+      expect(noise.status).toBe(404);
+      expect(await settleState(listener.waitForCode)).toBe("pending");
+
+      // A state-matched callback then settles it — the listener kept
+      // listening through the noise above.
+      const ok = await fetch(
+        `${listener.redirectUri}?code=good-code&state=expected-state`,
+      );
+      expect(ok.status).toBe(200);
+      expect(await listener.waitForCode).toBe("good-code");
+    } finally {
+      listener.close();
+    }
+  });
+
+  test("rejects on an error callback with the matching state", async () => {
+    const listener = await startLoopbackListener("st");
+    try {
+      const settled = listener.waitForCode.then(
+        () => null,
+        (e: Error) => e,
+      );
+      const res = await fetch(`${listener.redirectUri}?error=access_denied&state=st`);
+      expect(res.status).toBe(400);
+      const err = await settled;
+      expect(err?.message).toMatch(/access_denied/);
+    } finally {
+      listener.close();
+    }
+  });
+
+  test("close rejects a pending waiter with the given reason", async () => {
+    const listener = await startLoopbackListener("st");
+    const settled = listener.waitForCode.then(
+      () => null,
+      (e: Error) => e,
+    );
+    listener.close("Login timed out. Please try again.");
+    const err = await settled;
+    expect(err?.message).toMatch(/timed out/);
+  });
+});