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

package/src/commands/flags.ts

@@ -0,0 +1,269 @@
+import { AssistantClient } from "../lib/assistant-client.js";
+import {
+  formatAssistantLookupError,
+  lookupAssistantByIdentifier,
+} from "../lib/assistant-config.js";
+
+type FeatureFlagEntry = {
+  key: string;
+  label: string;
+  enabled: boolean;
+  defaultEnabled: boolean;
+  description: string;
+};
+
+type FlagsResponse = {
+  flags: FeatureFlagEntry[];
+};
+
+function pad(s: string, w: number): string {
+  return s + " ".repeat(Math.max(0, w - s.length));
+}
+
+function printFlagTable(flags: FeatureFlagEntry[]): void {
+  const headers = {
+    key: "KEY",
+    enabled: "ENABLED",
+    default: "DEFAULT",
+    label: "LABEL",
+  };
+
+  const rows = flags
+    .slice()
+    .sort((a, b) => a.key.localeCompare(b.key))
+    .map((f) => ({
+      key: f.enabled !== f.defaultEnabled ? `* ${f.key}` : `  ${f.key}`,
+      enabled: String(f.enabled),
+      default: String(f.defaultEnabled),
+      label: f.label,
+    }));
+
+  const all = [headers, ...rows];
+  const colWidths = {
+    key: Math.max(...all.map((r) => r.key.length)),
+    enabled: Math.max(...all.map((r) => r.enabled.length)),
+    default: Math.max(...all.map((r) => r.default.length)),
+    label: Math.max(...all.map((r) => r.label.length)),
+  };
+
+  const formatRow = (r: typeof headers) =>
+    `${pad(r.key, colWidths.key)}  ${pad(r.enabled, colWidths.enabled)}  ${pad(r.default, colWidths.default)}  ${r.label}`;
+
+  console.log(formatRow(headers));
+  console.log(
+    `${"-".repeat(colWidths.key)}  ${"-".repeat(colWidths.enabled)}  ${"-".repeat(colWidths.default)}  ${"-".repeat(colWidths.label)}`,
+  );
+  for (const row of rows) {
+    console.log(formatRow(row));
+  }
+  console.log("");
+  console.log("* = overridden (differs from default)");
+}
+
+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("");
+  console.log("Subcommands:");
+  console.log("  (none)              List all feature flags in a table");
+  console.log("  get <key>           Show details for a single flag");
+  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 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(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(assistantId ? { assistantId } : undefined);
+  } catch {
+    throw new Error(
+      assistantName
+        ? `No assistant found matching '${assistantName}'.`
+        : "No assistant found. Hatch one with 'vellum hatch' first.",
+    );
+  }
+}
+
+function rethrowFetchError(err: unknown): never {
+  if (
+    err instanceof TypeError &&
+    (err.message.includes("fetch") || err.message.includes("connect"))
+  ) {
+    throw new Error(
+      "Could not reach the assistant gateway. Is it running? Try 'vellum wake'.",
+    );
+  }
+  throw err;
+}
+
+async function listFlags(assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  let res: Response;
+  try {
+    res = await client.get("/feature-flags");
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to fetch flags: HTTP ${res.status} ${body}`.trim());
+  }
+  const data = (await res.json()) as FlagsResponse;
+  if (data.flags.length === 0) {
+    console.log("No feature flags found.");
+    return;
+  }
+  printFlagTable(data.flags);
+}
+
+async function getFlag(key: string, assistantName?: string): Promise<void> {
+  const client = createClient(assistantName);
+  let res: Response;
+  try {
+    res = await client.get("/feature-flags");
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to fetch flags: HTTP ${res.status} ${body}`.trim());
+  }
+  const data = (await res.json()) as FlagsResponse;
+  const flag = data.flags.find((f) => f.key === key);
+  if (!flag) {
+    throw new Error(`Flag "${key}" not found.`);
+  }
+  console.log(`Key:            ${flag.key}`);
+  console.log(`Enabled:        ${flag.enabled}`);
+  console.log(`Default:        ${flag.defaultEnabled}`);
+  console.log(`Description:    ${flag.description || "(none)"}`);
+}
+
+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 });
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to set flag: HTTP ${res.status} ${body}`.trim());
+  }
+  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);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const assistantName = extractAssistantFlag(args);
+
+  const subcommand = args[0];
+
+  if (!subcommand) {
+    await listFlags(assistantName);
+    return;
+  }
+
+  if (subcommand === "get") {
+    const key = args[1];
+    if (!key) {
+      console.error("Usage: vellum flags get <key>");
+      process.exit(1);
+    }
+    await getFlag(key, assistantName);
+    return;
+  }
+
+  if (subcommand === "set") {
+    const key = args[1];
+    const rawValue = args[2];
+    if (!key || rawValue === undefined) {
+      console.error("Usage: vellum flags set <key> <true|false>");
+      process.exit(1);
+    }
+    if (rawValue !== "true" && rawValue !== "false") {
+      console.error(`Invalid value "${rawValue}". Must be "true" or "false".`);
+      process.exit(1);
+    }
+    await setFlag(key, rawValue === "true", assistantName);
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printHelp();
+  process.exit(1);
+}

package/src/commands/gateway/token.ts

@@ -0,0 +1,73 @@
+import {
+  lookupAssistantByIdentifier,
+  formatAssistantLookupError,
+} from "../../lib/assistant-config.js";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+} from "../../lib/guardian-token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum gateway token <subcommand> <assistantId>");
+  console.log("");
+  console.log("Manage gateway authentication tokens.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  get       Print the current guardian access token");
+  console.log("  refresh   Refresh an expired access token and print it");
+}
+
+export async function gatewayToken(): Promise<void> {
+  const args = process.argv.slice(4);
+  const subcommand = args[0];
+
+  if (subcommand === "--help" || subcommand === "-h" || !subcommand) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (subcommand !== "get" && subcommand !== "refresh") {
+    console.error(`Unknown subcommand: ${subcommand}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  const assistantId = args[1];
+  if (!assistantId) {
+    console.error("Missing required argument: <assistantId>");
+    printUsage();
+    process.exit(1);
+  }
+
+  const result = lookupAssistantByIdentifier(assistantId);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(assistantId, result));
+    process.exit(1);
+  }
+  const entry = result.entry;
+
+  const tokenData = loadGuardianToken(entry.assistantId);
+  if (!tokenData) {
+    console.error("No guardian token found for this assistant.");
+    process.exit(1);
+  }
+
+  if (subcommand === "get") {
+    console.log(tokenData.accessToken);
+    return;
+  }
+
+  const gatewayUrl = entry.localUrl || entry.runtimeUrl;
+  if (!gatewayUrl) {
+    console.error("No gateway URL found for this assistant.");
+    process.exit(1);
+  }
+
+  const refreshed = await refreshGuardianToken(gatewayUrl, entry.assistantId);
+  if (!refreshed) {
+    console.error("Failed to refresh guardian token.");
+    process.exit(1);
+  }
+
+  console.log(refreshed.accessToken);
+}

