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

package/src/commands/pair.ts

@@ -0,0 +1,222 @@
+/**
+ * `vellum pair [assistant] [--label <name>]`
+ *
+ * Mint a device-scoped token for another machine and print a pairing bundle.
+ * Runs on the machine hosting the assistant: it calls the local gateway's
+ * loopback-only `POST /v1/pair` (cli interface) with a freshly generated
+ * deviceId, then prints the credentials to hand to a second device.
+ *
+ * Each invocation generates a NEW random deviceId, so each pairing is an
+ * independent, separately-revocable device (see `vellum unpair`, forthcoming).
+ */
+
+import { nanoid } from "nanoid";
+
+import { extractFlag } from "../lib/arg-utils.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import {
+  formatAssistantLookupError,
+  lookupAssistantByIdentifier,
+  resolveAssistant,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+import {
+  CLI_INTERFACE_ID,
+  getClientRegistrationHeaders,
+} from "../lib/client-identity.js";
+import { GATEWAY_PORT } from "../lib/constants.js";
+import { getLocalLanIPv4 } from "../lib/local.js";
+
+function isLoopbackHost(url: string): boolean {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host === "localhost" || host === "::1" || host.startsWith("127.");
+  } catch {
+    return false;
+  }
+}
+
+function printUsage(): void {
+  console.log(`vellum pair - Mint a device-scoped token for another machine
+
+USAGE:
+    vellum pair [assistant] [options]
+
+ARGUMENTS:
+    [assistant]    Instance name (default: active assistant)
+
+OPTIONS:
+    --url <url>      Reachable gateway URL to advertise in the bundle
+                    (default: the assistant's runtime URL, not loopback)
+    --label <name>   Human label for this pairing (echoed in the output)
+    --json           Output the raw bundle as JSON
+
+EXAMPLES:
+    vellum pair
+    vellum pair "My Assistant" --label "phone"
+    vellum pair --url https://abc123.ngrok.app
+    vellum pair --json
+`);
+}
+
+interface PairResponse {
+  token: string;
+  expiresAt: string;
+  guardianId: string;
+  assistantId: string;
+  // Present on the device-bound path: a long-lived refresh credential the
+  // imported client uses to renew its access token (ISO-8601 strings).
+  refreshToken?: string;
+  refreshTokenExpiresAt?: string;
+  refreshAfter?: string;
+}
+
+export async function pair(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const jsonOutput = rawArgs.includes("--json");
+  let args = rawArgs.filter((a) => a !== "--json");
+
+  const [label, afterLabel] = extractFlag(args, "--label");
+  const [urlOverride, afterUrl] = extractFlag(afterLabel, "--url");
+  args = afterUrl;
+
+  // Resolve the target. An explicit argument is matched by display name OR id
+  // (with the standard ambiguity error); no argument falls back to the active
+  // assistant. Join positional tokens so multi-word display names work even
+  // unquoted (e.g. `vellum pair My Assistant`).
+  const assistantName = parseAssistantTargetArg(args);
+  let entry: AssistantEntry | null;
+  if (assistantName) {
+    const result = lookupAssistantByIdentifier(assistantName);
+    if (result.status !== "found") {
+      console.error(formatAssistantLookupError(assistantName, result));
+      process.exit(1);
+    }
+    entry = result.entry;
+  } else {
+    entry = resolveAssistant();
+    if (!entry) {
+      console.error("No assistant instance found. Run `vellum hatch` first.");
+      process.exit(1);
+    }
+  }
+
+  // Mint over loopback (localUrl avoids mDNS for same-machine calls), but
+  // advertise a REACHABLE url in the bundle — the loopback url would point the
+  // other machine at its own localhost. Prefer an explicit --url, then the
+  // runtime (LAN/tunnel) url.
+  const mintUrl = (
+    entry.localUrl ||
+    entry.runtimeUrl ||
+    `http://127.0.0.1:${GATEWAY_PORT}`
+  ).replace(/\/+$/, "");
+  const advertisedUrl = (urlOverride || entry.runtimeUrl || mintUrl).replace(
+    /\/+$/,
+    "",
+  );
+
+  // A local hatch's runtimeUrl is itself loopback (http://localhost:<port>),
+  // so without an explicit --url the bundle would point the other machine at
+  // its own localhost. Refuse to advertise a loopback URL unless the user
+  // explicitly passed one. (An explicit --url is trusted as-is.)
+  if (!urlOverride && isLoopbackHost(advertisedUrl)) {
+    const lan = getLocalLanIPv4();
+    // Use THIS assistant's gateway port (not the global default) — second
+    // local instances listen on a different port.
+    let port = String(GATEWAY_PORT);
+    try {
+      port = new URL(mintUrl).port || port;
+    } catch {
+      /* keep default */
+    }
+    const suggestion = lan
+      ? `http://${lan}:${port}`
+      : `http://<this-machine-ip>:${port}`;
+    console.error(
+      "Error: this assistant has no reachable gateway URL — its address is " +
+        `loopback (${advertisedUrl}), which the other machine can't connect to.`,
+    );
+    console.error(
+      `Re-run with a reachable URL, e.g.:\n  vellum pair --url ${suggestion}`,
+    );
+    process.exit(1);
+  }
+
+  // Fresh per-pairing device identity — each `vellum pair` is independently
+  // revocable.
+  const deviceId = nanoid();
+
+  let response: Response;
+  try {
+    response = await fetch(`${mintUrl}/v1/pair`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...getClientRegistrationHeaders(CLI_INTERFACE_ID),
+      },
+      body: JSON.stringify({ deviceId, platform: "cli" }),
+    });
+  } catch (err) {
+    console.error(
+      `Error: could not reach the gateway at ${mintUrl} ` +
+        `(${err instanceof Error ? err.message : String(err)}).`,
+    );
+    console.error("Is the assistant running? Try `vellum wake`.");
+    process.exit(1);
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    console.error(
+      `Error: HTTP ${response.status}: ${body || response.statusText}`,
+    );
+    process.exit(1);
+  }
+
+  const result = (await response.json()) as PairResponse;
+
+  // Single-line, copy-pasteable blob for the consume side (`vellum connect
+  // import <blob>`, forthcoming).
+  const bundle = {
+    gatewayUrl: advertisedUrl,
+    assistantId: result.assistantId,
+    token: result.token,
+    deviceId,
+    // Carry the refresh credential through when the gateway issued one, so the
+    // imported client can renew without re-pairing. Omitted entirely for an
+    // access-only (older gateway) response so the bundle stays clean.
+    ...(result.refreshToken
+      ? {
+          refreshToken: result.refreshToken,
+          refreshTokenExpiresAt: result.refreshTokenExpiresAt,
+          refreshAfter: result.refreshAfter,
+        }
+      : {}),
+  };
+  const blob = Buffer.from(JSON.stringify(bundle)).toString("base64");
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({ ...bundle, expiresAt: result.expiresAt }, null, 2),
+    );
+    return;
+  }
+
+  const displayName = entry.name || entry.assistantName || entry.assistantId;
+  console.log(`Paired ${label ? `"${label}" ` : ""}with ${displayName}.`);
+  console.log("");
+  console.log(`  Gateway:   ${advertisedUrl}`);
+  console.log(`  Assistant: ${result.assistantId}`);
+  console.log(`  Expires:   ${result.expiresAt}`);
+  console.log("");
+  console.log("Hand this to the other machine (keep it secret):");
+  console.log("");
+  console.log(`  ${blob}`);
+  console.log("");
+}

