@vellumai/cli 0.8.6 → 0.8.7-dev.202606052135.3e62c5a

package/src/commands/connect/import.ts

@@ -0,0 +1,217 @@
+/**
+ * `vellum connect import <blob> [--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.
+ *
+ * The bundle is base64(JSON.stringify({ gatewayUrl, assistantId, token,
+ * deviceId })). We store the entry under a UNIQUE LOCAL id (not the bundle's
+ * assistantId, which is typically "self" and would collide across hosts). This
+ * is safe because the gateway's runtime proxy strips the `/v1/assistants/<id>/`
+ * segment before forwarding, so the local id never has to match the remote one
+ * — the token (validated by signature/audience) is what authorizes requests.
+ */
+
+import { nanoid } from "nanoid";
+
+import { extractFlag } from "../../lib/arg-utils.js";
+import {
+  findAssistantByName,
+  saveAssistantEntry,
+} from "../../lib/assistant-config.js";
+import { saveGuardianToken } from "../../lib/guardian-token.js";
+
+function printUsage(): void {
+  console.log(`vellum connect import - Register an assistant paired from another machine
+
+USAGE:
+    vellum connect import <bundle> [options]
+
+ARGUMENTS:
+    <bundle>    The base64 bundle printed by 'vellum pair' on the host machine
+
+OPTIONS:
+    --name <name>   Local name to register the assistant under
+                    (default: paired-<deviceId>)
+
+EXAMPLES:
+    vellum connect import eyJnYXRld2F5...
+    vellum connect import eyJnYXRld2F5... --name desk
+`);
+}
+
+interface PairBundle {
+  gatewayUrl: string;
+  token: string;
+  assistantId?: string;
+  deviceId?: string;
+  // Optional refresh credential. Present when the host's gateway issued a
+  // device-bound token pair; absent for older access-only bundles (which remain
+  // importable, just without auto-renewal). `refreshTokenExpiresAt` mirrors
+  // GuardianTokenData (ISO string OR epoch-ms number) so a numeric expiry isn't
+  // silently dropped on import.
+  refreshToken?: string;
+  refreshTokenExpiresAt?: string | number;
+  refreshAfter?: string;
+}
+
+/** Decode the base64 bundle, returning null if malformed or missing fields. */
+function decodeBundle(blob: string): PairBundle | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(Buffer.from(blob, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof json !== "object" || json === null) return null;
+  const b = json as Record<string, unknown>;
+  if (typeof b.gatewayUrl !== "string" || typeof b.token !== "string") {
+    return null;
+  }
+  // The gatewayUrl is persisted as runtimeUrl and used to build fetch URLs, so
+  // require an absolute http(s) URL here rather than letting an invalid string
+  // through (which would crash `new URL(...)` or break later client calls).
+  try {
+    const parsed = new URL(b.gatewayUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  return {
+    gatewayUrl: b.gatewayUrl,
+    token: b.token,
+    assistantId: typeof b.assistantId === "string" ? b.assistantId : undefined,
+    deviceId: typeof b.deviceId === "string" ? b.deviceId : undefined,
+    refreshToken:
+      typeof b.refreshToken === "string" ? b.refreshToken : undefined,
+    refreshTokenExpiresAt:
+      typeof b.refreshTokenExpiresAt === "string" ||
+      typeof b.refreshTokenExpiresAt === "number"
+        ? b.refreshTokenExpiresAt
+        : undefined,
+    refreshAfter:
+      typeof b.refreshAfter === "string" ? b.refreshAfter : undefined,
+  };
+}
+
+/** Lowercase, collapse non-alphanumerics to single dashes, trim dashes. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Best-effort JWT `exp` (epoch seconds) → epoch ms; null if undecodable. */
+function jwtExpiryMs(token: string): number | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64").toString("utf8"),
+    );
+    if (typeof payload.exp === "number") return payload.exp * 1000;
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+export async function connectImport(): Promise<void> {
+  const rawArgs = process.argv.slice(4);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const [nameFlag, args] = extractFlag(rawArgs, "--name");
+  const blob = args[0];
+  if (!blob) {
+    console.error("Error: missing pairing bundle.");
+    printUsage();
+    process.exit(1);
+  }
+
+  const bundle = decodeBundle(blob);
+  if (!bundle) {
+    console.error(
+      "Error: invalid pairing bundle. Paste the full base64 string printed by `vellum pair`.",
+    );
+    process.exit(1);
+  }
+
+  // Unique local id: a --name slug, or paired-<deviceId> (deviceId is unique
+  // per pairing). Never the bundle's "self" assistantId — that would collide.
+  // The deviceId comes from an untrusted bundle and is used as a path component
+  // by saveGuardianToken, so it MUST be slugified (no `../` traversal); fall
+  // back to a random id if it sanitizes to empty.
+  const localId = nameFlag
+    ? slugify(nameFlag)
+    : `paired-${slugify(bundle.deviceId ?? "") || nanoid()}`;
+  if (!localId) {
+    console.error(
+      "Error: --name must contain at least one alphanumeric character.",
+    );
+    process.exit(1);
+  }
+
+  // Don't clobber an existing assistant. Only update in place when the prior
+  // entry is itself a paired import (marked `paired: true`); otherwise the id
+  // collides with a real local/remote assistant and overwriting would drop its
+  // resources/runtime metadata. Reject and let the user pick a fresh --name.
+  const existing = findAssistantByName(localId);
+  if (existing && existing.paired !== true) {
+    console.error(
+      `Error: an assistant named '${localId}' already exists locally. ` +
+        "Choose a different --name to avoid overwriting it.",
+    );
+    process.exit(1);
+  }
+  const existed = existing !== null;
+
+  saveAssistantEntry({
+    assistantId: localId,
+    name: nameFlag ?? `paired (${new URL(bundle.gatewayUrl).host})`,
+    runtimeUrl: bundle.gatewayUrl,
+    // Paired entries are reached by bearer token at the remote runtimeUrl
+    // (a non-"vellum" cloud selects the bearer-token auth path in client.ts).
+    // The "paired" topology lets lifecycle/status commands (ps/wake/sleep)
+    // recognize this as a remote pairing rather than an on-machine process.
+    cloud: "paired",
+    // Marks this entry as a connect-import so re-imports update in place while
+    // imports never silently overwrite a non-paired assistant (see guard above).
+    paired: true,
+    species: "vellum",
+  });
+
+  const now = Date.now();
+  const hasRefresh = Boolean(bundle.refreshToken);
+  saveGuardianToken(localId, {
+    guardianPrincipalId: "imported",
+    accessToken: bundle.token,
+    accessTokenExpiresAt:
+      jwtExpiryMs(bundle.token) ?? now + 24 * 60 * 60 * 1000,
+    refreshToken: bundle.refreshToken ?? "",
+    refreshTokenExpiresAt: bundle.refreshTokenExpiresAt ?? 0,
+    refreshAfter: bundle.refreshAfter ?? "",
+    isNew: false,
+    deviceId: bundle.deviceId ?? "",
+    leasedAt: new Date(now).toISOString(),
+  });
+
+  console.log(
+    `${existed ? "Updated" : "Imported"} paired assistant '${localId}'.`,
+  );
+  console.log("");
+  console.log(`  Connect with:  vellum client ${localId}`);
+  console.log("");
+  console.log(
+    hasRefresh
+      ? "Note: this connection includes a refresh credential, so it can renew itself — re-pair only if it's revoked or the refresh credential expires."
+      : "Note: the token is access-only and will expire — re-run `vellum pair` and import again when it does.",
+  );
+}

package/src/commands/connect.ts

@@ -0,0 +1,31 @@
+import { connectImport } from "./connect/import.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum connect <subcommand>");
+  console.log("");
+  console.log("Connect to an assistant paired from another machine.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log(
+    "  import    Import a pairing bundle from `vellum pair` and register it",
+  );
+}
+
+export async function connect(): Promise<void> {
+  const args = process.argv.slice(3);
+  const subcommand = args[0];
+
+  if (subcommand === "--help" || subcommand === "-h" || !subcommand) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (subcommand === "import") {
+    await connectImport();
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printUsage();
+  process.exit(1);
+}

package/src/commands/devices.ts

@@ -0,0 +1,247 @@
+/**
+ * `vellum devices [name]` and `vellum devices revoke <hashedDeviceId> [name] [--yes]`
+ *
+ * Host-side of pairing lifecycle: list and revoke the devices paired to a LOCAL
+ * self-hosted assistant. Calls the loopback-only gateway endpoints
+ * `GET /v1/devices` and `POST /v1/devices/revoke` (added in the gateway slice),
+ * which self-guard loopback + reject any browser/WebView Origin. The gateway
+ * only ever stores the HASHED device id, so list returns and revoke accepts the
+ * same `hashedDeviceId` (the raw device id is never persisted anywhere).
+ *
+ * This is the counterpart to `vellum unpair`: `unpair` forgets a connection on
+ * the *paired* machine (client side); `devices` revokes a device from the *host*
+ * that runs the assistant (server side).
+ */
+
+import {
+  type AssistantEntry,
+  formatAssistantReference,
+  getAssistantDisplayName,
+  resolveTargetAssistant,
+} from "../lib/assistant-config";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import {
+  CLI_INTERFACE_ID,
+  getClientRegistrationHeaders,
+} from "../lib/client-identity.js";
+import {
+  canPromptForConfirmation,
+  confirmAction,
+} from "../lib/confirm-action.js";
+
+interface DeviceRecord {
+  hashedDeviceId: string;
+  platform: string;
+  issuedAt: number | null;
+  expiresAt: number | null;
+  lastUsedAt: number | null;
+}
+
+function printUsage(): void {
+  console.log(`vellum devices - List and revoke devices paired to a local assistant
+
+USAGE:
+    vellum devices [name]
+    vellum devices revoke <hashedDeviceId> [name] [--yes]
+
+ARGUMENTS:
+    [name]              Name or id of the local assistant (defaults to the active/sole one)
+    <hashedDeviceId>    The device's hashed id (copy it from the list output)
+
+OPTIONS:
+    --yes              Skip the interactive confirmation prompt when revoking (for automation)
+
+Lists the devices paired to a local (host-side) assistant, or revokes one by its
+hashed id. Runs on the machine that hosts the assistant — paired connections
+imported from another machine are managed with 'vellum unpair' instead.
+
+EXAMPLES:
+    vellum devices
+    vellum devices my-desk
+    vellum devices revoke 3f9a1c...
+    vellum devices revoke 3f9a1c... my-desk --yes
+`);
+}
+
+/**
+ * Resolve the LOOPBACK gateway base URL for a host-side assistant, or exit with
+ * a helpful error. Refuses paired connections (they have no local gateway here)
+ * and never falls back to a non-loopback URL.
+ */
+function resolveLoopbackBase(entry: AssistantEntry): string {
+  const displayName = getAssistantDisplayName(entry);
+
+  if (entry.cloud === "paired") {
+    console.error(
+      `Error: '${displayName}' is a paired connection imported from another machine.`,
+    );
+    console.error(
+      "Run `vellum devices` on the host that runs the assistant to manage its devices.",
+    );
+    console.error("To forget this connection here, use `vellum unpair`.");
+    process.exit(1);
+  }
+
+  const base =
+    entry.localUrl ||
+    (entry.resources?.gatewayPort
+      ? `http://127.0.0.1:${entry.resources.gatewayPort}`
+      : undefined);
+  if (!base) {
+    console.error(
+      `Error: no local gateway found for '${displayName}'. \`vellum devices\` runs on the machine hosting the assistant.`,
+    );
+    process.exit(1);
+  }
+
+  return base.replace(/\/+$/, "");
+}
+
+/** Format an epoch-ms timestamp as ISO, or a placeholder when absent. */
+function formatTimestamp(ms: number | null, absent: string): string {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return absent;
+  return new Date(ms).toISOString();
+}
+
+async function listDevices(entry: AssistantEntry, base: string): Promise<void> {
+  const displayName = getAssistantDisplayName(entry);
+
+  let response: Response;
+  try {
+    response = await fetch(`${base}/v1/devices`, {
+      method: "GET",
+      headers: getClientRegistrationHeaders(CLI_INTERFACE_ID),
+    });
+  } catch (err) {
+    console.error(
+      `Error: could not reach the gateway for '${displayName}' at ${base}: ${
+        (err as Error).message
+      }`,
+    );
+    process.exit(1);
+  }
+
+  if (!response.ok) {
+    console.error(
+      `Error: gateway returned ${response.status} listing devices for '${displayName}'.`,
+    );
+    process.exit(1);
+  }
+
+  const body = (await response.json()) as { devices?: DeviceRecord[] };
+  const devices = body.devices ?? [];
+
+  if (devices.length === 0) {
+    console.log(`No devices are paired to ${displayName}.`);
+    return;
+  }
+
+  console.log(`Devices paired to ${formatAssistantReference(entry)}:`);
+  console.log("");
+  for (const device of devices) {
+    console.log(`  ${device.hashedDeviceId}`);
+    console.log(`    platform:   ${device.platform}`);
+    console.log(`    issued:     ${formatTimestamp(device.issuedAt, "—")}`);
+    console.log(`    expires:    ${formatTimestamp(device.expiresAt, "—")}`);
+    console.log(
+      `    last used:  ${formatTimestamp(device.lastUsedAt, "never")}`,
+    );
+    console.log("");
+  }
+  console.log(
+    `${devices.length} device(s). Revoke one with: vellum devices revoke <hashedDeviceId>`,
+  );
+}
+
+async function revokeDevice(
+  entry: AssistantEntry,
+  base: string,
+  hashedDeviceId: string,
+  yes: boolean,
+): Promise<void> {
+  const displayName = getAssistantDisplayName(entry);
+
+  // Print the resolved identity before acting (cli/AGENTS.md).
+  console.log("Device to revoke:");
+  console.log(`  Assistant: ${formatAssistantReference(entry)}`);
+  console.log(`  Device:    ${hashedDeviceId}`);
+  console.log("");
+
+  if (!yes) {
+    if (!canPromptForConfirmation()) {
+      console.error(
+        "Error: Refusing to revoke 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 revoke, or Esc/q to cancel: ",
+    );
+    if (!confirmed) {
+      console.log("Revoke cancelled.");
+      process.exit(1);
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(`${base}/v1/devices/revoke`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...getClientRegistrationHeaders(CLI_INTERFACE_ID),
+      },
+      body: JSON.stringify({ hashedDeviceId }),
+    });
+  } catch (err) {
+    console.error(
+      `Error: could not reach the gateway for '${displayName}' at ${base}: ${
+        (err as Error).message
+      }`,
+    );
+    process.exit(1);
+  }
+
+  if (!response.ok) {
+    console.error(
+      `Error: gateway returned ${response.status} revoking device for '${displayName}'.`,
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `Revoked device ${hashedDeviceId} from ${displayName}. Its tokens are invalidated; that machine must re-pair to reconnect.`,
+  );
+}
+
+export async function devices(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  if (args[0] === "revoke") {
+    const rest = args.slice(1);
+    const yes = rest.includes("--yes");
+    const positionals = rest.filter((a) => !a.startsWith("-"));
+    const hashedDeviceId = positionals[0];
+    if (!hashedDeviceId) {
+      console.error("Error: a hashedDeviceId is required to revoke.");
+      printUsage();
+      process.exit(1);
+    }
+    const nameArg = positionals.slice(1).join(" ") || undefined;
+    const entry = resolveTargetAssistant(nameArg);
+    const base = resolveLoopbackBase(entry);
+    await revokeDevice(entry, base, hashedDeviceId, yes);
+    return;
+  }
+
+  const nameArg = parseAssistantTargetArg(args, []);
+  const entry = resolveTargetAssistant(nameArg);
+  const base = resolveLoopbackBase(entry);
+  await listDevices(entry, base);
+}

package/src/commands/env.ts

@@ -1,4 +1,4 @@
-import { SEEDS } from "../lib/environments/seeds.js";
+import { SEEDS } from "@vellumai/environments";
 import {
   clearDefaultEnvironment,
   readDefaultEnvironment,

package/src/commands/flags.ts

@@ -1,4 +1,8 @@
 import { AssistantClient } from "../lib/assistant-client.js";
+import {
+  formatAssistantLookupError,
+  lookupAssistantByIdentifier,
+} from "../lib/assistant-config.js";
 
 type FeatureFlagEntry = {
   key: string;
@@ -17,7 +21,12 @@ function pad(s: string, w: number): string {
 }
 
 function printFlagTable(flags: FeatureFlagEntry[]): void {
-  const headers = { key: "KEY", enabled: "ENABLED", default: "DEFAULT", label: "LABEL" };
+  const headers = {
+    key: "KEY",
+    enabled: "ENABLED",
+    default: "DEFAULT",
+    label: "LABEL",
+  };
 
   const rows = flags
     .slice()
@@ -55,7 +64,9 @@ function printHelp(): void {
   console.log("Usage: vellum flags [subcommand] [options]");
   console.log("");
   console.log("Show and toggle feature flags for the active assistant.");
-  console.log("Reads from the gateway's merged flag state (persisted overrides > remote > defaults).");
+  console.log(
+    "Reads from the gateway's merged flag state (persisted overrides > remote > defaults).",
+  );
   console.log("");
   console.log("Subcommands:");
   console.log("  (none)              List all feature flags in a table");
@@ -63,20 +74,53 @@ function printHelp(): void {
   console.log("  set <key> <bool>    Set a flag override to true or false");
   console.log("");
   console.log("Options:");
+  console.log(
+    "  --assistant <name>  Target a specific assistant (display name or ID)",
+  );
+  console.log(
+    "                      instead of the active one. Useful for scripted",
+  );
+  console.log(
+    "                      flows like eval harnesses that must not mutate",
+  );
+  console.log("                      the user's active-assistant pointer.");
   console.log("  --help, -h          Show this help");
   console.log("");
   console.log("Examples:");
-  console.log("  $ vellum flags                                 # list all flags");
-  console.log("  $ vellum flags get query-complexity-routing     # inspect one flag");
-  console.log("  $ vellum flags set voice-mode true              # enable a flag");
+  console.log(
+    "  $ vellum flags                                              # list flags for active assistant",
+  );
+  console.log(
+    "  $ vellum flags get query-complexity-routing                  # inspect one flag",
+  );
+  console.log(
+    "  $ vellum flags set voice-mode true                           # enable a flag",
+  );
+  console.log(
+    "  $ vellum flags set external-plugins true --assistant eval-1  # target by name/id",
+  );
 }
 
-function createClient(): AssistantClient {
+function createClient(assistantName?: string): AssistantClient {
+  // When `--assistant <name>` is provided, resolve the display name or
+  // explicit ID through the standard lookup helper (see cli/AGENTS.md
+  // "Assistant targeting convention"). Exact ID wins over display-name
+  // matches; ambiguous names fail loudly.
+  let assistantId: string | undefined;
+  if (assistantName) {
+    const result = lookupAssistantByIdentifier(assistantName);
+    if (result.status !== "found") {
+      throw new Error(formatAssistantLookupError(assistantName, result));
+    }
+    assistantId = result.entry.assistantId;
+  }
   try {
-    return new AssistantClient();
+    return new AssistantClient(assistantId ? { assistantId } : undefined);
   } catch {
     throw new Error(
-      "No assistant found. Hatch one with 'vellum hatch' first.",
+      assistantName
+        ? `No assistant found matching '${assistantName}'.`
+        : "No assistant found. Hatch one with 'vellum hatch' first.",
     );
   }
 }
@@ -93,8 +137,8 @@ function rethrowFetchError(err: unknown): never {
   throw err;
 }
 
-async function listFlags(): Promise<void> {
-  const client = createClient();
+async function listFlags(assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
   let res: Response;
   try {
     res = await client.get("/feature-flags");
@@ -113,8 +157,8 @@ async function listFlags(): Promise<void> {
   printFlagTable(data.flags);
 }
 
-async function getFlag(key: string): Promise<void> {
-  const client = createClient();
+async function getFlag(key: string, assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
   let res: Response;
   try {
     res = await client.get("/feature-flags");
@@ -136,8 +180,12 @@ async function getFlag(key: string): Promise<void> {
   console.log(`Description:    ${flag.description || "(none)"}`);
 }
 
-async function setFlag(key: string, value: boolean): Promise<void> {
-  const client = createClient();
+async function setFlag(
+  key: string,
+  value: boolean,
+  assistantName?: string,
+): Promise<void> {
+  const client = createClient(assistantName);
   let res: Response;
   try {
     res = await client.patch(`/feature-flags/${key}`, { enabled: value });
@@ -151,6 +199,28 @@ async function setFlag(key: string, value: boolean): Promise<void> {
   console.log(`Flag "${key}" set to ${value}`);
 }
 
+/**
+ * Strip `--assistant <name>` from argv and return the captured value.
+ *
+ * Mutates the input array so positional parsing downstream sees a clean
+ * shape (subcommand + key + value). Returns `undefined` if the flag is
+ * absent. Error-reports a missing value so the user gets a clear message
+ * rather than the flag being silently swallowed as a positional.
+ */
+function extractAssistantFlag(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--assistant") continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error("Missing value for --assistant <name>");
+      process.exit(1);
+    }
+    args.splice(i, 2);
+    return value;
+  }
+  return undefined;
+}
+
 export async function flags(): Promise<void> {
   const args = process.argv.slice(3);
 
@@ -159,10 +229,12 @@ export async function flags(): Promise<void> {
     return;
   }
 
+  const assistantName = extractAssistantFlag(args);
+
   const subcommand = args[0];
 
   if (!subcommand) {
-    await listFlags();
+    await listFlags(assistantName);
     return;
   }
 
@@ -172,7 +244,7 @@ export async function flags(): Promise<void> {
       console.error("Usage: vellum flags get <key>");
       process.exit(1);
     }
-    await getFlag(key);
+    await getFlag(key, assistantName);
     return;
   }
 
@@ -187,7 +259,7 @@ export async function flags(): Promise<void> {
       console.error(`Invalid value "${rawValue}". Must be "true" or "false".`);
       process.exit(1);
     }
-    await setFlag(key, rawValue === "true");
+    await setFlag(key, rawValue === "true", assistantName);
     return;
   }