package/src/commands/gateway.ts

@@ -0,0 +1,29 @@
+import { gatewayToken } from "./gateway/token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum gateway <subcommand>");
+  console.log("");
+  console.log("Gateway management commands.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  token    Manage gateway authentication tokens");
+}
+
+export async function gateway(): Promise<void> {
+  const args = process.argv.slice(3);
+  const subcommand = args[0];
+
+  if (subcommand === "--help" || subcommand === "-h" || !subcommand) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (subcommand === "token") {
+    await gatewayToken();
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printUsage();
+  process.exit(1);
+}

package/src/commands/logs.ts

@@ -4,8 +4,12 @@ import { createInterface } from "readline";
 import { watch } from "fs";
 import { join } from "path";
 
-import { resolveAssistant } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  extractHostFromUrl,
+  resolveAssistant,
+  resolveCloud,
+  type AssistantEntry,
+} from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getLogDir } from "../lib/xdg-log";
 import { execOutput } from "../lib/step-runner";
@@ -112,13 +116,6 @@ function parseArgs(): LogsArgs {
 
 // ── Helpers ─────────────────────────────────────────────────────
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) return entry.cloud;
-  if (entry.project) return "gcp";
-  if (entry.sshUser) return "custom";
-  return "local";
-}
-
 /**
  * Parse a relative time string like "10m", "2h", "30s" into a Date.
  * Returns null if the string doesn't look like a relative time.
@@ -494,15 +491,6 @@ async function showGcpLogs(
   }
 }
 
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
 async function showCustomLogs(
   entry: AssistantEntry,
   opts: LogsArgs,

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("");
+}