package/src/commands/ps.ts

@@ -444,6 +444,22 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "paired") {
+    // A remote assistant paired from another machine: no local process to
+    // list — probe the remote gateway's health over the bearer token instead.
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    const health = await checkHealth(entry.runtimeUrl, token);
+    const rows: TableRow[] = [
+      {
+        name: "gateway",
+        status: withStatusEmoji(health.status),
+        info: entry.runtimeUrl + (health.detail ? ` | ${health.detail}` : ""),
+      },
+    ];
+    printTable(rows);
+    return;
+  }
+
   let output: string;
   try {
     if (cloud === "gcp") {

package/src/commands/retire.ts

@@ -13,6 +13,10 @@ import {
   type AssistantEntry,
 } from "../lib/assistant-config.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import {
+  canPromptForConfirmation,
+  confirmAction,
+} from "../lib/confirm-action.js";
 import { getConfigDir } from "../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
@@ -152,51 +156,6 @@ function printRetireTarget(entry: AssistantEntry, cloud: string): void {
   console.log("");
 }
 
-function canPromptForRetireConfirmation(): boolean {
-  return (
-    process.stdin.isTTY === true &&
-    process.stdout.isTTY === true &&
-    typeof process.stdin.setRawMode === "function"
-  );
-}
-
-async function confirmRetireInteractive(): Promise<boolean> {
-  const stdin = process.stdin;
-  const stdout = process.stdout;
-  const wasRaw = stdin.isRaw === true;
-  const wasPaused = stdin.isPaused();
-
-  stdout.write("Press Enter to retire, or Esc/q to cancel: ");
-  stdin.setRawMode(true);
-  stdin.resume();
-
-  return await new Promise<boolean>((resolve) => {
-    const cleanup = () => {
-      stdin.off("data", onData);
-      stdin.setRawMode(wasRaw);
-      if (wasPaused) {
-        stdin.pause();
-      }
-      stdout.write("\n");
-    };
-
-    const onData = (chunk: Buffer) => {
-      const byte = chunk[0];
-      if (byte === 13 || byte === 10) {
-        cleanup();
-        resolve(true);
-        return;
-      }
-      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
-        cleanup();
-        resolve(false);
-      }
-    };
-
-    stdin.on("data", onData);
-  });
-}
-
 /** Patch console methods to also append output to the given log file descriptor. */
 function teeConsoleToLogFile(fd: number | "ignore"): void {
   if (fd === "ignore") return;
@@ -290,10 +249,22 @@ async function retireInner(): Promise<void> {
   const assistantId = entry.assistantId;
   const source = parsed.source;
   const cloud = resolveCloud(entry);
+
+  if (cloud === "paired") {
+    // A remote assistant paired from another machine. Retiring tears the
+    // assistant down — that can only happen on its host machine, never from a
+    // paired machine, which holds nothing but a pairing record. (Removing that
+    // local record is `vellum unpair`'s job, not retire's.)
+    console.error(
+      `Error: '${assistantId}' is a remote assistant paired from another machine — it can't be retired from here. Retiring tears down the assistant, which can only be done on its host machine. To remove the local pairing record on this machine, run \`vellum unpair ${assistantId}\`.`,
+    );
+    process.exit(1);
+  }
+
   printRetireTarget(entry, cloud);
 
   if (!parsed.yes) {
-    if (!canPromptForRetireConfirmation()) {
+    if (!canPromptForConfirmation()) {
       console.error(
         "Error: Refusing to retire without confirmation in a non-interactive terminal.",
       );
@@ -301,7 +272,9 @@ async function retireInner(): Promise<void> {
       process.exit(1);
     }
 
-    const confirmed = await confirmRetireInteractive();
+    const confirmed = await confirmAction(
+      "Press Enter to retire, or Esc/q to cancel: ",
+    );
     if (!confirmed) {
       console.log("Retire cancelled.");
       process.exit(1);

package/src/commands/sleep.ts

@@ -82,6 +82,13 @@ export async function sleep(): Promise<void> {
     process.exit(1);
   }
 
+  if (entry.cloud === "paired") {
+    console.error(
+      `Error: '${entry.assistantId}' is a remote assistant paired from another machine — its lifecycle is managed on its host machine, not here. Use \`vellum client ${entry.assistantId}\` to chat with it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum sleep' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,

package/src/commands/tunnel.ts

@@ -1,4 +1,7 @@
+import { join } from "path";
+
 import { resolveAssistant } from "../lib/assistant-config";
+import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
 import { runNgrokTunnel } from "../lib/ngrok";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -21,17 +24,45 @@ function parseArgs(): TunnelArgs {
     if (arg === "--help" || arg === "-h") {
       console.log("Usage: vellum tunnel [<name>] [options]");
       console.log("");
-      console.log("Create a tunnel for a locally hosted assistant.");
+      console.log(
+        "Expose a locally running assistant to the internet via a tunnel.",
+      );
+      console.log(
+        "The public URL is saved to the workspace config as the ingress base URL,",
+      );
+      console.log(
+        "enabling webhook integrations (Telegram, Twilio, etc.) to reach the assistant.",
+      );
       console.log("");
       console.log("Arguments:");
       console.log(
-        "  <name>                        Name of the assistant (defaults to latest)",
+        "  <name>                        Name of the assistant (defaults to active or only local)",
       );
       console.log("");
       console.log("Options:");
       console.log(
         `  --provider <provider>         Tunnel provider: ${VALID_PROVIDERS.join(", ")} (default: ${DEFAULT_PROVIDER})`,
       );
+      console.log("");
+      console.log("Providers:");
+      console.log(
+        "  vellum       Managed tunnel via Vellum Cloud (default; requires account)",
+      );
+      console.log(
+        "  ngrok        ngrok tunnel — install: brew install ngrok/ngrok/ngrok",
+      );
+      console.log(
+        "  cloudflare   Cloudflare quick tunnel — install: brew install cloudflare/cloudflare/cloudflared",
+      );
+      console.log(
+        "               No Cloudflare account required for quick tunnels.",
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ vellum tunnel");
+      console.log("  $ vellum tunnel --provider ngrok");
+      console.log("  $ vellum tunnel --provider cloudflare");
+      console.log("  $ vellum tunnel my-assistant --provider cloudflare");
       process.exit(0);
     } else if (arg === "--provider") {
       const next = args[i + 1];
@@ -78,5 +109,18 @@ export async function tunnel(): Promise<void> {
     return;
   }
 
+  if (provider === "cloudflare") {
+    const resources = entry.resources;
+    await runCloudflareTunnel(
+      resources
+        ? {
+            port: resources.gatewayPort,
+            workspaceDir: join(resources.instanceDir, ".vellum", "workspace"),
+          }
+        : {},
+    );
+    return;
+  }
+
   throw new Error(`Tunnel provider '${provider}' is not yet implemented.`);
 }

package/src/commands/unpair.ts

@@ -0,0 +1,118 @@
+/**
+ * `vellum unpair <name> [--yes]`
+ *
+ * Forget a pairing imported from another machine via `vellum connect import`:
+ * remove its lockfile entry and stored guardian token from THIS machine. Only
+ * paired assistants (`cloud: "paired"`) can be unpaired — `vellum retire` owns
+ * local and managed assistants.
+ *
+ * This is client-side only: it forgets the connection here but does not revoke
+ * the device on the host. (Host-side revocation is `vellum devices`.)
+ */
+
+import {
+  formatAssistantLookupError,
+  getAssistantDisplayName,
+  lookupAssistantByIdentifier,
+  removeAssistantEntry,
+} from "../lib/assistant-config";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import {
+  canPromptForConfirmation,
+  confirmAction,
+} from "../lib/confirm-action.js";
+import { deleteGuardianToken } from "../lib/guardian-token";
+
+function printUsage(): void {
+  console.log(`vellum unpair - Forget a paired assistant imported from another machine
+
+USAGE:
+    vellum unpair <name> [--yes]
+
+ARGUMENTS:
+    <name>    Name or id of the paired assistant to forget
+
+OPTIONS:
+    --yes     Skip the interactive confirmation prompt (for automation)
+
+Removes the local connection (lockfile entry + stored token). Only paired
+assistants (imported via 'vellum connect import') can be unpaired; use
+'vellum retire' for local or managed assistants.
+
+EXAMPLES:
+    vellum unpair paired-desk
+    vellum unpair "Desk Box"
+    vellum unpair paired-desk --yes
+`);
+}
+
+export async function unpair(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const yes = args.includes("--yes");
+  const name = parseAssistantTargetArg(args, []);
+  if (!name) {
+    console.error("Error: assistant name or id is required.");
+    printUsage();
+    process.exit(1);
+  }
+
+  const lookup = lookupAssistantByIdentifier(name);
+  if (lookup.status !== "found") {
+    console.error(formatAssistantLookupError(name, lookup));
+    process.exit(1);
+  }
+  const entry = lookup.entry;
+
+  if (entry.cloud !== "paired") {
+    console.error(
+      `Error: '${name}' is not a paired assistant. Use \`vellum retire\` to remove a local or managed assistant.`,
+    );
+    process.exit(1);
+  }
+
+  // Print the resolved identity before acting (cli/AGENTS.md).
+  const displayName = getAssistantDisplayName(entry);
+  console.log("Pairing to unpair:");
+  if (displayName !== entry.assistantId) {
+    console.log(`  Name: ${displayName}`);
+  }
+  console.log(`  ID: ${entry.assistantId}`);
+  if (entry.runtimeUrl) {
+    console.log(`  Host: ${entry.runtimeUrl}`);
+  }
+  console.log("");
+
+  if (!yes) {
+    if (!canPromptForConfirmation()) {
+      console.error(
+        "Error: Refusing to unpair without confirmation in a non-interactive terminal.",
+      );
+      console.error("Re-run with --yes to confirm from automation.");
+      process.exit(1);
+    }
+    const confirmed = await confirmAction(
+      "Press Enter to unpair, or Esc/q to cancel: ",
+    );
+    if (!confirmed) {
+      console.log("Unpair cancelled.");
+      process.exit(1);
+    }
+  }
+
+  removeAssistantEntry(entry.assistantId);
+  deleteGuardianToken(entry.assistantId);
+
+  console.log(
+    `Unpaired '${name}' — removed the local connection (lockfile entry + token).`,
+  );
+  console.log("");
+  console.log(
+    "Note: this only forgets the connection on this machine. The assistant's host can fully revoke this device from its side.",
+  );
+}

package/src/commands/wake.ts

@@ -68,6 +68,13 @@ export async function wake(): Promise<void> {
     process.exit(1);
   }
 
+  if (entry.cloud === "paired") {
+    console.error(
+      `Error: '${entry.assistantId}' is a remote assistant paired from another machine — its lifecycle is managed on its host machine, not here. Use \`vellum client ${entry.assistantId}\` to chat with it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum wake' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,