@vellumai/cli 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/components/DefaultMainScreen.tsx

@@ -10,9 +10,12 @@ 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";
 import { statusEmoji, withStatusEmoji } from "../lib/status-emoji";
 import {
   getTerminalCapabilities,
@@ -62,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;
@@ -176,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,
@@ -184,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(() => "");
@@ -230,13 +290,20 @@ async function pollMessages(
   auth?: Record<string, string>,
 ): Promise<ListMessagesResponse> {
   const params = new URLSearchParams({ conversationKey: assistantId });
-  return runtimeRequest<ListMessagesResponse>(
+  const response = await runtimeRequest<ListMessagesResponse>(
     baseUrl,
     assistantId,
     `/messages?${params.toString()}`,
     undefined,
     auth,
   );
+  return {
+    ...response,
+    messages: response.messages.map((msg) => ({
+      ...msg,
+      content: segmentsToPlainText(msg.textSegments),
+    })),
+  };
 }
 
 async function sendMessage(
@@ -366,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",
@@ -626,6 +698,13 @@ export interface RuntimeMessage {
   id: string;
   role: "user" | "assistant";
   content: string;
+  /**
+   * Ordered text segments from the daemon's history payload, split at
+   * tool_use/surface boundaries. The flat `content` body is derived from
+   * these (see `segmentsToPlainText`); the daemon no longer sends a
+   * redundant flattened `content` field on the wire.
+   */
+  textSegments?: string[];
   timestamp: string;
   toolCalls?: ToolCallInfo[];
   label?: string;
@@ -1969,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",
@@ -1982,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/__tests__/lifecycle-reporter.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+
+import { consoleLifecycleReporter } from "../lifecycle-reporter.js";
+
+describe("consoleLifecycleReporter", () => {
+  const originalDesktopApp = process.env.VELLUM_DESKTOP_APP;
+  let stdoutWriteSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    stdoutWriteSpy = spyOn(process.stdout, "write").mockImplementation(
+      () => true,
+    );
+  });
+
+  afterEach(() => {
+    stdoutWriteSpy.mockRestore();
+    if (originalDesktopApp === undefined) {
+      delete process.env.VELLUM_DESKTOP_APP;
+    } else {
+      process.env.VELLUM_DESKTOP_APP = originalDesktopApp;
+    }
+  });
+
+  test("routes log/warn/error to the matching console methods", () => {
+    const logSpy = spyOn(console, "log").mockImplementation(() => {});
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    consoleLifecycleReporter.log("hello");
+    consoleLifecycleReporter.warn("careful");
+    consoleLifecycleReporter.error("boom");
+
+    expect(logSpy).toHaveBeenCalledWith("hello");
+    expect(warnSpy).toHaveBeenCalledWith("careful");
+    expect(errorSpy).toHaveBeenCalledWith("boom");
+
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("emits the HATCH_PROGRESS stdout contract under VELLUM_DESKTOP_APP", () => {
+    process.env.VELLUM_DESKTOP_APP = "1";
+
+    consoleLifecycleReporter.progress(3, 6, "Starting assistant...");
+
+    expect(stdoutWriteSpy).toHaveBeenCalledWith(
+      `HATCH_PROGRESS:${JSON.stringify({ step: 3, total: 6, label: "Starting assistant..." })}\n`,
+    );
+  });
+
+  test("suppresses progress output when not running under the desktop app", () => {
+    delete process.env.VELLUM_DESKTOP_APP;
+
+    consoleLifecycleReporter.progress(1, 6, "Allocating resources...");
+
+    expect(stdoutWriteSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -10,6 +10,8 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
 import {
   getDefaultPorts,
@@ -18,8 +20,6 @@ import {
   getMultiInstanceDir,
 } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { SEEDS } from "./environments/seeds.js";
-import type { EnvironmentDefinition } from "./environments/types.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -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;
@@ -631,7 +643,7 @@ export async function allocateLocalResources(
 
   // Env-aware bases: non-prod envs sit in their own 1000-port window so
   // running prod and staging assistants side-by-side doesn't collide. See
-  // `environments/seeds.ts:portBlock` for the layout.
+  // the `@vellumai/environments` `portBlock` layout.
   const basePorts = getDefaultPorts(env);
   const daemonPort = await findAvailablePort(basePorts.daemon, reservedPorts);
   const gatewayPort = await findAvailablePort(basePorts.gateway, [