@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/src/commands/client.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import path from "node:path";
 
 import {
@@ -39,7 +39,9 @@ import {
   runDevicesRevoke,
   runHatch,
   runRetire,
-  connectImport,
+  pairingCancel,
+  pairingPoll,
+  pairingStart,
   unpairAssistant,
   getGuardianAccessToken,
   getPairedGuardianAccessToken,
@@ -72,11 +74,10 @@ import {
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { relaunchDetached } from "../lib/detached-process.js";
 import { probePort } from "../lib/port-probe.js";
 import { openBrowser } from "../lib/open-browser";
-import { isCompiledCli } from "../lib/local.js";
 import { findWebDistDir } from "../lib/web-dist.js";
-import { getLogDir, openLogFile, resetLogFile } from "../lib/xdg-log.js";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -431,7 +432,9 @@ const RETIRE_PATTERN = /^(?:\/assistant)?\/__local\/retire$/;
 const UNPAIR_PATTERN = /^(?:\/assistant)?\/__local\/unpair$/;
 const DEVICES_PATTERN = /^(?:\/assistant)?\/__local\/devices$/;
 const DEVICES_REVOKE_PATTERN = /^(?:\/assistant)?\/__local\/devices-revoke$/;
-const CONNECT_IMPORT_PATTERN = /^(?:\/assistant)?\/__local\/connect-import$/;
+const PAIRING_START_PATTERN = /^(?:\/assistant)?\/__local\/pairing-start$/;
+const PAIRING_POLL_PATTERN = /^(?:\/assistant)?\/__local\/pairing-poll$/;
+const PAIRING_CANCEL_PATTERN = /^(?:\/assistant)?\/__local\/pairing-cancel$/;
 const GUARDIAN_TOKEN_PATTERN =
   /^(?:\/assistant)?\/__local\/guardian-token\/([^/]+)$/;
 const PLATFORM_SESSION_PATTERN =
@@ -489,7 +492,9 @@ async function handleLocalEndpoints(
     UNPAIR_PATTERN.test(pathname) ||
     DEVICES_PATTERN.test(pathname) ||
     DEVICES_REVOKE_PATTERN.test(pathname) ||
-    CONNECT_IMPORT_PATTERN.test(pathname) ||
+    PAIRING_START_PATTERN.test(pathname) ||
+    PAIRING_POLL_PATTERN.test(pathname) ||
+    PAIRING_CANCEL_PATTERN.test(pathname) ||
     GUARDIAN_TOKEN_PATTERN.test(pathname) ||
     PLATFORM_SESSION_PATTERN.test(pathname) ||
     parseGatewayUrl(pathname).match ||
@@ -766,16 +771,26 @@ async function handleLocalEndpoints(
     return Response.json(await runDevicesList(invocation, assistantId));
   }
 
-  // Connect-import: register a pairing bundle from another machine (guardian
-  // token + paired lockfile entry), the write counterpart of unpair.
-  if (CONNECT_IMPORT_PATTERN.test(pathname)) {
+  // Pairing: the three-step device-code exchange that registers an assistant
+  // paired on another machine (guardian token + paired lockfile entry), the
+  // write counterpart of unpair. The exchange runs here rather than in the
+  // browser, so the device code and the credentials it buys never reach it.
+  if (
+    PAIRING_START_PATTERN.test(pathname) ||
+    PAIRING_POLL_PATTERN.test(pathname) ||
+    PAIRING_CANCEL_PATTERN.test(pathname)
+  ) {
     if (req.method !== "POST") {
       return new Response(null, { status: 405 });
     }
 
-    let body: { bundle?: unknown; name?: unknown };
+    let body: { address?: unknown; handle?: unknown; name?: unknown };
     try {
-      body = (await req.json()) as { bundle?: unknown; name?: unknown };
+      body = (await req.json()) as {
+        address?: unknown;
+        handle?: unknown;
+        name?: unknown;
+      };
     } catch {
       return Response.json(
         { ok: false, error: "Invalid JSON body" },
@@ -783,21 +798,58 @@ async function handleLocalEndpoints(
       );
     }
 
-    const result = connectImport(lockfilePaths, configDir, {
-      bundle: body.bundle,
+    if (PAIRING_CANCEL_PATTERN.test(pathname)) {
+      return Response.json({ ok: pairingCancel(body.handle) });
+    }
+
+    if (PAIRING_START_PATTERN.test(pathname)) {
+      const result = await pairingStart(body.address);
+      if (result.ok) {
+        return Response.json({
+          ok: true,
+          handle: result.handle,
+          userCode: result.userCode,
+          expiresAt: result.expiresAt,
+          intervalSeconds: result.intervalSeconds,
+        });
+      }
+      // `rejection` rides along so the renderer can show its own localized
+      // copy for a refused address instead of this host's English.
+      return Response.json(
+        {
+          ok: false,
+          reason: result.reason,
+          error: result.error,
+          rejection: result.rejection,
+        },
+        { status: result.status },
+      );
+    }
+
+    const result = await pairingPoll(lockfilePaths, configDir, {
+      handle: body.handle,
       name: body.name,
     });
-    if (result.ok) {
+    if (!result.ok) {
+      return Response.json(
+        { ok: false, reason: result.reason, error: result.error },
+        { status: result.status },
+      );
+    }
+    if (result.status === "pending") {
       return Response.json({
         ok: true,
-        assistantId: result.assistantId,
-        accessOnly: result.accessOnly,
+        status: "pending",
+        expiresAt: result.expiresAt,
+        intervalSeconds: result.intervalSeconds,
       });
     }
-    return Response.json(
-      { ok: false, error: result.error },
-      { status: result.status },
-    );
+    return Response.json({
+      ok: true,
+      status: "imported",
+      assistantId: result.assistantId,
+      accessOnly: result.accessOnly,
+    });
   }
 
   // Guardian token
@@ -1140,53 +1192,24 @@ async function spawnBackgroundWebInterface(
   }
   childArgs.push("--port", String(port));
 
-  // A compiled binary re-invokes itself; under plain bun (source tree, npm
-  // install) the entry script is argv[1].
-  const spawnArgs = isCompiledCli()
-    ? childArgs
-    : [process.argv[1], ...childArgs];
-
-  resetLogFile(WEB_BACKGROUND_LOG_FILE);
-  const fd = openLogFile(WEB_BACKGROUND_LOG_FILE);
-  const child = spawn(process.execPath, spawnArgs, {
-    detached: true,
-    stdio: ["ignore", fd, fd],
-  });
-  if (typeof fd === "number") {
-    closeSync(fd);
-  }
-  child.unref();
-
-  const logPath = path.join(getLogDir(), WEB_BACKGROUND_LOG_FILE);
-
   // Don't report success until the child is actually serving: watch for an
   // early exit (e.g. missing @vellumai/web assets, port lost to the TOCTOU
   // window) and poll the port until it accepts connections.
-  let exit: { code: number | null } | undefined;
-  child.on("error", () => {
-    exit = { code: null };
-  });
-  child.on("exit", (code) => {
-    exit = { code };
+  const { child, logPath, ready, exitCode } = await relaunchDetached({
+    args: childArgs,
+    logFile: WEB_BACKGROUND_LOG_FILE,
+    timeoutMs: WEB_BACKGROUND_START_TIMEOUT_MS,
+    isReady: () => probePort(port, "127.0.0.1"),
+    pollIntervalMs: 200,
   });
 
-  const deadline = Date.now() + WEB_BACKGROUND_START_TIMEOUT_MS;
-  let listening = false;
-  while (Date.now() < deadline && !exit) {
-    if (await probePort(port, "127.0.0.1")) {
-      listening = true;
-      break;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 200));
-  }
-
-  if (exit) {
+  if (exitCode !== undefined) {
     console.error(
-      `Web interface exited during startup${exit.code !== null ? ` (exit code ${exit.code})` : ""}. Logs: ${logPath}`,
+      `Web interface exited during startup${exitCode !== null ? ` (exit code ${exitCode})` : ""}. Logs: ${logPath}`,
     );
     process.exit(1);
   }
-  if (!listening) {
+  if (!ready) {
     // Kill the detached child (its whole process group — the Vite path spawns
     // grandchildren) so a slow startup can't bind the port and linger after
     // we've reported failure.

package/src/commands/connect/import.ts

@@ -1,42 +1,138 @@
 /**
- * `vellum connect import <blob> [--name <localname>]`
+ * `vellum connect import <address> [--name <localname>]`
  *
- * Import a pairing bundle printed by `vellum pair` on another machine and
- * register it locally so `vellum client`/`message`/`events <name>` work against
- * the remote assistant. Decoding, id derivation, and the lockfile/token writes
- * live in `pairAssistant` (`@vellumai/local-mode`); this command owns only the
- * argv parsing and output copy.
+ * Pair this machine with an assistant running elsewhere and register it
+ * locally so `vellum client`/`message`/`events <name>` work against it. The
+ * device-code exchange, the lockfile write, and the token write live in
+ * `pairingStart`/`pairingPoll` (`@vellumai/local-mode`); this command owns the
+ * argv parsing, the polling cadence, and the output copy.
  */
 
 import {
-  decodePairBundle,
-  pairAssistant,
+  checkPairedAssistantName,
+  connectImport as importLegacyBundle,
+  pairingCancel,
+  pairingPoll,
+  pairingStart,
   resolveConfigDir,
 } from "@vellumai/local-mode";
+import { isRetryablePairingReason } from "@vellumai/service-contracts/remote-web-pairing";
 
 import { extractFlag } from "../../lib/arg-utils.js";
 import { getLockfilePaths } from "../../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../../lib/environments/resolve.js";
+import { STALE_CLI_UPDATE_HINT } from "../../lib/stale-cli-hint.js";
 
 function printUsage(): void {
-  console.log(`vellum connect import - Register an assistant paired from another machine
+  console.log(`vellum connect import - Pair with an assistant running on another machine
 
 USAGE:
-    vellum connect import <bundle> [options]
+    vellum connect import <address> [options]
+
+Registers the assistant at <address> on this machine: a lockfile entry plus a
+guardian token, both under the local name below. The pairing is a device of
+its own on the host, listed and separately revocable there.
+
+<address> is either form of pairing artifact:
+
+    A pairing link from 'vellum pair' (or the host's Pair a device card). It
+    carries an approved device code, so the import completes right away.
+
+    The assistant's public https address, e.g. https://your-assistant.ts.net.
+    This machine mints its own pairing code, prints it, and polls until the
+    code is approved on the host with 'vellum pair --web-approve <code>' or
+    expires (10 minutes). Ctrl-C cancels the attempt. A temporary network
+    failure is retried until then rather than ending the attempt.
 
 ARGUMENTS:
-    <bundle>    The base64 bundle printed by 'vellum pair' on the host machine
+    <address>       A pairing link or the assistant's https address. https
+                    only; loopback, private-network, and tunnel-provider
+                    website addresses are refused.
 
 OPTIONS:
-    --name <name>   Local name to register the assistant under
-                    (default: paired-<deviceId>)
+    --name <name>   Local name to register the assistant under, slugified for
+                    the id (default: paired-<assistant host>). An existing
+                    local assistant of that name is never overwritten;
+                    re-importing the same host updates its entry.
 
 EXAMPLES:
-    vellum connect import eyJnYXRld2F5...
-    vellum connect import eyJnYXRld2F5... --name desk
+    vellum connect import "https://your-assistant.ts.net/assistant/pair#device_code=abc123"
+    vellum connect import https://your-assistant.ts.net
+    vellum connect import https://your-assistant.ts.net --name desk
 `);
 }
 
+/** Caps a retry backoff so a long attempt still polls on a useful cadence. */
+const MAX_RETRY_BACKOFF_SECONDS = 30;
+
+/**
+ * The single place a local registration refusal becomes output. A 409 is a
+ * name collision, so it carries the "pick another name" guidance whether it
+ * came from the pre-check below or from the import itself.
+ */
+function formatImportFailure(status: number, error: string): string {
+  return status === 409
+    ? `Error: ${error} locally. Choose a different --name to avoid overwriting it.`
+    : `Error: ${error}`;
+}
+
+/** The shared success output of both import paths. */
+function reportImported(result: {
+  assistantId: string;
+  updated: boolean;
+  accessOnly: boolean;
+}): void {
+  console.log(
+    `${result.updated ? "Updated" : "Imported"} paired assistant '${result.assistantId}'.`,
+  );
+  console.log("");
+  console.log(`  Connect with:  vellum client ${result.assistantId}`);
+  console.log("");
+  console.log(
+    result.accessOnly
+      ? "Note: the assistant issued an access-only token, so this connection will expire. Run `vellum connect import` again with a fresh pairing link when it does."
+      : "Note: this connection includes a refresh credential, so it can renew itself. Re-pair only if it's revoked or the refresh credential expires.",
+  );
+}
+
+/**
+ * DEPRECATED input path, kept for one upgrade cycle: a host still on the
+ * previous CLI release mints a base64 pairing bundle, and an upgraded second
+ * machine would otherwise reject that bundle as an invalid address. Delete
+ * this once that release is out of support; nothing mints bundles any more.
+ *
+ * Returns true when the argument was a bundle and the import is done. A 400
+ * means it did not decode as one, so the caller reports the address error it
+ * already has instead of a bundle error.
+ */
+function importLegacyPairingBundle(
+  lockfilePaths: string[],
+  configDir: string,
+  address: string,
+  name: string | undefined,
+): boolean {
+  const result = importLegacyBundle(lockfilePaths, configDir, {
+    bundle: address,
+    name,
+  });
+  if (!result.ok) {
+    if (result.status === 400) {
+      return false;
+    }
+    console.error(formatImportFailure(result.status, result.error));
+    process.exit(1);
+  }
+  console.log(
+    "Warning: base64 pairing bundles are deprecated and will stop working in a future release.",
+  );
+  console.log(
+    "Newer hosts print a pairing link instead: run `vellum pair` there and import that link.",
+  );
+  console.log("");
+  reportImported(result);
+  return true;
+}
+
 export async function connectImport(): Promise<void> {
   const rawArgs = process.argv.slice(4);
 
@@ -46,51 +142,151 @@ export async function connectImport(): Promise<void> {
   }
 
   const [nameFlag, args] = extractFlag(rawArgs, "--name");
-  const blob = args[0];
-  if (!blob) {
-    console.error("Error: missing pairing bundle.");
-    printUsage();
-    process.exit(1);
-  }
 
-  const decoded = decodePairBundle(blob);
-  if (!decoded.ok) {
+  // Any `--`-prefixed token left after known-flag extraction is an option this
+  // CLI version doesn't support. Fail loud before any network call rather than
+  // letting it fall through: an unknown flag would otherwise be read as the
+  // address and reported as an unusable one, hiding the real mistake. Neither
+  // an https address nor a pairing link starts with `--`.
+  const unknownFlag = args.find((a) => a.startsWith("--"));
+  if (unknownFlag) {
+    console.error(`Error: unknown option '${unknownFlag}'.`);
+    console.error(
+      "Run `vellum connect import --help` to see available options.",
+    );
     console.error(
-      "Error: invalid pairing bundle. Paste the full base64 string printed by `vellum pair`.",
+      `If this option is from newer docs, ${STALE_CLI_UPDATE_HINT}`,
     );
     process.exit(1);
   }
 
-  const result = pairAssistant(
-    getLockfilePaths(getCurrentEnvironment()),
-    resolveConfigDir(process.env),
-    { bundle: decoded.bundle, name: nameFlag },
-  );
-  if (!result.ok) {
-    if (result.status === 400) {
-      console.error(
-        "Error: --name must contain at least one alphanumeric character.",
-      );
-    } else if (result.status === 409) {
-      console.error(
-        `Error: an assistant named '${result.assistantId}' already exists locally. ` +
-          "Choose a different --name to avoid overwriting it.",
-      );
-    } else {
-      console.error(`Error: ${result.error}`);
+  const address = args[0];
+  if (!address) {
+    console.error("Error: missing assistant address.");
+    printUsage();
+    process.exit(1);
+  }
+
+  const lockfilePaths = getLockfilePaths(getCurrentEnvironment());
+  const configDir = resolveConfigDir(process.env);
+
+  // Refuse a colliding --name BEFORE anything is exchanged. The device code is
+  // one-time and the gateway records a device the moment it is spent, so
+  // discovering the collision after the exchange would orphan that device and
+  // force the user to generate a fresh link. This is a pre-check, not a
+  // reservation: another process can still claim the id in between, which the
+  // real check inside the import path catches.
+  if (nameFlag) {
+    const conflict = checkPairedAssistantName(lockfilePaths, nameFlag);
+    if (conflict) {
+      console.error(formatImportFailure(conflict.status, conflict.error));
+      process.exit(1);
     }
+  }
+
+  const started = await pairingStart(address);
+  if (!started.ok) {
+    // The address path runs first, so the normal flow never touches the
+    // deprecated bundle decoder; only an unusable address falls through to it.
+    if (
+      started.reason === "invalid-address" &&
+      importLegacyPairingBundle(lockfilePaths, configDir, address, nameFlag)
+    ) {
+      return;
+    }
+    console.error(`Error: ${started.error}`);
     process.exit(1);
   }
 
-  console.log(
-    `${result.updated ? "Updated" : "Imported"} paired assistant '${result.assistantId}'.`,
-  );
-  console.log("");
-  console.log(`  Connect with:  vellum client ${result.assistantId}`);
-  console.log("");
-  console.log(
-    result.accessOnly
-      ? "Note: the token is access-only and will expire. Re-run `vellum pair` and import again when it does."
-      : "Note: this connection includes a refresh credential, so it can renew itself. Re-pair only if it's revoked or the refresh credential expires.",
-  );
+  // An interrupted wait drops the pending session rather than leaving the
+  // device code exchangeable for the rest of its TTL.
+  const cancelPairing = (): void => {
+    pairingCancel(started.handle);
+    process.exit(130);
+  };
+  process.on("SIGINT", cancelPairing);
+  process.on("SIGTERM", cancelPairing);
+
+  try {
+    if (started.userCode) {
+      console.log("Approve this pairing on the assistant's machine:");
+      console.log("");
+      console.log(`  Code: ${started.userCode}`);
+      console.log(`  Run:  vellum pair --web-approve ${started.userCode}`);
+      console.log("");
+      console.log(`Waiting for approval (expires ${started.expiresAt})...`);
+    }
+
+    // The approval wait promises to run until approval or expiry, so a
+    // transport failure backs off and polls again rather than abandoning a
+    // session local-mode is deliberately keeping alive. Minting the challenge
+    // already proved this address reachable, so a later failure is transient.
+    //
+    // A pairing link is the other case: it opens a session without any
+    // request, so nothing has proved the host is up, and there is no approval
+    // to wait for. An unreachable host is reported at once there instead of
+    // hanging for the link's full TTL.
+    const retryTransientFailures = started.userCode !== null;
+    let expiresAt = started.expiresAt;
+    let intervalSeconds = started.intervalSeconds;
+    let consecutiveFailures = 0;
+
+    for (;;) {
+      const result = await pairingPoll(lockfilePaths, configDir, {
+        handle: started.handle,
+        name: nameFlag,
+        platform: "cli",
+      });
+
+      if (!result.ok) {
+        if (
+          !retryTransientFailures ||
+          !isRetryablePairingReason(result.reason)
+        ) {
+          console.error(formatImportFailure(result.status, result.error));
+          process.exit(1);
+        }
+        const expiresAtMs = Date.parse(expiresAt);
+        if (Number.isFinite(expiresAtMs) && Date.now() >= expiresAtMs) {
+          console.error(
+            "Error: the pairing code expired before the assistant could be " +
+              "reached. Start over to get a new one.",
+          );
+          process.exit(1);
+        }
+        consecutiveFailures += 1;
+        if (consecutiveFailures === 1) {
+          console.log("");
+          console.log(
+            `Could not reach the assistant: ${result.error} ` +
+              `Still trying until the code expires (${expiresAt}).`,
+          );
+        }
+        await Bun.sleep(
+          Math.min(
+            intervalSeconds * consecutiveFailures,
+            MAX_RETRY_BACKOFF_SECONDS,
+          ) * 1000,
+        );
+        continue;
+      }
+
+      consecutiveFailures = 0;
+
+      if (result.status === "imported") {
+        reportImported(result);
+        return;
+      }
+
+      // Pending: the host has not approved the code yet. The gateway names the
+      // deadline and the cadence, and `pairingPoll` reports the attempt expired
+      // once that deadline passes.
+      expiresAt = result.expiresAt;
+      intervalSeconds = result.intervalSeconds;
+      await Bun.sleep(intervalSeconds * 1000);
+    }
+  } finally {
+    process.off("SIGINT", cancelPairing);
+    process.off("SIGTERM", cancelPairing);
+  }
 }

package/src/commands/connect.ts

@@ -7,7 +7,7 @@ function printUsage(): void {
   console.log("");
   console.log("Subcommands:");
   console.log(
-    "  import    Import a pairing bundle from `vellum pair` and register it",
+    "  import    Pair with an assistant at a link or https address and register it",
   );
 }
 

package/src/commands/devices.ts

@@ -165,6 +165,10 @@ async function listDevices(
   for (const device of devices) {
     console.log(`  ${device.hashedDeviceId}`);
     console.log(`    platform:   ${device.platform}`);
+    console.log(
+      `    name:       ${device.clientReportedName || "not reported"}`,
+    );
+    console.log(`    user agent: ${device.pairingUserAgent || "not recorded"}`);
     console.log(`    issued:     ${formatTimestamp(device.issuedAt, "—")}`);
     console.log(`    expires:    ${formatTimestamp(device.expiresAt, "—")}`);
     console.log(