@vellumai/cli 0.4.56 → 0.5.0

package/AGENTS.md

@@ -6,14 +6,11 @@ The `cli/` package (`@vellumai/cli`) manages the **lifecycle of Vellum assistant
 
 This contrasts with `assistant/src/cli/`, where commands are scoped to a **single running assistant** and operate on its local state (config, memory, contacts, etc.).
 
-## When a command belongs here vs `assistant/src/cli/`
+## Scope
 
-| `cli/` (this package)                           | `assistant/src/cli/`                                |
-| ----------------------------------------------- | --------------------------------------------------- |
-| Operates on or across assistant instances       | Operates within a single assistant's workspace      |
-| Manages lifecycle (create, start, stop, delete) | Manages instance-local state (config, memory, etc.) |
-| Requires specifying which assistant to target   | Implicitly scoped to the running assistant          |
-| Works without an assistant process running      | May require or start the daemon                     |
+Commands here operate on or across **assistant instances** — creating, starting, stopping, connecting to, and deleting them. They require specifying which assistant to target and work without an assistant process running.
+
+For commands scoped to a **single running assistant's** local state (config, memory, contacts), see `assistant/src/cli/AGENTS.md`.
 
 Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`, `contacts`, `memory` belong in `assistant/src/cli/`.
 
@@ -30,9 +27,7 @@ Commands that act on a specific assistant should accept an assistant name or ID
 
 ## Help Text Standards
 
-Every command must have high-quality `--help` output optimized for AI/LLM
-consumption. Help text is a primary interface — both humans and AI agents read
-it to understand what a command does and how to use it.
+Every command must have high-quality `--help` output. Follow the same standards as `assistant/src/cli/AGENTS.md` § Help Text Standards, adapted for this package's manual argv parsing (no Commander.js).
 
 ### Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.56",
+  "version": "0.5.0",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/coverage.test.ts

@@ -5,6 +5,11 @@ import { resolve } from "node:path";
 import { expect, test } from "bun:test";
 
 const EXCLUDE_PATTERNS = [".test.ts", ".d.ts"];
+const EXCLUDE_DIRS = [
+  // Ink components import yoga-layout whose WASM binary crashes
+  // intermittently during headless import (null reference in za()).
+  "components/",
+];
 const EXCLUDE_FILES = [
   // index.ts calls main() at module level, causing side effects on import
   "index.ts",
@@ -15,6 +20,7 @@ async function importAllModules(dir: string): Promise<string[]> {
   const files = [...glob.scanSync(dir)].filter(
     (f) =>
       !EXCLUDE_PATTERNS.some((pattern) => f.endsWith(pattern)) &&
+      !EXCLUDE_DIRS.some((dir) => f.startsWith(dir)) &&
       !EXCLUDE_FILES.some((excluded) => f === excluded) &&
       !f.includes("__tests__"),
   );

package/src/commands/client.ts

@@ -6,6 +6,7 @@ import {
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import { DAEMON_INTERNAL_ASSISTANT_ID, GATEWAY_PORT, type Species } from "../lib/constants";
+import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4, getMacLocalHostname } from "../lib/local";
 
 const ANSI = {
@@ -83,7 +84,7 @@ function parseArgs(): ParsedArgs {
 
   let runtimeUrl = entry?.localUrl || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
   let assistantId = entry?.assistantId || DAEMON_INTERNAL_ASSISTANT_ID;
-  const bearerToken = entry?.bearerToken || undefined;
+  const bearerToken = loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined;
   const species: Species = (entry?.species as Species) ?? "vellum";
 
   for (let i = 0; i < flagArgs.length; i++) {

package/src/commands/hatch.ts

@@ -383,7 +383,7 @@ export async function watchHatching(
         );
         console.log(`   Monitor with: vel logs ${instanceName}`);
         console.log("");
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 
@@ -428,7 +428,7 @@ function watchHatchingDesktop(
           `Timed out after ${formatElapsed(elapsed)}. Instance is still running.`,
         );
         desktopLog(`Monitor with: vel logs ${instanceName}`);
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 
@@ -701,32 +701,36 @@ async function hatchLocal(
 
   await startLocalDaemon(watch, resources);
 
-  let runtimeUrl: string;
-  try {
-    runtimeUrl = await startGateway(watch, resources);
-  } catch (error) {
-    // Gateway failed — stop the daemon we just started so we don't leave
-    // orphaned processes with no lock file entry.
-    console.error(
-      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
-    );
-    await stopLocalProcesses(resources);
-    throw error;
-  }
+  // When daemonOnly is set, skip gateway and ngrok — the caller only wants
+  // the daemon restarted (e.g. macOS app bootstrap retry).
+  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+  if (!daemonOnly) {
+    try {
+      runtimeUrl = await startGateway(watch, resources);
+    } catch (error) {
+      // Gateway failed — stop the daemon we just started so we don't leave
+      // orphaned processes with no lock file entry.
+      console.error(
+        `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
+      );
+      await stopLocalProcesses(resources);
+      throw error;
+    }
 
