@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/src/commands/pair.ts

@@ -31,6 +31,7 @@ import { extractFlag } from "../lib/arg-utils.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import {
   formatAssistantLookupError,
+  formatAssistantReference,
   lookupAssistantByIdentifier,
   resolveAssistant,
   type AssistantEntry,
@@ -40,6 +41,7 @@ import {
   getClientRegistrationHeaders,
 } from "../lib/client-identity.js";
 import { GATEWAY_PORT } from "../lib/constants.js";
+import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
   formatFeatureFlagGateMessage,
   isAssistantFeatureFlagEnabled,
@@ -47,6 +49,7 @@ import {
 } from "../lib/feature-flags.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
 import { isLoopbackUrl, loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { formatWebApproveFailure, parseGatewayErrorCode } from "../lib/pair.js";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
 
 function assistantDisplayName(entry: AssistantEntry): string {
@@ -89,7 +92,8 @@ ARGUMENTS:
 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)
+    --label <name>   Human label for this pairing (echoed in the output; with
+                    --qr --app it also names the assistant in the connect link)
     --web            Create a browser pairing URL for remote web access
     --web-approve <code>
                     Approve a browser pairing code shown by /assistant/pair
@@ -100,8 +104,10 @@ OPTIONS:
                     loopback or non-https URLs.
     --app            With --qr: encode the QR as a vellum-assistant://connect
                     link that opens the Vellum iOS app directly (the plain
-                    https pairing URL is printed as a fallback). Requires an
-                    app build with the connect handler installed on the phone.
+                    https pairing URL is printed as a fallback). The link
+                    carries the assistant's name (--label overrides it) so the
+                    app can label the pairing. Requires an app build with the
+                    connect handler installed on the phone.
     --app-scheme <scheme>
                     URL scheme for --app links (default: vellum-assistant;
                     dev/staging app builds use vellum-assistant-dev /
@@ -138,33 +144,40 @@ const DEFAULT_APP_CONNECT_SCHEME = "vellum-assistant";
 
 /**
  * Compose the custom-scheme link the iOS app's connect handler accepts:
- * `<scheme>://connect?url=<base>&code=<device code>`. The app persists the
- * base as its self-hosted server and opens the pair page with the code.
+ * `<scheme>://connect?url=<base>&code=<device code>[&name=<label>]`. The app
+ * persists the base (and the label, when present) as its self-hosted server
+ * and opens the pair page with the code.
  */
 export function buildAppConnectUrl(
   scheme: string,
   baseUrl: string,
   deviceCode: string,
+  name?: string,
 ): string {
   const params = new URLSearchParams({ url: baseUrl, code: deviceCode });
-  return `${scheme}://connect?${params.toString()}`;
+  if (name) {
+    params.set("name", name);
+  }
+  // Percent-encode spaces: URLSearchParams form-encodes them as `+`, which
+  // the app's Foundation URLComponents parser keeps as a literal plus.
+  const query = params.toString().replace(/\+/g, "%20");
+  return `${scheme}://connect?${query}`;
 }
 
 /**
  * POST a JSON body to a loopback gateway route, exiting with a clear message
- * when the gateway is unreachable or answers non-2xx. Every pairing subcommand
- * talks to the gateway this way, so the reachability + HTTP-error handling has
- * a single home.
+ * when the gateway is unreachable. Non-2xx responses are returned to the
+ * caller; use {@link gatewayPostOrExit} unless the call site prints its own
+ * HTTP-error diagnostics.
  */
-async function gatewayPostOrExit(
+async function gatewayPost(
   gatewayUrl: string,
   path: string,
   body: unknown,
   headers?: Record<string, string>,
 ): Promise<Response> {
-  let response: Response;
   try {
-    response = await loopbackSafeFetch(`${gatewayUrl}${path}`, {
+    return await loopbackSafeFetch(`${gatewayUrl}${path}`, {
       method: "POST",
       headers: { "Content-Type": "application/json", ...headers },
       body: JSON.stringify(body),
@@ -177,7 +190,24 @@ async function gatewayPostOrExit(
     console.error("Is the assistant running? Try `vellum wake`.");
     process.exit(1);
   }
+}
+
+/**
+ * {@link gatewayPost}, but also exiting with a generic message on non-2xx.
+ * Every pairing subcommand talks to the gateway this way, so the reachability
+ * + HTTP-error handling has a single home.
+ */
+async function gatewayPostOrExit(
+  gatewayUrl: string,
+  path: string,
+  body: unknown,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  return exitOnHttpError(await gatewayPost(gatewayUrl, path, body, headers));
+}
 
+/** Exit with a generic HTTP-error message on non-2xx; pass 2xx through. */
+async function exitOnHttpError(response: Response): Promise<Response> {
   if (!response.ok) {
     const errorBody = await response.text().catch(() => "");
     console.error(
@@ -185,7 +215,6 @@ async function gatewayPostOrExit(
     );
     process.exit(1);
   }
-
   return response;
 }
 
@@ -206,18 +235,32 @@ async function createRemoteWebPairingChallenge(
 }
 
 /**
- * Approve a pending pairing challenge by its user code — the local-presence
- * proof for the device-code flow. Shared by `--web-approve` and `--qr` (which
- * approves the challenge it just minted so one scan completes pairing).
+ * Approve a pending pairing challenge by its user code, the local-presence
+ * proof for the device-code flow. Single owner of the pairing-verification
+ * route and request body: `--qr` approves via {@link approveRemoteWebPairing}
+ * (generic exit on non-2xx), while `--web-approve` calls this directly to
+ * inspect rejections and print mismatch diagnostics (see
+ * {@link formatWebApproveFailure}).
+ */
+async function postPairingVerification(
+  gatewayUrl: string,
+  userCode: string,
+): Promise<Response> {
+  return gatewayPost(gatewayUrl, "/v1/remote-web/pairing-verification", {
+    userCode,
+  } satisfies RemoteWebPairingVerificationRequest);
+}
+
+/**
+ * Approve the challenge `--qr` just minted so one scan completes pairing,
+ * exiting with a generic message on non-2xx.
  */
 async function approveRemoteWebPairing(
   gatewayUrl: string,
   userCode: string,
 ): Promise<RemoteWebPairingVerificationResponse> {
-  const response = await gatewayPostOrExit(
-    gatewayUrl,
-    "/v1/remote-web/pairing-verification",
-    { userCode } satisfies RemoteWebPairingVerificationRequest,
+  const response = await exitOnHttpError(
+    await postPairingVerification(gatewayUrl, userCode),
   );
   return (await response.json()) as RemoteWebPairingVerificationResponse;
 }
@@ -399,7 +442,26 @@ export async function pair(): Promise<void> {
   if (webApproveCode) {
     await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
 
-    const result = await approveRemoteWebPairing(mintUrl, webApproveCode);
+    // Rejections are diagnosed here rather than by exitOnHttpError: a
+    // rejected code must name the gateway that was asked, or an
+    // assistant/environment mismatch is indistinguishable from a typo.
+    const response = await postPairingVerification(mintUrl, webApproveCode);
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      const diagnostic = formatWebApproveFailure(
+        mintUrl,
+        formatAssistantReference(entry),
+        getCurrentEnvironment().name,
+        parseGatewayErrorCode(errorBody),
+      );
+      console.error(
+        diagnostic ??
+          `Error: HTTP ${response.status}: ${errorBody || response.statusText}`,
+      );
+      process.exit(1);
+    }
+    const result =
+      (await response.json()) as RemoteWebPairingVerificationResponse;
     if (jsonOutput) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -502,6 +564,7 @@ export async function pair(): Promise<void> {
           appSchemeOverride ?? DEFAULT_APP_CONNECT_SCHEME,
           qrBaseUrl,
           challenge.deviceCode,
+          label || assistantDisplayName(entry),
         )
       : null;
 

package/src/commands/tunnel.ts

@@ -1,15 +1,26 @@
 import { join } from "path";
 
-import { resolveAssistant, type AssistantEntry } from "../lib/assistant-config";
+import {
+  formatAssistantReference,
+  loadAllAssistants,
+  resolveTargetAssistant,
+  type AssistantEntry,
+} from "../lib/assistant-config";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
-import { GATEWAY_PORT } from "../lib/constants.js";
 import {
-  isAssistantFeatureFlagEnabled,
-  WEB_REMOTE_INGRESS_FLAG,
-} from "../lib/feature-flags.js";
+  getDefaultWorkspaceDir,
+  saveNgrokDomain,
+} from "../lib/ingress-config.js";
+import {
+  ensureTunnelEdge,
+  formatEdgeMode,
+  type TunnelEdge,
+} from "../lib/nginx-ingress.js";
 import { runNgrokTunnel } from "../lib/ngrok";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
 import { runTailscaleTunnel } from "../lib/tailscale-tunnel.js";
+import { parseGatewayPortFromEntryUrls } from "./nginx-ingress.js";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
 type TunnelProvider = (typeof VALID_PROVIDERS)[number];
@@ -19,12 +30,17 @@ const DEFAULT_PROVIDER: TunnelProvider = "vellum";
 interface TunnelArgs {
   assistantName: string | null;
   provider: TunnelProvider;
+  domain: string | null;
+  clearDomain: boolean;
 }
 
+const FLAGS_WITH_VALUES = ["--provider", "--domain"] as const;
+
 function parseArgs(): TunnelArgs {
   const args = process.argv.slice(3);
-  let assistantName: string | null = null;
   let provider: TunnelProvider = DEFAULT_PROVIDER;
+  let domain: string | null = null;
+  let clearDomain = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -41,6 +57,13 @@ function parseArgs(): TunnelArgs {
         "enabling webhook integrations (Telegram, Twilio, etc.) to reach the assistant.",
       );
       console.log("");
+      console.log(
+        "The tunnel always fronts the local nginx edge, which is started automatically.",
+      );
+      console.log(
+        "nginx must be installed (macOS: brew install nginx, Linux: sudo apt install nginx).",
+      );
+      console.log("");
       console.log("Arguments:");
       console.log(
         "  <name>                        Name of the assistant (defaults to active or only local)",
@@ -50,6 +73,18 @@ function parseArgs(): TunnelArgs {
       console.log(
         `  --provider <provider>         Tunnel provider: ${VALID_PROVIDERS.join(", ")} (default: ${DEFAULT_PROVIDER})`,
       );
+      console.log(
+        "  --domain <domain>             Reserved ngrok domain to bind (ngrok provider only).",
+      );
+      console.log(
+        "                                Saved to the workspace config so `vellum wake` restores reuse it.",
+      );
+      console.log(
+        "  --clear-domain                Clear the saved ngrok domain (ngrok provider only) and tunnel",
+      );
+      console.log(
+        "                                without one. Cannot be combined with --domain.",
+      );
       console.log("");
       console.log("Providers:");
       console.log(
@@ -72,8 +107,11 @@ function parseArgs(): TunnelArgs {
       );
       console.log("");
       console.log("Examples:");
-      console.log("  $ vellum tunnel");
       console.log("  $ vellum tunnel --provider ngrok");
+      console.log(
+        "  $ vellum tunnel --provider ngrok --domain my-assistant.ngrok.app",
+      );
+      console.log("  $ vellum tunnel --provider ngrok --clear-domain");
       console.log("  $ vellum tunnel --provider cloudflare");
       console.log("  $ vellum tunnel my-assistant --provider tailscale");
       process.exit(0);
@@ -96,121 +134,194 @@ function parseArgs(): TunnelArgs {
       }
       provider = next as TunnelProvider;
       i++;
+    } else if (arg === "--domain") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error(
+          "Error: --domain requires a value, e.g. --domain my-assistant.ngrok.app",
+        );
+        process.exit(1);
+      }
+      domain = next;
+      i++;
+    } else if (arg === "--clear-domain") {
+      clearDomain = true;
     } else if (arg.startsWith("-")) {
       console.error(`Error: Unknown option '${arg}'.`);
       process.exit(1);
-    } else if (!assistantName) {
-      assistantName = arg;
-    } else {
-      console.error(`Error: Unexpected argument '${arg}'.`);
-      process.exit(1);
     }
   }
 
-  return { assistantName, provider };
+  // Joins all positionals so unquoted multi-word display names resolve as one
+  // identifier (cli/AGENTS.md "Assistant targeting convention").
+  const assistantName =
+    parseAssistantTargetArg(args, FLAGS_WITH_VALUES) ?? null;
+
+  if (domain && provider !== "ngrok") {
+    console.error(
+      `Error: --domain is only supported with --provider ngrok (got '${provider}').`,
+    );
+    process.exit(1);
+  }
+
+  if (clearDomain && provider !== "ngrok") {
+    console.error(
+      `Error: --clear-domain is only supported with --provider ngrok (got '${provider}').`,
+    );
+    process.exit(1);
+  }
+
+  if (clearDomain && domain) {
+    console.error(
+      "Error: --clear-domain cannot be combined with --domain. Pass --domain alone to replace the saved domain.",
+    );
+    process.exit(1);
+  }
+
+  return { assistantName, provider, domain, clearDomain };
 }
 
-function parsePortFromUrl(url: unknown): number | undefined {
-  if (typeof url !== "string" || !url.trim()) return undefined;
-  try {
-    const port = Number(new URL(url).port);
-    return Number.isInteger(port) && port > 0 && port <= 65535
-      ? port
-      : undefined;
-  } catch {
-    return undefined;
+/** A tunnelable assistant plus the gateway port and workspace the edge fronts. */
+interface LocalTunnelTarget {
+  entry: AssistantEntry;
+  gatewayPort: number;
+  workspaceDir: string;
+}
+
+/** Container topologies whose gateway runs on this machine without host `resources`. */
+function isLocalContainerEntry(entry: AssistantEntry): boolean {
+  return entry.cloud === "docker" || entry.cloud === "apple-container";
+}
+
+/**
+ * Map an entry to its local tunnel target, or null when it has no locally
+ * reachable gateway (e.g. platform-hosted). Entries with `resources` carry
+ * their own gateway port and instance workspace. Local container entries
+ * (docker, apple-container) run locally without host resources: their gateway
+ * port comes from localUrl/runtimeUrl and their ingress state lives in the
+ * default workspace, matching the `vellum nginx-ingress` resolution for the
+ * same topology.
+ */
+function toLocalTunnelTarget(entry: AssistantEntry): LocalTunnelTarget | null {
+  if (entry.resources) {
+    return {
+      entry,
+      gatewayPort: entry.resources.gatewayPort,
+      workspaceDir: join(entry.resources.instanceDir, ".vellum", "workspace"),
+    };
   }
+  if (isLocalContainerEntry(entry)) {
+    const gatewayPort = parseGatewayPortFromEntryUrls(entry);
+    if (gatewayPort !== undefined) {
+      return { entry, gatewayPort, workspaceDir: getDefaultWorkspaceDir() };
+    }
+  }
+  return null;
 }
 
-function resolveEntryGatewayPort(entry: AssistantEntry): number {
-  return (
-    entry.resources?.gatewayPort ??
-    parsePortFromUrl(entry.localUrl) ??
-    parsePortFromUrl(entry.runtimeUrl) ??
-    GATEWAY_PORT
-  );
+function describeUntunnelableEntry(entry: AssistantEntry): string {
+  const reference = formatAssistantReference(entry);
+  return entry.cloud === "vellum"
+    ? `Assistant '${reference}' runs on Vellum Cloud and needs no tunnel.`
+    : `Assistant '${reference}' has no locally managed runtime to tunnel.`;
 }
 
-async function shouldPreferNginxIngress(
-  assistantId: string,
-  gatewayPort: number,
-): Promise<boolean> {
-  try {
-    return await isAssistantFeatureFlagEnabled(
-      assistantId,
-      WEB_REMOTE_INGRESS_FLAG,
-      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
+/**
+ * Resolve the assistant whose gateway and workspace the tunnel edge fronts.
+ * Tunnels only make sense for assistants with a local gateway; when the
+ * resolved entry has none (e.g. the active assistant is platform-hosted) and
+ * no name was given, fall back to the sole local target, otherwise exit with
+ * an error naming the local assistants to pass explicitly.
+ */
+function resolveLocalTunnelTarget(
+  assistantName: string | null,
+): LocalTunnelTarget {
+  const entry = resolveTargetAssistant(assistantName ?? undefined);
+
+  const target = toLocalTunnelTarget(entry);
+  if (target) {
+    return target;
+  }
+
+  const localTargets = loadAllAssistants()
+    .map(toLocalTunnelTarget)
+    .filter((local): local is LocalTunnelTarget => local !== null);
+
+  if (!assistantName && localTargets.length === 1) {
+    console.log(
+      `${describeUntunnelableEntry(entry)} Tunneling the local assistant '${formatAssistantReference(localTargets[0].entry)}' instead.`,
     );
-  } catch (err) {
-    throw new Error(
-      `Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag before starting the tunnel. Is the assistant running? Try \`vellum wake\` and retry. ${
-        err instanceof Error ? err.message : String(err)
-      }`,
+    return localTargets[0];
+  }
+
+  console.error(describeUntunnelableEntry(entry));
+  if (localTargets.length === 0) {
+    console.error(
+      "No local assistant found to tunnel. Run `vellum hatch` first.",
+    );
+  } else {
+    console.error(
+      `Pass a local assistant as the name argument: ${localTargets
+        .map((local) => formatAssistantReference(local.entry))
+        .join(", ")}.`,
     );
   }
+  process.exit(1);
 }
 
 export async function tunnel(): Promise<void> {
-  const { assistantName, provider } = parseArgs();
+  const { assistantName, provider, domain, clearDomain } = parseArgs();
 
-  const entry = resolveAssistant(assistantName ?? undefined);
+  if (provider === "vellum") {
+    throw new Error(
+      `Tunnel provider '${provider}' is not yet implemented. ` +
+        `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
+    );
+  }
 
-  if (!entry) {
-    if (assistantName) {
-      console.error(
-        `No assistant instance found with name '${assistantName}'.`,
-      );
-    } else {
-      console.error("No assistant instance found. Run `vellum hatch` first.");
-    }
+  const { entry, gatewayPort, workspaceDir } =
+    resolveLocalTunnelTarget(assistantName);
+
+  if (clearDomain) {
+    saveNgrokDomain(workspaceDir, null);
+    console.log("Cleared the saved ngrok domain from the workspace config.");
+  }
+
+  let edge: TunnelEdge;
+  try {
+    edge = await ensureTunnelEdge({
+      assistantId: entry.assistantId,
+      workspaceDir,
+      gatewayPort,
+    });
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   }
 
-  const resources = entry.resources;
-  const gatewayPort = resolveEntryGatewayPort(entry);
+  console.log(
+    `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port} ` +
+      `(serves ${formatEdgeMode(edge.includesWebApp)}).`,
+  );
+
   const baseTunnelOpts = {
-    port: gatewayPort,
+    port: edge.port,
     assistantId: entry.assistantId,
-    ...(resources
-      ? { workspaceDir: join(resources.instanceDir, ".vellum", "workspace") }
-      : {}),
+    workspaceDir,
   };
 
   if (provider === "ngrok") {
     await runNgrokTunnel({
       ...baseTunnelOpts,
-      preferNginxIngress: await shouldPreferNginxIngress(
-        entry.assistantId,
-        gatewayPort,
-      ),
+      ...(domain ? { domain } : {}),
     });
     return;
   }
 
   if (provider === "cloudflare") {
-    await runCloudflareTunnel({
-      ...baseTunnelOpts,
-      preferNginxIngress: await shouldPreferNginxIngress(
-        entry.assistantId,
-        gatewayPort,
-      ),
-    });
+    await runCloudflareTunnel(baseTunnelOpts);
     return;
   }
 
-  if (provider === "tailscale") {
-    await runTailscaleTunnel({
-      ...baseTunnelOpts,
-      preferNginxIngress: await shouldPreferNginxIngress(
-        entry.assistantId,
-        gatewayPort,
-      ),
-    });
-    return;
-  }
-
-  throw new Error(
-    `Tunnel provider '${provider}' is not yet implemented. ` +
-      `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
-  );
+  await runTailscaleTunnel(baseTunnelOpts);
 }

package/src/commands/upgrade.ts

@@ -72,7 +72,7 @@ import {
   startLocalDaemon,
   stopLocalProcesses,
 } from "../lib/local.js";
-import { maybeStartNgrokTunnel } from "../lib/ngrok.js";
+import { restoreTunnelEdgeAndAutoTunnel } from "../lib/tunnel-edge.js";
 import {
   leaseGuardianToken,
   resetGuardianBootstrap,
@@ -1044,7 +1044,8 @@ async function upgradeLocal(
     ".vellum",
     "workspace",
   );
-  const ngrokChild = await maybeStartNgrokTunnel(
+  const ngrokChild = await restoreTunnelEdgeAndAutoTunnel(
+    entry.assistantId,
     entry.resources.gatewayPort,
     workspaceDir,
   );