@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/src/lib/pair.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure helpers for `vellum pair`'s remote-web approval flow.
+ *
+ * Pairing challenge stores are in-memory per gateway process, so approving a
+ * code against a different assistant or environment than the one that served
+ * the pair page looks identical to a typo'd or expired code. These helpers
+ * turn the gateway's error envelope into a diagnostic that names the gateway
+ * actually asked.
+ */
+
+import { REMOTE_WEB_PAIRING_CODE_TTL_MS } from "@vellumai/service-contracts/remote-web-pairing";
+
+const CODE_TTL_MINUTES = Math.round(REMOTE_WEB_PAIRING_CODE_TTL_MS / 60_000);
+
+/**
+ * Extract the `error.code` from a gateway JSON error envelope
+ * (`{"error":{"code":...,"message":...}}`). Returns null when the body is not
+ * JSON or carries no string code.
+ */
+export function parseGatewayErrorCode(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as { error?: { code?: unknown } };
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Diagnostic for a failed `--web-approve`, naming which gateway rejected the
+ * code and hinting at cross-assistant / cross-environment mismatches. Returns
+ * null for error codes this helper doesn't recognize, so the caller falls
+ * back to the generic HTTP error text. `assistantReference` should carry the
+ * stable assistant ID (see `formatAssistantReference`); `envName` should be
+ * the effective environment actually used (see `getCurrentEnvironment`).
+ */
+export function formatWebApproveFailure(
+  gatewayUrl: string,
+  assistantReference: string,
+  envName: string,
+  errorCode: string | null,
+): string | null {
+  if (errorCode !== "INVALID_USER_CODE" && errorCode !== "EXPIRED_USER_CODE") {
+    return null;
+  }
+  const rejection =
+    errorCode === "EXPIRED_USER_CODE"
+      ? "Pairing code expired on"
+      : "No such pairing code on";
+  return [
+    `${rejection} ${gatewayUrl} (assistant "${assistantReference}", environment "${envName}").`,
+    `Codes are minted by the gateway that serves the pair page, expire after ${CODE_TTL_MINUTES} minutes, and are single-use.`,
+    "If the pair page came from a different assistant or environment (e.g. the desktop app's), re-run with that environment's VELLUM_ENVIRONMENT and that assistant's name.",
+  ].join("\n");
+}

package/src/lib/platform-client.ts

@@ -9,7 +9,7 @@ import {
 import { join, dirname } from "path";
 
 import { getLockfilePlatformBaseUrl } from "./assistant-config.js";
-import { getConfigDir } from "./environments/paths.js";
+import { getConfigDir, getConfigDirs } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
 
@@ -55,11 +55,14 @@ export function getWebUrl(): string {
 }
 
 export function readPlatformToken(): string | null {
-  try {
-    return readFileSync(getPlatformTokenPath(), "utf-8").trim();
-  } catch {
-    return null;
+  for (const dir of getConfigDirs(getCurrentEnvironment())) {
+    try {
+      return readFileSync(join(dir, "platform-token"), "utf-8").trim();
+    } catch {
+      // Try the next compatible location.
+    }
   }
+  return null;
 }
 
 export function savePlatformToken(token: string): void {

package/src/lib/tailscale-tunnel.ts

@@ -6,7 +6,6 @@ import {
   getDefaultWorkspaceDir,
   saveIngressUrl,
 } from "./ingress-config.js";
-import { resolveTunnelTargetPort } from "./nginx-ingress.js";
 
 // ── Tailscale CLI discovery + invocation ────────────────────────────────────
 
@@ -161,12 +160,10 @@ export function shouldClearIngressUrl(
 // ── Tailscale serve lifecycle ───────────────────────────────────────────────
 
 export interface RunTailscaleTunnelOptions {
-  /** Gateway port to serve. Defaults to the global GATEWAY_PORT. */
+  /** Local edge port to serve. Defaults to the global GATEWAY_PORT. */
   port?: number;
   /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
   workspaceDir?: string;
-  /** Prefer nginx ingress over the gateway port when it is running. */
-  preferNginxIngress?: boolean;
   /** Lockfile entry to mirror the ingress URL onto (`ingressUrl`). */
   assistantId?: string;
 }
@@ -174,7 +171,6 @@ export interface RunTailscaleTunnelOptions {
 export interface TailscaleServeInfo {
   publicUrl: string;
   port: number;
-  viaIngress: boolean;
   binary: string;
   workspaceDir: string;
 }
@@ -210,12 +206,7 @@ export async function startTailscaleServe(
   const publicUrl = `https://${hostname}`;
 
   const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
-  const gatewayPort = opts.port ?? GATEWAY_PORT;
-  const { port, viaIngress } = resolveTunnelTargetPort(
-    workspaceDir,
-    gatewayPort,
-    { preferNginxIngress: opts.preferNginxIngress === true },
-  );
+  const port = opts.port ?? GATEWAY_PORT;
 
   const serveResult = deps.run(binary, ["serve", "--bg", String(port)]);
   if (serveResult.status !== 0) {
@@ -224,7 +215,7 @@ export async function startTailscaleServe(
 
   saveIngressUrl(workspaceDir, publicUrl, opts.assistantId);
 
-  return { publicUrl, port, viaIngress, binary, workspaceDir };
+  return { publicUrl, port, binary, workspaceDir };
 }
 
 /**
@@ -252,12 +243,10 @@ export async function runTailscaleTunnel(
   const deps = realTailscaleDeps();
 
   console.log("Setting up tailscale serve...");
-  const { publicUrl, port, viaIngress, binary, workspaceDir } =
-    await startTailscaleServe(opts, deps);
-
-  if (viaIngress) {
-    console.log(`nginx ingress detected — serving it on 127.0.0.1:${port}.`);
-  }
+  const { publicUrl, port, binary, workspaceDir } = await startTailscaleServe(
+    opts,
+    deps,
+  );
 
   console.log("");
   console.log(`Tunnel established: ${publicUrl}`);

package/src/lib/tunnel-edge.ts

@@ -0,0 +1,114 @@
+import type { ChildProcess } from "child_process";
+
+import { loadRawConfig } from "./ingress-config.js";
+import {
+  ensureTunnelEdge,
+  formatEdgeMode,
+  isIngressRunning,
+  readIngressState,
+  type TunnelEdge,
+} from "./nginx-ingress.js";
+import { hasWebhookIntegrations, maybeStartNgrokTunnel } from "./ngrok.js";
+
+/**
+ * Retry policy for the flag lookup inside the tunnel-edge restore. The gateway
+ * has typically been up for milliseconds at this point and answers
+ * `503 {"status":"starting"}` (or refuses connections) until its startup
+ * completes, so a single lookup races it.
+ */
+export const WEB_INGRESS_FLAG_RETRY = {
+  attempts: 15,
+  intervalMs: 2_000,
+};
+
+/**
+ * Whether the workspace ingress config wants the remote-web edge: explicitly
+ * enabled with a saved public URL.
+ */
+function wantsWebIngress(config: Record<string, unknown>): boolean {
+  const ingress = config.ingress as
+    { enabled?: unknown; publicBaseUrl?: unknown } | undefined;
+  return (
+    ingress?.enabled === true &&
+    typeof ingress.publicBaseUrl === "string" &&
+    ingress.publicBaseUrl.trim() !== ""
+  );
+}
+
+/**
+ * Whether anything wants the nginx edge: webhook integrations or the
+ * remote-web ingress config. One config read covers both checks;
+ * `maybeStartNgrokTunnel` keeps its own webhook gate for its other callers.
+ */
+function wantsTunnelEdge(workspaceDir: string): boolean {
+  try {
+    const config = loadRawConfig(workspaceDir);
+    return hasWebhookIntegrations(config) || wantsWebIngress(config);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bring the nginx edge back up after a wake or local upgrade and point the
+ * webhook auto-tunnel at it. The edge is wanted when webhook integrations are
+ * configured or the workspace ingress config is enabled with a saved public
+ * URL; `ensureTunnelEdge` picks SPA vs webhooks-only mode off the
+ * `web-remote-ingress` flag, retrying the lookup through the gateway's startup
+ * window. A healthy edge whose recorded state already targets the requested
+ * gateway port is reused without the flag lookup or the `remoteWebConfigHash`
+ * comparison `startRemoteWebIngress` performs; both flag-driven mode drift
+ * and injected-config drift (a renamed assistant, a changed hub URL) are
+ * repaired by the next explicit `vellum tunnel` or `vellum nginx-ingress up`,
+ * not by background wakes. Edge failures warn
+ * (with the error's install or diagnostic text) and fall back to tunneling the
+ * gateway port directly, which `maybeStartNgrokTunnel` only does when webhook
+ * integrations are configured, so webhook channels on nginx-less machines
+ * keep working, and the caller never fails because of edge problems.
+ *
+ * Returns the spawned ngrok child (for PID tracking) or null.
+ */
+export async function restoreTunnelEdgeAndAutoTunnel(
+  assistantId: string,
+  gatewayPort: number,
+  workspaceDir: string,
+): Promise<ChildProcess | null> {
+  let tunnelTargetPort = gatewayPort;
+  if (wantsTunnelEdge(workspaceDir)) {
+    const recorded = isIngressRunning(workspaceDir)
+      ? readIngressState(workspaceDir)
+      : null;
+    let edge: TunnelEdge | null = null;
+    if (recorded !== null && recorded.gatewayPort === gatewayPort) {
+      edge = {
+        port: recorded.listenPort,
+        started: false,
+        includesWebApp: recorded.includeWebApp,
+      };
+    } else {
+      try {
+        edge = await ensureTunnelEdge({
+          assistantId,
+          workspaceDir,
+          gatewayPort,
+          flagRetry: WEB_INGRESS_FLAG_RETRY,
+        });
+      } catch (err) {
+        console.warn(
+          `   Could not restore the tunnel edge: ${
+            err instanceof Error ? err.message : String(err)
+          } Bring it up manually with \`vellum nginx-ingress up\`.`,
+        );
+      }
+    }
+    if (edge) {
+      tunnelTargetPort = edge.port;
+      console.log(
+        `   Tunnel edge ${edge.started ? "started" : "already running"} on 127.0.0.1:${edge.port} (${formatEdgeMode(
+          edge.includesWebApp,
+        )}).`,
+      );
+    }
+  }
+  return maybeStartNgrokTunnel(tunnelTargetPort, workspaceDir);
+}

package/src/lib/xdg-log.ts

@@ -11,7 +11,7 @@ import {
 } from "fs";
 import { join } from "path";
 
-import { getConfigDir } from "./environments/paths.js";
+import { getLogDir as getEnvironmentLogDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 
 /** Regex matching pino-pretty's short time prefix, e.g. `[12:07:37.467] `. */
@@ -24,7 +24,7 @@ const PINO_TIME_RE = /^\[\d{2}:\d{2}:\d{2}\.\d{3}\]\s*/;
  * non-production environments use `$XDG_CONFIG_HOME/vellum-<env>/logs`.
  */
 export function getLogDir(): string {
-  return join(getConfigDir(getCurrentEnvironment()), "logs");
+  return getEnvironmentLogDir(getCurrentEnvironment());
 }
 
 /** Open (or create) a log file in append mode, returning the file descriptor.