-  // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
+    // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
+    // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+    const prevBaseDataDir = process.env.BASE_DATA_DIR;
+    process.env.BASE_DATA_DIR = resources.instanceDir;
+    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+    if (ngrokChild?.pid) {
+      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+    }
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
+    }
   }
 
   const localEntry: AssistantEntry = {
@@ -757,7 +761,12 @@ async function hatchLocal(
   }
 
   if (keepAlive) {
-    const gatewayHealthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    // When --daemon-only is set, no gateway is running — poll the daemon
+    // health endpoint instead of the gateway to avoid self-termination.
+    const healthUrl = daemonOnly
+      ? `http://127.0.0.1:${resources.daemonPort}/healthz`
+      : `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    const healthTarget = daemonOnly ? "Assistant" : "Gateway";
     const POLL_INTERVAL_MS = 5000;
     const MAX_FAILURES = 3;
     let consecutiveFailures = 0;
@@ -771,11 +780,11 @@ async function hatchLocal(
     process.on("SIGTERM", () => void shutdown());
     process.on("SIGINT", () => void shutdown());
 
-    // Poll the gateway health endpoint until it stops responding.
+    // Poll the health endpoint until it stops responding.
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       try {
-        const res = await fetch(gatewayHealthUrl, {
+        const res = await fetch(healthUrl, {
           signal: AbortSignal.timeout(3000),
         });
         if (res.ok) {
@@ -787,7 +796,9 @@ async function hatchLocal(
         consecutiveFailures++;
       }
       if (consecutiveFailures >= MAX_FAILURES) {
-        console.log("\n⚠️  Gateway stopped responding — shutting down.");
+        console.log(
+          `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
+        );
         await stopLocalProcesses(resources);
         process.exit(1);
       }

package/src/commands/pair.ts

@@ -7,6 +7,8 @@ import { PNG } from "pngjs";
 import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import type { Species } from "../lib/constants";
+import { saveGuardianToken } from "../lib/guardian-token";
+import type { GuardianTokenData } from "../lib/guardian-token";
 import { generateInstanceName } from "../lib/random-name";
 
 interface QRPairingPayload {
@@ -168,13 +170,27 @@ export async function pair(): Promise<void> {
     const customEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
-      bearerToken,
       cloud: "custom",
       species,
       hatchedAt: new Date().toISOString(),
     };
     saveAssistantEntry(customEntry);
 
+    if (bearerToken) {
+      const tokenData: GuardianTokenData = {
+        guardianPrincipalId: "",
+        accessToken: bearerToken,
+        accessTokenExpiresAt: "",
+        refreshToken: "",
+        refreshTokenExpiresAt: "",
+        refreshAfter: "",
+        isNew: true,
+        deviceId: getDeviceId(),
+        leasedAt: new Date().toISOString(),
+      };
+      saveGuardianToken(instanceName, tokenData);
+    }
+
     console.log("");
     console.log("Successfully paired with remote assistant!");
     console.log("Instance details:");

package/src/commands/ps.ts

@@ -6,7 +6,9 @@ import {
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { loadGuardianToken } from "../lib/guardian-token";
 import { checkHealth, checkManagedHealth } from "../lib/health-check";
+import { dockerResourceNames } from "../lib/docker";
 import {
   classifyProcess,
   detectOrphanedProcesses,
@@ -248,6 +250,73 @@ async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
   }));
 }
 
+async function getDockerContainerState(
+  containerName: string,
+): Promise<string | null> {
+  try {
+    const output = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{.State.Status}}",
+      containerName,
+    ]);
+    return output.trim() || "unknown";
+  } catch {
+    return null;
+  }
+}
+
+function isLocalProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
+  const res = dockerResourceNames(entry.assistantId);
+
+  const containers: { name: string; containerName: string }[] = [
+    { name: "assistant", containerName: res.assistantContainer },
+    { name: "gateway", containerName: res.gatewayContainer },
+    { name: "credential-executor", containerName: res.cesContainer },
+  ];
+
+  const results = await Promise.all(
+    containers.map(async ({ name, containerName }) => {
+      const state = await getDockerContainerState(containerName);
+      if (!state) {
+        return {
+          name,
+          status: withStatusEmoji("not found"),
+          info: `container ${containerName}`,
+        };
+      }
+      return {
+        name,
+        status: withStatusEmoji(state === "running" ? "running" : state),
+        info: `container ${containerName}`,
+      };
+    }),
+  );
+
+  // Show the file watcher process if the instance was hatched with --watch.
+  const watcherPid =
+    typeof entry.watcherPid === "number" ? entry.watcherPid : null;
+  if (watcherPid !== null) {
+    const alive = isLocalProcessAlive(watcherPid);
+    results.push({
+      name: "file-watcher",
+      status: withStatusEmoji(alive ? "running" : "not running"),
+      info: alive ? `PID ${watcherPid}` : "not detected",
+    });
+  }
+
+  return results;
+}
+
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   const cloud = resolveCloud(entry);
 
@@ -259,6 +328,12 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "docker") {
+    const rows = await getDockerProcesses(entry);
+    printTable(rows);
+    return;
+  }
+
   let output: string;
   try {
     if (cloud === "gcp") {
@@ -357,12 +432,23 @@ async function listAllAssistants(): Promise<void> {
         if (!alive) {
           health = { status: "sleeping", detail: null };
         } else {
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
+        }
+      } else if (a.cloud === "docker") {
+        const res = dockerResourceNames(a.assistantId);
+        const state = await getDockerContainerState(res.assistantContainer);
+        if (!state || state !== "running") {
+          health = { status: "sleeping", detail: null };
+        } else {
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
         }
       } else if (a.cloud === "vellum") {
         health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
       } else {
-        health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+        const token = loadGuardianToken(a.assistantId)?.accessToken;
+        health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
       const infoParts = [a.runtimeUrl];