@vellumai/cli 0.8.7 → 0.8.8-dev.202606060043.60454ad

package/src/components/DefaultMainScreen.tsx

@@ -10,7 +10,9 @@ import {
 import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
+import { lookupAssistantByIdentifier } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
+import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
 import { appendHistory, loadHistory } from "../lib/input-history";
 import { tuiLog } from "../lib/tui-log";
 import { segmentsToPlainText } from "../lib/segments-to-plain-text";
@@ -63,6 +65,9 @@ const HELP_COMMANDS = [
 ] as const;
 
 const SEND_TIMEOUT_MS = 5000;
+/** Fresh deadline for a request retried after a mid-session token refresh —
+ *  the original caller signal may have already timed out during the refresh. */
+const RETRY_TIMEOUT_MS = 30_000;
 
 // ── Layout constants ──────────────────────────────────────
 const MAX_TOTAL_WIDTH = 72;
@@ -177,6 +182,44 @@ function friendlyErrorMessage(status: number, body: string): string {
   return `HTTP ${status}: ${body || "Unknown error"}`;
 }
 
+/**
+ * On a 401, refresh a stale PAIRED-assistant guardian token and update the
+ * shared `auth` headers IN PLACE, returning true if the caller should retry.
+ *
+ * Scoped to paired assistants only (a remote assistant on another machine,
+ * `cloud: "paired"`) — the local/docker TUI flow and platform sessions are left
+ * untouched. Also self-gating: skips platform session auth (no `Authorization`
+ * header), ephemeral `--token` overrides (whose bearer won't match the store),
+ * and access-only tokens. Because the TUI threads one shared `auth` object by
+ * reference, mutating it here propagates to every later request and the SSE
+ * reconnect — no callback threading needed.
+ */
+export async function maybeRefreshAuthHeaders(
+  baseUrl: string,
+  assistantId: string,
+  auth?: Record<string, string>,
+): Promise<boolean> {
+  if (!auth) return false;
+  const bearer = auth["Authorization"]?.replace(/^Bearer /, "");
+  if (!bearer) return false;
+
+  // Only paired (remote-on-another-machine) assistants use refreshable pair
+  // tokens; don't perturb the local/docker session flow.
+  const lookup = lookupAssistantByIdentifier(assistantId);
+  if (lookup.status !== "found" || lookup.entry.cloud !== "paired") {
+    return false;
+  }
+
+  const stored = loadGuardianToken(assistantId);
+  if (!stored || stored.accessToken !== bearer || !stored.refreshToken) {
+    return false;
+  }
+  const refreshed = await refreshGuardianToken(baseUrl, assistantId);
+  if (!refreshed?.accessToken) return false;
+  auth["Authorization"] = `Bearer ${refreshed.accessToken}`;
+  return true;
+}
+
 async function runtimeRequest<T>(
   baseUrl: string,
   assistantId: string,
@@ -185,14 +228,30 @@ async function runtimeRequest<T>(
   auth?: Record<string, string>,
 ): Promise<T> {
   const url = `${baseUrl}/v1/assistants/${assistantId}${path}`;
-  const response = await fetch(url, {
-    ...init,
-    headers: {
-      "Content-Type": "application/json",
-      ...auth,
-      ...(init?.headers as Record<string, string> | undefined),
-    },
-  });
+  const doFetch = (signalOverride?: AbortSignal) =>
+    fetch(url, {
+      ...init,
+      // The retry overrides the caller's signal (see below); otherwise use it.
+      signal: signalOverride ?? init?.signal,
+      headers: {
+        "Content-Type": "application/json",
+        ...auth,
+        ...(init?.headers as Record<string, string> | undefined),
+      },
+    });
+
+  let response = await doFetch();
+  // Mid-session token expiry → 401: refresh once and retry (auth headers are
+  // mutated in place by the helper, so the retry carries the new token). The
+  // refresh can take longer than the caller's timeout (lock wait + refresh
+  // fetch), which would already have aborted the original signal — so give the
+  // retry a fresh deadline instead of reusing the (likely-expired) one.
+  if (
+    response.status === 401 &&
+    (await maybeRefreshAuthHeaders(baseUrl, assistantId, auth))
+  ) {
+    response = await doFetch(AbortSignal.timeout(RETRY_TIMEOUT_MS));
+  }
 
   if (!response.ok) {
     const body = await response.text().catch(() => "");
@@ -374,6 +433,11 @@ async function* streamEvents(
   const params = new URLSearchParams({ conversationKey });
   const url = `${baseUrl}/v1/assistants/${assistantId}/events?${params.toString()}`;
   tuiLog.info("sse connect", { url, authHeaders: Object.keys(auth ?? {}) });
+  // NOTE: the SSE connect deliberately does NOT refresh-on-401 — keeping the
+  // stream path simple. After a mid-session token expiry, the REST path
+  // (runtimeRequest) refreshes the shared `auth` on the next request, and the
+  // existing reconnect (ensureConnected on the next message) re-opens the
+  // stream with the refreshed token.
   const response = await fetch(url, {
     headers: {
       Accept: "text/event-stream",
@@ -1984,9 +2048,8 @@ function ChatApp({
         if (!isConnected) return;
 
         try {
-          const res = await fetch(
-            `${runtimeUrl}/v1/assistants/${assistantId}/btw`,
-            {
+          const btwFetch = () =>
+            fetch(`${runtimeUrl}/v1/assistants/${assistantId}/btw`, {
               method: "POST",
               headers: {
                 "Content-Type": "application/json",
@@ -1997,8 +2060,16 @@ function ChatApp({
                 content: question,
               }),
               signal: AbortSignal.timeout(30_000),
-            },
-          );
+            });
+
+          let res = await btwFetch();
+          // Mid-session token expiry → 401: refresh once and retry.
+          if (
+            res.status === 401 &&
+            (await maybeRefreshAuthHeaders(runtimeUrl, assistantId, auth))
+          ) {
+            res = await btwFetch();
+          }
 
           if (!res.ok) throw new Error(`HTTP ${res.status}`);
 

package/src/index.ts

@@ -4,6 +4,8 @@ import cliPkg from "../package.json";
 import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
 import { client } from "./commands/client";
+import { connect } from "./commands/connect";
+import { devices } from "./commands/devices";
 import { env } from "./commands/env";
 import { events } from "./commands/events";
 import { exec } from "./commands/exec";
@@ -13,6 +15,7 @@ import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { logs } from "./commands/logs";
 import { message } from "./commands/message";
+import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { restore } from "./commands/restore";
@@ -25,6 +28,7 @@ import { ssh } from "./commands/ssh";
 import { teleport } from "./commands/teleport";
 import { terminal } from "./commands/terminal";
 import { tunnel } from "./commands/tunnel";
+import { unpair } from "./commands/unpair";
 import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
 import { wake } from "./commands/wake";
@@ -36,6 +40,8 @@ const commands = {
   backup,
   clean,
   client,
+  connect,
+  devices,
   env,
   events,
   exec,
@@ -46,6 +52,7 @@ const commands = {
   logout,
   logs,
   message,
+  pair,
   ps,
   recover,
   restore,
@@ -58,6 +65,7 @@ const commands = {
   teleport,
   terminal,
   tunnel,
+  unpair,
   upgrade,
   use,
   wake,
@@ -73,6 +81,8 @@ function printHelp(): void {
   console.log("  backup   Export a backup of a running assistant");
   console.log("  clean    Kill orphaned vellum processes");
   console.log("  client   Connect to a hatched assistant");
+  console.log("  connect  Import an assistant paired from another machine");
+  console.log("  devices  List or revoke devices paired to a local assistant");
   console.log("  env      Manage the default CLI environment");
   console.log("  events   Stream events from a running assistant");
   console.log("  exec     Execute a command inside an assistant's container");
@@ -83,6 +93,9 @@ function printHelp(): void {
   console.log("  login    Log in to the Vellum platform");
   console.log("  logout   Log out of the Vellum platform");
   console.log("  message  Send a message to a running assistant");
+  console.log(
+    "  pair     Mint a device-scoped token to connect another machine",
+  );
   console.log(
     "  ps       List assistants (or processes for a specific assistant)",
   );
@@ -99,6 +112,9 @@ function printHelp(): void {
   console.log("  teleport Transfer assistant data between environments");
   console.log("  terminal Open a terminal into a managed assistant container");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");
+  console.log(
+    "  unpair   Forget a paired assistant imported from another machine",
+  );
   console.log("  upgrade  Upgrade an assistant to a newer version");
   console.log("  use      Set the active assistant for commands");
   console.log("  wake     Start the assistant and gateway");

package/src/lib/assistant-client.ts

@@ -12,11 +12,9 @@
  * ```
  */
 
-import {
-  resolveAssistant,
-} from "./assistant-config.js";
+import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
-import { loadGuardianToken } from "./guardian-token.js";
+import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -45,7 +43,8 @@ export class AssistantClient {
   readonly runtimeUrl: string;
 
   private readonly _assistantId: string;
-  private readonly token: string | undefined;
+  /** Mutable: a 401 on the guardian path refreshes this in place (see request). */
+  private token: string | undefined;
   /** True when token is a platform session token (X-Session-Token), false for guardian JWT (Authorization: Bearer). */
   private readonly isSessionAuth: boolean;
   private readonly orgId: string | undefined;
@@ -176,45 +175,67 @@ export class AssistantClient {
       ? `?${new URLSearchParams(opts.query).toString()}`
       : "";
     const url = `${this.runtimeUrl}/v1/assistants/${this._assistantId}${urlPath}${qs}`;
-
-    const headers: Record<string, string> = { ...opts?.headers };
-    if (this.token) {
-      if (this.isSessionAuth) {
-        headers["X-Session-Token"] ??= this.token;
-      } else {
-        headers["Authorization"] ??= `Bearer ${this.token}`;
-      }
-    }
-    if (this.orgId) {
-      headers["Vellum-Organization-Id"] ??= this.orgId;
-    }
-    if (body !== undefined) {
-      headers["Content-Type"] = "application/json";
-    }
-
     const jsonBody = body !== undefined ? JSON.stringify(body) : undefined;
 
-    if (opts?.signal) {
+    // Headers are built per-attempt so a refreshed token is picked up on retry.
+    const buildHeaders = (): Record<string, string> => {
+      const headers: Record<string, string> = { ...opts?.headers };
+      if (this.token) {
+        if (this.isSessionAuth) {
+          headers["X-Session-Token"] ??= this.token;
+        } else {
+          headers["Authorization"] ??= `Bearer ${this.token}`;
+        }
+      }
+      if (this.orgId) {
+        headers["Vellum-Organization-Id"] ??= this.orgId;
+      }
+      if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+      }
+      return headers;
+    };
+
+    const doFetch = (): Promise<Response> => {
+      const headers = buildHeaders();
+      if (opts?.signal) {
+        return fetch(url, {
+          method,
+          headers,
+          body: jsonBody,
+          signal: opts.signal,
+        });
+      }
+      const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
       return fetch(url, {
-        method,
-        headers,
-        body: jsonBody,
-        signal: opts.signal,
-      });
-    }
-
-    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      return await fetch(url, {
         method,
         headers,
         body: jsonBody,
         signal: controller.signal,
-      });
-    } finally {
-      clearTimeout(timeoutId);
+      }).finally(() => clearTimeout(timeoutId));
+    };
+
+    const response = await doFetch();
+
+    // Reactive auto-refresh: a paired/local guardian access token that has
+    // expired comes back 401. Refresh it once via the stored refresh credential
+    // and retry. Self-gating — refreshGuardianToken returns null unless a usable
+    // refresh token is stored, so ephemeral (`--token`) and access-only sessions
+    // just see the original 401. The platform session-auth path is never
+    // refreshed here (its token is managed by the Vellum platform).
+    if (response.status === 401 && !this.isSessionAuth) {
+      const refreshed = await refreshGuardianToken(
+        this.runtimeUrl,
+        this._assistantId,
+      );
+      if (refreshed?.accessToken) {
+        this.token = refreshed.accessToken;
+        return doFetch();
+      }
     }
+
+    return response;
   }
 }

package/src/lib/assistant-config.ts

@@ -76,7 +76,19 @@ export interface AssistantEntry {
    *  Avoids mDNS resolution issues when the machine checks its own gateway. */
   localUrl?: string;
   bearerToken?: string;
+  /** Deployment topology / how the assistant is reached. Known values:
+   *  `"local"` (on-machine daemon), `"docker"` (local container),
+   *  `"apple-container"` (macOS-app-managed container), `"vellum"`
+   *  (platform-managed, uses the X-Session-Token auth path), `"gcp"` / `"aws"`
+   *  / `"custom"` (remote, SSH-managed), and `"paired"` (a remote assistant
+   *  paired from another machine — reached via a bearer guardian token at
+   *  `runtimeUrl`; has no local process, container, or `resources`).
+   *  Kept as a free `string` (not a union) for forward-compatibility. */
   cloud: string;
+  /** True when this entry was registered via `vellum connect import` (a remote
+   *  pairing). Set alongside `cloud: "paired"`; also backs the re-import /
+   *  overwrite guard in connect import. */
+  paired?: boolean;
   instanceId?: string;
   namespace?: string;
   project?: string;

package/src/lib/cloudflare-tunnel.ts

@@ -0,0 +1,276 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { GATEWAY_PORT } from "./constants.js";
+
+// ── Workspace config helpers (mirrors the pattern in ngrok.ts) ───────────────
+
+function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
+}
+
+function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+function clearIngressUrl(workspaceDir: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+// ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
+
+const CLOUDFLARED_TIMEOUT_MS = 30_000;
+
+// Quick-tunnel hostnames follow the pattern <word>-<word>-<word>.trycloudflare.com
+const QUICK_TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+/**
+ * Check whether cloudflared is installed and on PATH.
+ * Returns the version string if found, null otherwise.
+ */
+export function getCloudflareTunnelVersion(): string | null {
+  try {
+    const output = execFileSync("cloudflared", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn a cloudflared quick-tunnel process forwarding HTTP traffic to
+ * `targetPort`.  The child process writes its public URL to stderr during
+ * startup — use {@link waitForCloudflareTunnelUrl} to extract it.
+ */
+export function startCloudflareTunnelProcess(targetPort: number): ChildProcess {
+  return spawn(
+    "cloudflared",
+    ["tunnel", "--url", `http://localhost:${targetPort}`, "--no-autoupdate"],
+    // Keep stdio as pipes so we can parse the URL from output.
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+}
+
+/**
+ * Listen to a running cloudflared process's stdout/stderr and resolve with
+ * the public quick-tunnel URL once cloudflared prints it.
+ *
+ * cloudflared emits a line containing the trycloudflare.com URL during
+ * startup — typically within 5–15 seconds on a normal internet connection.
+ *
+ * Rejects when:
+ * - The URL does not appear within `timeoutMs`.
+ * - The child process exits before the URL is found.
+ */
+export function waitForCloudflareTunnelUrl(
+  child: ChildProcess,
+  timeoutMs: number = CLOUDFLARED_TIMEOUT_MS,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `cloudflared tunnel URL did not appear within ${timeoutMs / 1000}s. ` +
+            `Ensure cloudflared is working: try running 'cloudflared tunnel --url http://localhost:8080' manually.`,
+        ),
+      );
+    }, timeoutMs);
+
+    let resolved = false;
+
+    function scanLine(line: string): void {
+      if (resolved) return;
+      const match = QUICK_TUNNEL_URL_RE.exec(line);
+      if (match) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve(match[0]);
+      }
+    }
+
+    // Buffer incomplete lines across chunks
+    let stdoutBuf = "";
+    let stderrBuf = "";
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString();
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      clearTimeout(timer);
+      reject(
+        new Error(
+          `cloudflared exited with code ${code ?? "unknown"} before the tunnel URL appeared.`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Run the cloudflared quick-tunnel workflow:
+ * 1. Verify cloudflared is installed.
+ * 2. Start a quick tunnel pointing at the gateway port.
+ * 3. Parse the public URL from cloudflared output.
+ * 4. Persist the URL to the workspace config as the ingress base URL.
+ * 5. Block until the process exits or the user presses Ctrl+C.
+ * 6. Clear the ingress URL from config on exit.
+ *
+ * No Cloudflare account is required — quick tunnels are free and ephemeral.
+ */
+export interface RunCloudflareTunnelOptions {
+  /** Gateway port to forward. Defaults to the global GATEWAY_PORT. */
+  port?: number;
+  /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
+  workspaceDir?: string;
+}
+
+export async function runCloudflareTunnel(
+  opts: RunCloudflareTunnelOptions = {},
+): Promise<void> {
+  const version = getCloudflareTunnelVersion();
+  if (!version) {
+    console.error("Error: cloudflared is not installed.");
+    console.error("");
+    console.error("Install cloudflared:");
+    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
+    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
+    console.error(
+      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+    );
+    console.error("");
+    console.error("No Cloudflare account is required for quick tunnels.");
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+
+  const port = opts.port ?? GATEWAY_PORT;
+  const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
+
+  console.log(`Starting cloudflared quick tunnel to localhost:${port}...`);
+  console.log("No Cloudflare account required — quick tunnels are free.");
+  console.log("");
+
+  let publicUrl: string | undefined;
+  const child = startCloudflareTunnelProcess(port);
+
+  const cleanup = (): void => {
+    if (!child.killed) child.kill("SIGTERM");
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl(workspaceDir);
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  child.on("error", (err: Error) => {
+    console.error(`cloudflared process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    // Always clear the saved ingress URL when the tunnel process ends so
+    // webhook integrations don't keep hitting a dead endpoint.
+    if (publicUrl !== undefined) {
+      clearIngressUrl(workspaceDir);
+    }
+    if (code !== null && code !== 0) {
+      console.error(`\ncloudflared exited with code ${code}.`);
+      process.exit(1);
+    }
+  });
+
+  // Forward cloudflared output to the console so the user can see startup
+  // progress and any authentication errors.
+  child.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+  child.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForCloudflareTunnelUrl(child);
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+  console.log("");
+
+  saveIngressUrl(workspaceDir, publicUrl);
+  console.log("Ingress URL saved to config.");
+  console.log("");
+  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
+
+  // Keep running until cloudflared exits (e.g., network error or user Ctrl+C)
+  await new Promise<void>((resolve) => {
+    child.on("exit", () => resolve());
+  });
+}