@vellumai/cli 0.8.12-dev.202606152248.70317d3 → 0.8.12-dev.202606160320.367ef7c

package/node_modules/@vellumai/local-mode/src/__tests__/status.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { getLocalAssistantStatus } from "../status";
+
+let tempDir: string;
+let lockfilePath: string;
+let instanceDir: string;
+
+function writeLockfile(entry: Record<string, unknown>): void {
+  writeFileSync(
+    lockfilePath,
+    JSON.stringify({
+      assistants: [entry],
+      activeAssistant: entry.assistantId,
+    }),
+  );
+}
+
+function writeLocalLockfile(overrides: Record<string, unknown> = {}): void {
+  writeLockfile({
+    assistantId: "local-1",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 30101,
+      gatewayPort: 30102,
+      qdrantPort: 30103,
+    },
+    ...overrides,
+  });
+}
+
+function writeAssistantPid(value: string): string {
+  const pidDir = path.join(instanceDir, ".vellum", "workspace");
+  mkdirSync(pidDir, { recursive: true });
+  const pidPath = path.join(pidDir, "vellum.pid");
+  writeFileSync(pidPath, value);
+  return pidPath;
+}
+
+function markStale(filePath: string): void {
+  const stale = new Date(Date.now() - 120_000);
+  utimesSync(filePath, stale, stale);
+}
+
+function listen(server: Server, port = 0): Promise<number> {
+  return new Promise((resolve) => {
+    server.listen(port, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("expected TCP server address");
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+function close(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+async function unusedPort(): Promise<number> {
+  const server = createServer();
+  const port = await listen(server);
+  await close(server);
+  return port;
+}
+
+beforeEach(() => {
+  tempDir = path.join(
+    tmpdir(),
+    `vellum-local-status-test-${Date.now()}-${Math.random()}`,
+  );
+  mkdirSync(tempDir, { recursive: true });
+  lockfilePath = path.join(tempDir, "lockfile.json");
+  instanceDir = path.join(tempDir, "instance");
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("getLocalAssistantStatus", () => {
+  test("returns sleeping when the assistant PID file is absent", async () => {
+    writeLocalLockfile();
+
+    expect(await getLocalAssistantStatus([lockfilePath], "local-1")).toEqual({
+      ok: true,
+      state: "sleeping",
+    });
+  });
+
+  test("returns sleeping for legacy local entries without cloud/resources", async () => {
+    writeLockfile({
+      assistantId: "legacy-local",
+      baseDataDir: instanceDir,
+      runtimeUrl: "http://127.0.0.1:30102",
+    });
+
+    expect(
+      await getLocalAssistantStatus([lockfilePath], "legacy-local"),
+    ).toEqual({
+      ok: true,
+      state: "sleeping",
+    });
+  });
+
+  test("returns sleeping when the assistant PID file points at a dead process", async () => {
+    writeLocalLockfile();
+    writeAssistantPid("999999999");
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("sleeping");
+    }
+  });
+
+  test("returns crashed when the assistant PID file is invalid", async () => {
+    writeLocalLockfile();
+    writeAssistantPid("not-a-pid");
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("crashed");
+      expect(result.detail).toContain("PID file");
+    }
+  });
+
+  test("returns starting when a fresh assistant PID is alive but health is not ready yet", async () => {
+    writeLocalLockfile({
+      resources: {
+        instanceDir,
+        daemonPort: await unusedPort(),
+        gatewayPort: 30102,
+        qdrantPort: 30103,
+      },
+    });
+    writeAssistantPid(String(process.pid));
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("starting");
+      expect(result.pid).toBe(process.pid);
+    }
+  });
+
+  test("returns crashed when an old live assistant PID is still not responding", async () => {
+    writeLocalLockfile({
+      resources: {
+        instanceDir,
+        daemonPort: await unusedPort(),
+        gatewayPort: 30102,
+        qdrantPort: 30103,
+      },
+    });
+    const pidPath = writeAssistantPid(String(process.pid));
+    markStale(pidPath);
+
+    const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.state).toBe("crashed");
+      expect(result.detail).toContain("not responding");
+    }
+  });
+
+  test("returns starting while the gateway is coming up for a freshly started assistant", async () => {
+    const server = createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "healthy" }));
+    });
+    const daemonPort = await listen(server);
+    try {
+      writeLocalLockfile({
+        resources: {
+          instanceDir,
+          daemonPort,
+          gatewayPort: await unusedPort(),
+          qdrantPort: 30103,
+        },
+      });
+      writeAssistantPid(String(process.pid));
+
+      const result = await getLocalAssistantStatus([lockfilePath], "local-1");
+
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state).toBe("starting");
+        expect(result.pid).toBe(process.pid);
+      }
+    } finally {
+      await close(server);
+    }
+  });
+
+  test("rejects non-local assistants", async () => {
+    writeLockfile({
+      assistantId: "platform-1",
+      cloud: "vellum",
+      runtimeUrl: "https://example.com",
+    });
+
+    expect(await getLocalAssistantStatus([lockfilePath], "platform-1")).toEqual(
+      {
+        ok: false,
+        status: 404,
+        error: "Local assistant not found",
+      },
+    );
+  });
+});

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

@@ -35,8 +35,15 @@ export { runHatch } from "./hatch";
 export type { HatchResult } from "./hatch";
 export { runRetire } from "./retire";
 export type { RetireResult } from "./retire";
+export { runSleep } from "./sleep";
+export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
 export type { WakeOptions, WakeResult } from "./wake";
+export { getLocalAssistantStatus } from "./status";
+export type {
+  LocalAssistantRuntimeState,
+  LocalAssistantStatusResult,
+} from "./status";
 export { getGuardianAccessToken } from "./guardian-token";
 export type { TokenResult } from "./guardian-token";
 export {

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

@@ -31,6 +31,7 @@
  */
 
 export interface LocalAssistantResources {
+  instanceDir?: string;
   gatewayPort: number;
   daemonPort: number;
 }
@@ -69,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,
+  };
 }
 
 /**

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.12-dev.202606152248.70317d3",
+  "version": "0.8.12-dev.202606160320.367ef7c",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {