@vellumai/cli 0.4.5 → 0.4.7

package/package.json

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

package/src/adapters/install.sh

@@ -24,11 +24,58 @@ ensure_git() {
 
     info "Installing git..."
     if [ "$(uname -s)" = "Darwin" ]; then
-        if command -v brew >/dev/null 2>&1; then
-            brew install git
-        else
-            error "git is required. Install Homebrew (https://brew.sh) then run: brew install git"
-            exit 1
+        # On macOS, the standard way to get git is via Xcode Command Line Tools.
+        # Try installing CLT first before falling back to Homebrew.
+        if ! xcode-select -p >/dev/null 2>&1; then
+            info "Installing Xcode Command Line Tools (includes git)..."
+
+            # Use softwareupdate to install CLT non-interactively instead of
+            # xcode-select --install which opens a GUI dialog requiring manual
+            # confirmation.
+            touch /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
+            local clt_package
+            clt_package=$(softwareupdate -l 2>/dev/null \
+                | grep -o '.*Command Line Tools.*' \
+                | grep -v "^\*" \
+                | sed 's/^ *//' \
+                | sort -V \
+                | tail -1)
+
+            if [ -n "$clt_package" ]; then
+                info "Found package: $clt_package"
+                softwareupdate -i "$clt_package" --verbose 2>&1 | while IFS= read -r line; do
+                    printf "  %s\n" "$line"
+                done
+            else
+                # Fallback: if softwareupdate can't find the package, try
+                # xcode-select --install and wait for user interaction.
+                info "Could not find CLT package via softwareupdate, falling back to xcode-select..."
+                xcode-select --install 2>/dev/null || true
+                info "Please follow the on-screen dialog to install. Waiting..."
+                local waited=0
+                while ! xcode-select -p >/dev/null 2>&1; do
+                    sleep 5
+                    waited=$((waited + 5))
+                    if [ "$waited" -ge 600 ]; then
+                        error "Timed out waiting for Xcode Command Line Tools. Please install manually and re-run."
+                        exit 1
+                    fi
+                done
+            fi
+
+            rm -f /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
+            hash -r 2>/dev/null || true
+        fi
+
+        # If git still doesn't work after CLT, try Homebrew as a fallback.
+        if ! git --version >/dev/null 2>&1; then
+            hash -r 2>/dev/null || true
+            if command -v brew >/dev/null 2>&1; then
+                brew install git
+            else
+                error "git is still not available. Please install manually: xcode-select --install"
+                exit 1
+            fi
         fi
     elif command -v apt-get >/dev/null 2>&1; then
         sudo apt-get update -qq && sudo apt-get install -y -qq git

package/src/commands/hatch.ts

@@ -1,8 +1,9 @@
 import { createHash, randomBytes, randomUUID } from "crypto";
-import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from "fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from "fs";
 import { homedir, hostname, userInfo } from "os";
 import { join } from "path";
 
+import QRCode from "qrcode";
 import qrcode from "qrcode-terminal";
 
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
@@ -508,7 +509,7 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
     const pairingRequestId = randomUUID();
     const pairingSecret = randomBytes(32).toString("hex");
 
-    const registerRes = await fetch(`${runtimeUrl}/v1/pairing/register`, {
+    const registerRes = await fetch(`${runtimeUrl}/pairing/register`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -539,6 +540,20 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
       });
     });
 
+    // Save QR code as PNG to a well-known location so it can be retrieved
+    // (e.g. via SCP) for pairing through the Desktop app.
+    const qrDir = join(homedir(), ".vellum", "pairing-qr");
+    mkdirSync(qrDir, { recursive: true });
+    const qrPngPath = join(qrDir, "initial.png");
+    try {
+      const pngBuffer = await QRCode.toBuffer(payload, { type: "png", width: 512 });
+      writeFileSync(qrPngPath, pngBuffer);
+      console.log(`QR code PNG saved to ${qrPngPath}\n`);
+    } catch (pngErr) {
+      const pngReason = pngErr instanceof Error ? pngErr.message : String(pngErr);
+      console.warn(`\u26A0 Could not save QR code PNG: ${pngReason}\n`);
+    }
+
     console.log("Scan this QR code with the Vellum iOS app to pair:\n");
     console.log(qrString);
     console.log("This pairing request expires in 5 minutes.");

package/src/components/DefaultMainScreen.tsx

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { createHash, randomBytes, randomUUID } from "crypto";
-import { hostname, userInfo } from "os";
+import { hostname, platform, userInfo } from "os";
 import { basename } from "path";
 import qrcode from "qrcode-terminal";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement } from "react";
@@ -135,6 +135,7 @@ async function runtimeRequest<T>(
   path: string,
   init?: RequestInit,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<T> {
   const url = `${baseUrl}/v1/assistants/${assistantId}${path}`;
   const response = await fetch(url, {
@@ -142,6 +143,7 @@ async function runtimeRequest<T>(
     headers: {
       "Content-Type": "application/json",
       ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+      ...(actorToken ? { "X-Actor-Token": actorToken } : {}),
       ...(init?.headers as Record<string, string> | undefined),
     },
   });
@@ -177,10 +179,47 @@ async function checkHealthRuntime(baseUrl: string): Promise<HealthResponse> {
   return response.json() as Promise<HealthResponse>;
 }
 
+async function bootstrapActorToken(baseUrl: string, bearerToken?: string): Promise<string> {
+  if (!bearerToken) {
+    throw new Error("Missing bearer token; cannot bootstrap actor identity");
+  }
+
+  const deviceId = `vellum-cli:${platform()}:${hostname()}:${userInfo().username}`;
+  const url = `${baseUrl}/v1/integrations/guardian/vellum/bootstrap`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify({ platform: "cli", deviceId }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status}: ${body || response.statusText}`);
+  }
+
+  const json: unknown = await response.json();
+
+  if (typeof json !== "object" || json === null) {
+    throw new Error("Invalid bootstrap response from gateway/runtime");
+  }
+
+  const actorToken = (json as Record<string, unknown>).actorToken;
+  if (typeof actorToken !== "string" || actorToken.length === 0) {
+    throw new Error("Invalid bootstrap response from gateway/runtime");
+  }
+
+  return actorToken;
+}
+
 async function pollMessages(
   baseUrl: string,
   assistantId: string,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<ListMessagesResponse> {
   const params = new URLSearchParams({ conversationKey: assistantId });
   return runtimeRequest<ListMessagesResponse>(
@@ -189,6 +228,7 @@ async function pollMessages(
     `/messages?${params.toString()}`,
     undefined,
     bearerToken,
+    actorToken,
   );
 }
 
@@ -198,6 +238,7 @@ async function sendMessage(
   content: string,
   signal?: AbortSignal,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<SendMessageResponse> {
   return runtimeRequest<SendMessageResponse>(
     baseUrl,
@@ -209,6 +250,7 @@ async function sendMessage(
       signal,
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -218,6 +260,7 @@ async function submitDecision(
   requestId: string,
   decision: "allow" | "deny",
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<SubmitDecisionResponse> {
   return runtimeRequest<SubmitDecisionResponse>(
     baseUrl,
@@ -228,6 +271,7 @@ async function submitDecision(
       body: JSON.stringify({ requestId, decision }),
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -239,6 +283,7 @@ async function addTrustRule(
   scope: string,
   decision: "allow" | "deny",
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<AddTrustRuleResponse> {
   return runtimeRequest<AddTrustRuleResponse>(
     baseUrl,
@@ -249,6 +294,7 @@ async function addTrustRule(
       body: JSON.stringify({ requestId, pattern, scope, decision }),
     },
     bearerToken,
+    actorToken,
   );
 }
 
@@ -256,6 +302,7 @@ async function pollPendingInteractions(
   baseUrl: string,
   assistantId: string,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<PendingInteractionsResponse> {
   const params = new URLSearchParams({ conversationKey: assistantId });
   return runtimeRequest<PendingInteractionsResponse>(
@@ -264,6 +311,7 @@ async function pollPendingInteractions(
     `/pending-interactions?${params.toString()}`,
     undefined,
     bearerToken,
+    actorToken,
   );
 }
 
@@ -301,6 +349,7 @@ async function handleConfirmationPrompt(
   confirmation: PendingConfirmation,
   chatApp: ChatAppHandle,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const preview = formatConfirmationPreview(confirmation.toolName, confirmation.input);
   const allowlistOptions = confirmation.allowlistOptions ?? [];
@@ -320,7 +369,7 @@ async function handleConfirmationPrompt(
   const index = await chatApp.showSelection("Tool Approval", options);
 
   if (index === 0) {
-    await submitDecision(baseUrl, assistantId, requestId, "allow", bearerToken);
+    await submitDecision(baseUrl, assistantId, requestId, "allow", bearerToken, actorToken);
     chatApp.addStatus("\u2714 Allowed", "green");
     return;
   }
@@ -333,6 +382,7 @@ async function handleConfirmationPrompt(
       chatApp,
       "always_allow",
       bearerToken,
+      actorToken,
     );
     return;
   }
@@ -345,11 +395,12 @@ async function handleConfirmationPrompt(
       chatApp,
       "always_deny",
       bearerToken,
+      actorToken,
     );
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -361,6 +412,7 @@ async function handlePatternSelection(
   chatApp: ChatAppHandle,
   trustDecision: TrustDecision,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const allowlistOptions = confirmation.allowlistOptions ?? [];
   const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
@@ -379,11 +431,12 @@ async function handlePatternSelection(
       selectedPattern,
       trustDecision,
       bearerToken,
+      actorToken,
     );
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -396,6 +449,7 @@ async function handleScopeSelection(
   selectedPattern: string,
   trustDecision: TrustDecision,
   bearerToken?: string,
+  actorToken?: string,
 ): Promise<void> {
   const scopeOptions = confirmation.scopeOptions ?? [];
   const label = trustDecision === "always_deny" ? "Denylist" : "Allowlist";
@@ -413,6 +467,7 @@ async function handleScopeSelection(
       scopeOptions[index].scope,
       ruleDecision,
       bearerToken,
+      actorToken,
     );
     await submitDecision(
       baseUrl,
@@ -420,6 +475,7 @@ async function handleScopeSelection(
       requestId,
       ruleDecision === "deny" ? "deny" : "allow",
       bearerToken,
+      actorToken,
     );
     const ruleLabel = trustDecision === "always_deny" ? "Denylisted" : "Allowlisted";
     const ruleColor = trustDecision === "always_deny" ? "yellow" : "green";
@@ -430,7 +486,7 @@ async function handleScopeSelection(
     return;
   }
 
-  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken);
+  await submitDecision(baseUrl, assistantId, requestId, "deny", bearerToken, actorToken);
   chatApp.addStatus("\u2718 Denied", "yellow");
 }
 
@@ -1025,6 +1081,7 @@ function ChatApp({
   const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const doctorSessionIdRef = useRef(randomUUID());
   const handleRef_ = useRef<ChatAppHandle | null>(null);
+  const actorTokenRef = useRef<string | undefined>(undefined);
 
   const { stdout } = useStdout();
   const terminalRows = stdout.rows || DEFAULT_TERMINAL_ROWS;
@@ -1250,6 +1307,9 @@ function ChatApp({
 
     try {
       const health = await checkHealthRuntime(runtimeUrl);
+      if (!actorTokenRef.current) {
+        actorTokenRef.current = await bootstrapActorToken(runtimeUrl, bearerToken);
+      }
       h.hideSpinner();
       h.updateHealthStatus(health.status);
       if (health.status === "healthy" || health.status === "ok") {
@@ -1265,7 +1325,12 @@ function ChatApp({
       h.showSpinner("Loading conversation history...");
 
       try {
-        const historyResponse = await pollMessages(runtimeUrl, assistantId, bearerToken);
+        const historyResponse = await pollMessages(
+          runtimeUrl,
+          assistantId,
+          bearerToken,
+          actorTokenRef.current,
+        );
         h.hideSpinner();
         if (historyResponse.messages.length > 0) {
           for (const msg of historyResponse.messages) {
@@ -1279,7 +1344,12 @@ function ChatApp({
 
       pollTimerRef.current = setInterval(async () => {
         try {
-          const response = await pollMessages(runtimeUrl, assistantId, bearerToken);
+          const response = await pollMessages(
+            runtimeUrl,
+            assistantId,
+            bearerToken,
+            actorTokenRef.current,
+          );
           for (const msg of response.messages) {
             if (!seenMessageIdsRef.current.has(msg.id)) {
               seenMessageIdsRef.current.add(msg.id);
@@ -1296,11 +1366,12 @@ function ChatApp({
       connectedRef.current = true;
       connectingRef.current = false;
       return true;
-    } catch {
+    } catch (err) {
       h.hideSpinner();
       connectingRef.current = false;
       h.updateHealthStatus("unreachable");
-      h.addStatus(`${statusEmoji("unreachable")} Failed to connect: Timeout`, "red");
+      const msg = err instanceof Error ? err.message : String(err);
+      h.addStatus(`${statusEmoji("unreachable")} Failed to connect: ${msg}`, "red");
       return false;
     }
   }, [runtimeUrl, assistantId, bearerToken]);
@@ -1347,8 +1418,8 @@ function ChatApp({
           const pairingSecret = randomBytes(32).toString("hex");
           const gatewayUrl = runtimeUrl;
 
-          // Call /v1/pairing/register directly (not under /v1/assistants/:id/)
-          const registerUrl = `${runtimeUrl}/v1/pairing/register`;
+          // Call /pairing/register on the gateway (dedicated pairing proxy route)
+          const registerUrl = `${runtimeUrl}/pairing/register`;
           const registerRes = await fetch(registerUrl, {
             method: "POST",
             headers: {
@@ -1561,6 +1632,7 @@ function ChatApp({
             trimmed,
             controller.signal,
             bearerToken,
+            actorTokenRef.current,
           );
           clearTimeout(timeoutId);
           if (!sendResult.accepted) {
@@ -1586,7 +1658,12 @@ function ChatApp({
 
           // Check for pending confirmations/secrets
           try {
-            const pending = await pollPendingInteractions(runtimeUrl, assistantId, bearerToken);
+            const pending = await pollPendingInteractions(
+              runtimeUrl,
+              assistantId,
+              bearerToken,
+              actorTokenRef.current,
+            );
 
             if (pending.pendingConfirmation) {
               h.hideSpinner();
@@ -1597,6 +1674,7 @@ function ChatApp({
                 pending.pendingConfirmation,
                 h,
                 bearerToken,
+                actorTokenRef.current,
               );
               h.showSpinner("Working...");
               continue;
@@ -1615,6 +1693,7 @@ function ChatApp({
                     body: JSON.stringify({ requestId: secretRequestId, value, delivery }),
                   },
                   bearerToken,
+                  actorTokenRef.current,
                 );
               });
               h.showSpinner("Working...");
@@ -1626,7 +1705,12 @@ function ChatApp({
 
           // Poll for new messages to detect completion
           try {
-            const pollResult = await pollMessages(runtimeUrl, assistantId, bearerToken);
+            const pollResult = await pollMessages(
+              runtimeUrl,
+              assistantId,
+              bearerToken,
+              actorTokenRef.current,
+            );
             for (const msg of pollResult.messages) {
               if (!seenMessageIdsRef.current.has(msg.id)) {
                 seenMessageIdsRef.current.add(msg.id);

package/src/lib/local.ts

@@ -1,5 +1,5 @@
 import { execFileSync, spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
 import { createConnection } from "net";
 import { homedir } from "os";
@@ -11,6 +11,33 @@ import { stopProcessByPidFile } from "./process.js";
 
 const _require = createRequire(import.meta.url);
 
+/** Returns the XDG-compatible log directory for Vellum hatch logs. */
+function getHatchLogDir(): string {
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "vellum", "logs");
+}
+
+/** Open (or create) a log file in append mode, returning the file descriptor.
+ *  Creates the parent directory if it doesn't exist. Returns "ignore" if the
+ *  directory or file cannot be created (permissions, read-only filesystem, etc.)
+ *  so that spawn falls back to discarding output instead of aborting startup. */
+function openHatchLogFile(name: string): number | "ignore" {
+  try {
+    const dir = getHatchLogDir();
+    mkdirSync(dir, { recursive: true });
+    return openSync(join(dir, name), "a");
+  } catch {
+    return "ignore";
+  }
+}
+
+/** Close a file descriptor returned by openHatchLogFile (no-op for "ignore"). */
+function closeHatchLogFile(fd: number | "ignore"): void {
+  if (typeof fd === "number") {
+    try { closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
 function isAssistantSourceDir(dir: string): boolean {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts"))) return false;
@@ -376,18 +403,25 @@ export async function startLocalDaemon(): Promise<void> {
         }
       }
 
-      const child = spawn(daemonBinary, [], {
-        cwd: dirname(daemonBinary),
-        detached: true,
-        stdio: "ignore",
-        env: daemonEnv,
-      });
-      child.unref();
+      const daemonLogFd = openHatchLogFile("daemon.log");
+      let daemonPid: number | undefined;
+      try {
+        const child = spawn(daemonBinary, [], {
+          cwd: dirname(daemonBinary),
+          detached: true,
+          stdio: ["ignore", daemonLogFd, daemonLogFd],
+          env: daemonEnv,
+        });
+        child.unref();
+        daemonPid = child.pid;
+      } finally {
+        closeHatchLogFile(daemonLogFd);
+      }
 
       // Write PID file immediately so the health monitor can find the process
       // and concurrent hatch() calls see it as alive.
-      if (child.pid) {
-        writeFileSync(pidFile, String(child.pid), "utf-8");
+      if (daemonPid) {
+        writeFileSync(pidFile, String(daemonPid), "utf-8");
       }
     }
 
@@ -534,20 +568,30 @@ export async function startGateway(assistantId?: string): Promise<string> {
       );
     }
 
-    gateway = spawn(gatewayBinary, [], {
-      detached: true,
-      stdio: "ignore",
-      env: gatewayEnv,
-    });
+    const gatewayLogFd = openHatchLogFile("gateway.log");
+    try {
+      gateway = spawn(gatewayBinary, [], {
+        detached: true,
+        stdio: ["ignore", gatewayLogFd, gatewayLogFd],
+        env: gatewayEnv,
+      });
+    } finally {
+      closeHatchLogFile(gatewayLogFd);
+    }
   } else {
     // Source tree / bunx: resolve the gateway source directory and run via bun.
     const gatewayDir = resolveGatewayDir();
-    gateway = spawn("bun", ["run", "src/index.ts"], {
-      cwd: gatewayDir,
-      detached: true,
-      stdio: "ignore",
-      env: gatewayEnv,
-    });
+    const gwLogFd = openHatchLogFile("gateway.log");
+    try {
+      gateway = spawn("bun", ["run", "src/index.ts"], {
+        cwd: gatewayDir,
+        detached: true,
+        stdio: ["ignore", gwLogFd, gwLogFd],
+        env: gatewayEnv,
+      });
+    } finally {
+      closeHatchLogFile(gwLogFd);
+    }
   }
 
   gateway.unref();