@vellumai/cli 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/AGENTS.md

@@ -63,7 +63,7 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
-**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Swift clients, the Electron main process, the host-mode assistant, and the CLI (see `clients/shared/App/Auth/DeviceIdStore.swift` and `apps/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
+**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Electron main process, the host-mode assistant, and the CLI (see `clients/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
 
 ## Process liveness
 

package/README.md

@@ -4,7 +4,7 @@ CLI tools for provisioning and managing Vellum assistant instances.
 
 ## Installation
 
-This package is used internally by the [`vel`](https://github.com/vellum-ai/vellum-assistant-platform/tree/main/vel) CLI. You typically don't need to install it directly.
+This package is used internally by the `vel` CLI. You typically don't need to install it directly.
 
 To run it standalone with [Bun](https://bun.sh):
 

package/node_modules/@vellumai/environments/src/seeds.ts

@@ -25,11 +25,8 @@ function portBlock(base: number): PortMap {
 }
 
 /**
- * Built-in environment definitions and the TS-side source of truth for the
- * set of known environment names. The Swift client mirrors this list in
- * `clients/macos/vellum-assistant/App/VellumEnvironment.swift`; since Swift
- * can't import TypeScript, drift between the two is caught at test time by
- * `cli/src/__tests__/env-drift.test.ts`.
+ * Built-in environment definitions and the source of truth for the
+ * set of known environment names.
  *
  * Custom environments via a user config file are a future phase — see the
  * "Coexisting environments" design doc. Until then, a call site that needs a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.9.0",
+  "version": "0.10.0-dev.202606192226.8ed8a6a",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/backup.test.ts

@@ -245,6 +245,69 @@ describe("vellum backup <local>: guardian bootstrap secret", () => {
   });
 });
 
+describe("vellum backup: --export-timeout flag", () => {
+  test("rejects a non-numeric value before any lookup", async () => {
+    setArgv("my-local", "--export-timeout", "soon");
+
+    const consoleErrorSpy = spyOn(console, "error").mockImplementation(
+      () => undefined,
+    );
+    try {
+      await expect(backup()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("--export-timeout must be a positive number"),
+      );
+      expect(findAssistantByNameMock).not.toHaveBeenCalled();
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  test("rejects a non-positive value", async () => {
+    setArgv("my-local", "--export-timeout", "0");
+
+    const consoleErrorSpy = spyOn(console, "error").mockImplementation(
+      () => undefined,
+    );
+    try {
+      await expect(backup()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("--export-timeout must be a positive number"),
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  test("accepts a valid override and completes the local export", async () => {
+    const localEntry = {
+      assistantId: "local-assistant",
+      runtimeUrl: "http://127.0.0.1:7830",
+      cloud: "local",
+      guardianBootstrapSecret: "bootstrap-secret-value",
+    } satisfies assistantConfig.AssistantEntry;
+    findAssistantByNameMock.mockReturnValue(localEntry);
+    setArgv(
+      "my-local",
+      "--export-timeout",
+      "600",
+      "--output",
+      "/tmp/local-backup.vbundle",
+    );
+
+    globalThis.fetch = mock(async () => {
+      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    }) as unknown as typeof globalThis.fetch;
+
+    await backup();
+
+    expect(writeFileSyncMock).toHaveBeenCalledTimes(1);
+    expect(writeFileSyncMock.mock.calls[0]![0]).toBe(
+      "/tmp/local-backup.vbundle",
+    );
+  });
+});
+
 describe("vellum backup <platform-managed>: GCS happy path", () => {
   test("requests upload URL → kicks off runtime export → polls → downloads from GCS → writes file", async () => {
     findAssistantByNameMock.mockReturnValue(VELLUM_ENTRY);

package/src/__tests__/nginx-ingress.test.ts

@@ -127,8 +127,6 @@ describe("buildIngressNginxConfig", () => {
       "location = /v1/pair/ { return 404; }",
       "location = /v1/pair/web-init { return 404; }",
       "location = /v1/pair/web-init/ { return 404; }",
-      "location = /v1/remote-web/pairing-challenge { return 404; }",
-      "location = /v1/remote-web/pairing-challenge/ { return 404; }",
       "location = /v1/devices { return 404; }",
       "location = /v1/devices/ { return 404; }",
       "location = /v1/devices/revoke { return 404; }",

package/src/__tests__/pair.test.ts

@@ -268,4 +268,203 @@ describe("pair command", () => {
     const out = JSON.parse(logs.join("\n"));
     expect(out.gatewayUrl).toBe(OVERRIDE);
   });
+
+  test("--web creates a browser pairing URL without printing tokens", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri:
+              "https://abc123.ngrok.app/assistant-123/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+            intervalSeconds: 5,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--web",
+      "--url",
+      "https://abc123.ngrok.app/assistant-123/assistant/",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(calls).toHaveLength(2);
+    expect(calls[1][0]).toBe(`${LOCAL_URL}/v1/remote-web/pairing-challenge`);
+    expect(JSON.parse(calls[1][1]?.body as string)).toEqual({
+      publicBaseUrl: "https://abc123.ngrok.app/assistant-123",
+    });
+
+    const out = JSON.parse(logs.join("\n"));
+    expect(out).toEqual({
+      pairUrl:
+        "https://abc123.ngrok.app/assistant-123/assistant/pair#device_code=device-code",
+      userCode: "ABCD-EFGH",
+      verificationUri: "https://abc123.ngrok.app/assistant-123/assistant/pair",
+      expiresAt: "2026-06-04T00:10:00.000Z",
+      expiresInSeconds: 600,
+    });
+    expect(logs.join("\n")).not.toContain("access");
+    expect(logs.join("\n")).not.toContain("refresh");
+  });
+
+  test("--web refuses when the web remote ingress feature flag is off", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      return new Response(
+        JSON.stringify({
+          flags: [{ key: "web-remote-ingress", enabled: false }],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--web",
+      "--url",
+      "https://abc123.ngrok.app",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("web-remote-ingress");
+    expect(calls).toHaveLength(1);
+    expect(calls[0][0]).toBe(
+      `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`,
+    );
+  });
+
+  test("--web-approve approves a browser pairing code over loopback", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            runtimeUrl: LOCAL_URL,
+            localUrl: LOCAL_URL,
+            cloud: "local",
+          },
+        ],
+        activeAssistant: "pair-test",
+      }),
+    );
+
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://abc123.ngrok.app/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--web-approve",
+      "ABCD-EFGH",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(calls).toHaveLength(2);
+    expect(calls[1][0]).toBe(`${LOCAL_URL}/v1/remote-web/pairing-verification`);
+    expect(JSON.parse(calls[1][1]?.body as string)).toEqual({
+      userCode: "ABCD-EFGH",
+    });
+    expect(JSON.parse(logs.join("\n"))).toEqual({
+      status: "approved",
+      verificationUri: "https://abc123.ngrok.app/assistant/pair",
+      expiresAt: "2026-06-04T00:10:00.000Z",
+    });
+  });
 });

package/src/__tests__/workos-pkce.test.ts

@@ -84,10 +84,10 @@ describe("buildAuthorizeUrl", () => {
   });
 
   test("login hint is forwarded", () => {
-    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
-    const url = new URL(buildAuthorizeUrl({ ...base, loginHint: "a@b.co" }));
-    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
-    expect(url.searchParams.get("login_hint")).toBe("a@b.co");
+    const url = new URL(
+      buildAuthorizeUrl({ ...base, loginHint: "user@example.com" }),
+    );
+    expect(url.searchParams.get("login_hint")).toBe("user@example.com");
 
     const noHint = new URL(buildAuthorizeUrl(base));
     expect(noHint.searchParams.has("login_hint")).toBe(false);

package/src/commands/backup.ts

@@ -18,23 +18,32 @@ import {
 } from "../lib/platform-client.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
+// Default timeout for the runtime-direct export request. Overridable via
+// --export-timeout.
+const DEFAULT_EXPORT_TIMEOUT_MS = 300_000;
+
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum backup <name> [--output <path>]");
+    console.log(
+      "Usage: vellum backup <name> [--output <path>] [--export-timeout <seconds>]",
+    );
     console.log("");
     console.log(
       "Export a backup of a running assistant as a .vbundle archive.",
     );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>              Name of the assistant to back up");
+    console.log("  <name>                   Name of the assistant to back up");
     console.log("");
     console.log("Options:");
-    console.log("  --output <path>     Path to save the .vbundle file");
+    console.log("  --output <path>          Path to save the .vbundle file");
     console.log(
-      "                      (default: ~/.local/share/vellum/backups/<name>-<timestamp>.vbundle)",
+      "                           (default: ~/.local/share/vellum/backups/<name>-<timestamp>.vbundle)",
+    );
+    console.log(
+      `  --export-timeout <secs>  Export request timeout in seconds (default: ${DEFAULT_EXPORT_TIMEOUT_MS / 1000})`,
     );
     console.log("");
     console.log("Examples:");
@@ -42,21 +51,33 @@ export async function backup(): Promise<void> {
     console.log(
       "  vellum backup my-assistant --output ~/Desktop/backup.vbundle",
     );
+    console.log("  vellum backup my-assistant --export-timeout 600");
     process.exit(0);
   }
 
   const name = args[0];
   if (!name || name.startsWith("-")) {
-    console.error("Usage: vellum backup <name> [--output <path>]");
+    console.error(
+      "Usage: vellum backup <name> [--output <path>] [--export-timeout <seconds>]",
+    );
     process.exit(1);
   }
 
-  // Parse --output flag
+  // Parse flags
   let outputArg: string | undefined;
+  let exportTimeoutMs = DEFAULT_EXPORT_TIMEOUT_MS;
   for (let i = 1; i < args.length; i++) {
     if (args[i] === "--output" && args[i + 1]) {
       outputArg = args[i + 1];
-      break;
+    } else if (args[i] === "--export-timeout" && args[i + 1]) {
+      const seconds = Number(args[i + 1]);
+      if (!Number.isFinite(seconds) || seconds <= 0) {
+        console.error(
+          `Error: --export-timeout must be a positive number of seconds (got '${args[i + 1]}').`,
+        );
+        process.exit(1);
+      }
+      exportTimeoutMs = seconds * 1000;
     }
   }
 
@@ -120,7 +141,7 @@ export async function backup(): Promise<void> {
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ description: "CLI backup" }),
-      signal: AbortSignal.timeout(120_000),
+      signal: AbortSignal.timeout(exportTimeoutMs),
     });
 
     // Retry once with a fresh token on 401 — the cached token may be stale
@@ -146,13 +167,15 @@ export async function backup(): Promise<void> {
             "Content-Type": "application/json",
           },
           body: JSON.stringify({ description: "CLI backup" }),
-          signal: AbortSignal.timeout(120_000),
+          signal: AbortSignal.timeout(exportTimeoutMs),
         });
       }
     }
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {
-      console.error("Error: Export request timed out after 2 minutes.");
+      console.error(
+        `Error: Export request timed out after ${exportTimeoutMs / 1000} seconds.`,
+      );
       process.exit(1);
     }
     const msg = err instanceof Error ? err.message : String(err);

package/src/commands/client.ts

@@ -340,7 +340,7 @@ const SPA_BASE = "/assistant/";
  *
  * Resolution order:
  *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
- *   2. Source checkout — walk up from cli/ to find apps/web/dist/
+ *   2. Source checkout — walk up from cli/ to find clients/web/dist/
  */
 function findWebDistDir(): string | null {
   try {
@@ -355,7 +355,7 @@ function findWebDistDir(): string | null {
 
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = path.join(dir, "apps", "web", "dist", "index.html");
+    const candidate = path.join(dir, "clients", "web", "dist", "index.html");
     if (existsSync(candidate)) {
       return path.dirname(candidate);
     }
@@ -367,13 +367,13 @@ function findWebDistDir(): string | null {
 }
 
 /**
- * Locate the apps/web source directory for running the Vite dev server.
+ * Locate the clients/web source directory for running the Vite dev server.
  * Only works from a source checkout (not npm-installed).
  */
 function findWebSourceDir(): string | null {
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = path.join(dir, "apps", "web", "vite.config.ts");
+    const candidate = path.join(dir, "clients", "web", "vite.config.ts");
     if (existsSync(candidate)) {
       return path.dirname(candidate);
     }
@@ -679,7 +679,7 @@ async function runWebInterface(
       `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
         `@vellumai/web assets.\n\n` +
         `  npm/bunx install:   npm install @vellumai/web\n` +
-        `  source checkout:    cd apps/web && VITE_PLATFORM_MODE=false bun run build`,
+        `  source checkout:    cd clients/web && VITE_PLATFORM_MODE=false bun run build`,
     );
     process.exit(1);
   }

package/src/commands/nginx-ingress.ts

@@ -195,7 +195,7 @@ async function up(target: NginxIngressTarget): Promise<void> {
     );
     console.error("");
     console.error("Build the SPA first:");
-    console.error("  cd apps/web && VITE_PLATFORM_MODE=false bun run build");
+    console.error("  cd clients/web && VITE_PLATFORM_MODE=false bun run build");
     console.error("");
     console.error(
       "Or install @vellumai/web so its packaged dist directory is available.",

package/src/commands/pair.ts

@@ -25,6 +25,11 @@ import {
   getClientRegistrationHeaders,
 } from "../lib/client-identity.js";
 import { GATEWAY_PORT } from "../lib/constants.js";
+import {
+  formatFeatureFlagGateMessage,
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
@@ -50,12 +55,17 @@ 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)
+    --web            Create a browser pairing URL for remote web access
+    --web-approve <code>
+                    Approve a browser pairing code shown by /assistant/pair
     --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 --web --url https://abc123.ngrok.app
+    vellum pair --web-approve ABCD-EFGH
     vellum pair --json
 `);
 }
@@ -72,6 +82,71 @@ interface PairResponse {
   refreshAfter?: string;
 }
 
+interface RemoteWebPairingChallengeResponse {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  expiresAt: string;
+  expiresInSeconds: number;
+}
+
+interface RemoteWebPairingApprovalResponse {
+  status: "approved";
+  verificationUri: string;
+  expiresAt: string;
+}
+
+function normalizePublicBaseUrl(value: string): string {
+  const url = new URL(value);
+  url.search = "";
+  url.hash = "";
+  const parts = url.pathname.split("/").filter(Boolean);
+  const assistantIndex = parts.indexOf("assistant");
+  if (assistantIndex >= 0) {
+    parts.splice(assistantIndex);
+  }
+  url.pathname = parts.length ? `/${parts.join("/")}` : "/";
+  return url.toString().replace(/\/+$/, "");
+}
+
+function buildRemoteWebPairingUrl(
+  challenge: RemoteWebPairingChallengeResponse,
+): string {
+  const url = new URL(challenge.verificationUri);
+  url.hash = new URLSearchParams({
+    device_code: challenge.deviceCode,
+  }).toString();
+  return url.toString();
+}
+
+async function assertWebRemoteIngressEnabled(
+  assistantId: string,
+  runtimeUrl: string,
+): Promise<void> {
+  let enabled: boolean;
+  try {
+    enabled = await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl },
+    );
+  } catch (err) {
+    console.error(
+      `Error: could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag. Is the assistant running? Try \`vellum wake\` and retry. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    process.exit(1);
+  }
+
+  if (!enabled) {
+    console.error(
+      `Error: ${formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG)}`,
+    );
+    process.exit(1);
+  }
+}
+
 export async function pair(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
@@ -81,12 +156,27 @@ export async function pair(): Promise<void> {
   }
 
   const jsonOutput = rawArgs.includes("--json");
-  let args = rawArgs.filter((a) => a !== "--json");
+  const webPairing = rawArgs.includes("--web");
+  const webApproval = rawArgs.includes("--web-approve");
+  let args = rawArgs.filter((a) => a !== "--json" && a !== "--web");
 
   const [label, afterLabel] = extractFlag(args, "--label");
-  const [urlOverride, afterUrl] = extractFlag(afterLabel, "--url");
+  const [webApproveCode, afterWebApprove] = extractFlag(
+    afterLabel,
+    "--web-approve",
+  );
+  const [urlOverride, afterUrl] = extractFlag(afterWebApprove, "--url");
   args = afterUrl;
 
+  if (webPairing && webApproveCode) {
+    console.error("Error: use either --web or --web-approve, not both.");
+    process.exit(1);
+  }
+  if (webApproval && !webApproveCode) {
+    console.error("Error: --web-approve requires a pairing code.");
+    process.exit(1);
+  }
+
   // 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
@@ -126,7 +216,7 @@ export async function pair(): Promise<void> {
   // 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)) {
+  if (!urlOverride && !webApproveCode && isLoopbackHost(advertisedUrl)) {
     const lan = getLocalLanIPv4();
     // Use THIS assistant's gateway port (not the global default) — second
     // local instances listen on a different port.
@@ -149,6 +239,126 @@ export async function pair(): Promise<void> {
     process.exit(1);
   }
 
+  if (webApproveCode) {
+    await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
+
+    let response: Response;
+    try {
+      response = await loopbackSafeFetch(
+        `${mintUrl}/v1/remote-web/pairing-verification`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ userCode: webApproveCode }),
+        },
+      );
+    } 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 RemoteWebPairingApprovalResponse;
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log("Remote web pairing approved.");
+    console.log(`Expires: ${result.expiresAt}`);
+    return;
+  }
+
+  if (webPairing) {
+    await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
+
+    let publicBaseUrl: string;
+    try {
+      publicBaseUrl = normalizePublicBaseUrl(advertisedUrl);
+    } catch {
+      console.error(`Error: invalid --url value '${advertisedUrl}'.`);
+      process.exit(1);
+    }
+
+    let response: Response;
+    try {
+      response = await loopbackSafeFetch(
+        `${mintUrl}/v1/remote-web/pairing-challenge`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ publicBaseUrl }),
+        },
+      );
+    } 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 challenge =
+      (await response.json()) as RemoteWebPairingChallengeResponse;
+    const pairUrl = buildRemoteWebPairingUrl(challenge);
+
+    if (jsonOutput) {
+      console.log(
+        JSON.stringify(
+          {
+            pairUrl,
+            userCode: challenge.userCode,
+            verificationUri: challenge.verificationUri,
+            expiresAt: challenge.expiresAt,
+            expiresInSeconds: challenge.expiresInSeconds,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    const displayName = entry.name || entry.assistantName || entry.assistantId;
+    console.log(`Created remote web pairing for ${displayName}.`);
+    console.log("");
+    console.log("Open this URL in the browser:");
+    console.log("");
+    console.log(`  ${pairUrl}`);
+    console.log("");
+    console.log("Approve this pairing locally when you're ready:");
+    console.log("");
+    const approveTarget = assistantName
+      ? `${JSON.stringify(assistantName)} `
+      : "";
+    console.log(`  Code: ${challenge.userCode}`);
+    console.log(
+      `  Run:  vellum pair ${approveTarget}--web-approve ${challenge.userCode}`,
+    );
+    console.log("");
+    console.log(`Expires: ${challenge.expiresAt}`);
+    return;
+  }
+
   // Fresh per-pairing device identity — each `vellum pair` is independently
   // revocable.
   const deviceId = nanoid();

package/src/commands/retire.ts

@@ -318,7 +318,7 @@ async function retireInner(): Promise<void> {
   console.log(`Removed ${formatAssistantReference(entry)} from config.`);
 
   // When no assistants remain, remove the dock-display-name sentinel so
-  // the next build.sh run falls back to "Vellum" instead of using the
+  // the dock label falls back to "Vellum" instead of using the
   // retired assistant's name.
   if (loadAllAssistants().length === 0) {
     const dockLabelFile = join(

package/src/commands/upgrade.ts

@@ -1012,7 +1012,7 @@ async function upgradePlatform(
 }
 
 /**
- * Pre-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Pre-upgrade steps for the macOS app upgrade lifecycle.
  * Runs the pre-update orchestration without actually swapping containers:
  * broadcasts SSE events, creates a workspace commit, creates a backup,
  * prunes old backups, and outputs the backup path.
@@ -1035,7 +1035,7 @@ async function upgradePrepare(
   await commitWorkspaceViaGateway(
     entry.runtimeUrl,
     entry.assistantId,
-    `[sparkle-update] Starting: ${currentVersion} → ${targetVersion}`,
+    `[assistant-upgrade] Starting: ${currentVersion} → ${targetVersion}`,
   );
 
   // 3. Progress: saving backup
@@ -1070,7 +1070,7 @@ async function upgradePrepare(
 }
 
 /**
- * Post-upgrade steps for Sparkle (macOS app) lifecycle.
+ * Post-upgrade steps for the macOS app upgrade lifecycle.
  * Called after the app has been replaced and the daemon is back up.
  * Broadcasts a "complete" SSE event and creates a workspace commit.
  */
@@ -1103,7 +1103,7 @@ async function upgradeFinalize(
   await commitWorkspaceViaGateway(
     entry.runtimeUrl,
     entry.assistantId,
-    `[sparkle-update] Complete: ${fromVersion} → ${currentVersion}\n\nresult: success`,
+    `[assistant-upgrade] Complete: ${fromVersion} → ${currentVersion}\n\nresult: success`,
   );
 }
 

package/src/lib/device-id.ts

@@ -1,7 +1,7 @@
 /**
  * Host device ID resolver. Resolution order: `VELLUM_DEVICE_ID` env var,
  * then `device.json`. Production uses the machine-wide shared
- * `~/.vellum/device.json`, matching Electron (`apps/macos/src/main/device-id.ts`)
+ * `~/.vellum/device.json`, matching Electron (`clients/macos/src/main/device-id.ts`)
  * and Swift (`VellumPaths.deviceIdFile`); non-production uses
  * `<configDir>/device.json`.
  *

package/src/lib/environments/resolve.ts

@@ -87,10 +87,9 @@ export function getCurrentEnvironment(
   if (!seed) {
     if (name !== DEFAULT_ENVIRONMENT_NAME) {
       // Warn on stderr instead of throwing, to match the silent-fallback
-      // behavior in assistant/src/util/platform.ts:getXdgVellumConfigDirName
-      // and clients/shared/App/VellumEnvironment.swift:current. Those two
-      // silently fall back to production; the CLI should agree so all three
-      // writers don't end up in disjoint states on a typo.
+      // behavior in assistant/src/util/platform.ts:getXdgVellumConfigDirName,
+      // which silently falls back to production; the CLI agrees so neither
+      // writer ends up in a disjoint state on a typo.
       process.stderr.write(
         `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
           `Add it to packages/environments/src/seeds.ts and rebuild if this was intentional.\n`,

package/src/lib/local.ts

@@ -1018,7 +1018,7 @@ export async function startLocalDaemon(
     let daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
 
     // Dev fallback: if the bundled daemon did not become ready in time,
-    // fall back to source daemon startup so local `./build.sh run` still works.
+    // fall back to source daemon startup so local source runs still work.
     if (!daemonReady) {
       const assistantIndex = resolveAssistantIndexPath();
       if (assistantIndex) {

package/src/lib/nginx-ingress.ts

@@ -85,7 +85,7 @@ function saveRawConfig(
  *
  * Resolution order:
  *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
- *   2. Source checkout — walk up from cli/ to find apps/web/dist/
+ *   2. Source checkout — walk up from cli/ to find clients/web/dist/
  */
 export function findWebDistDir(): string | null {
   try {
@@ -100,7 +100,7 @@ export function findWebDistDir(): string | null {
 
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = join(dir, "apps", "web", "dist", "index.html");
+    const candidate = join(dir, "clients", "web", "dist", "index.html");
     if (existsSync(candidate)) {
       return dirname(candidate);
     }
@@ -255,8 +255,6 @@ function buildRemoteWebIngressLocations(opts: {
     location = /v1/pair/ { return 404; }
     location = /v1/pair/web-init { return 404; }
     location = /v1/pair/web-init/ { return 404; }
-    location = /v1/remote-web/pairing-challenge { return 404; }
-    location = /v1/remote-web/pairing-challenge/ { return 404; }
     location = /v1/devices { return 404; }
     location = /v1/devices/ { return 404; }
     location = /v1/devices/revoke { return 404; }
@@ -265,6 +263,8 @@ function buildRemoteWebIngressLocations(opts: {
     location = /v1/guardian/init/ { return 404; }
     location = /v1/guardian/reset-bootstrap { return 404; }
     location = /v1/guardian/reset-bootstrap/ { return 404; }
+    location = /v1/remote-web/pairing-verification { return 404; }
+    location = /v1/remote-web/pairing-verification/ { return 404; }
     location ^~ /assistant/__local/ { return 404; }
     location ^~ /assistant/__gateway/ { return 404; }
 

package/src/shared/provider-env-vars.ts

@@ -27,6 +27,7 @@ export const LLM_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   fireworks: "FIREWORKS_API_KEY",
   openrouter: "OPENROUTER_API_KEY",
   minimax: "MINIMAX_API_KEY",
+  atlascloud: "ATLASCLOUD_API_KEY",
 };
 
 /** Search-provider env var names. Mirrors `SEARCH_PROVIDER_CATALOG` BYOK entries. */
@@ -34,6 +35,7 @@ export const SEARCH_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   perplexity: "PERPLEXITY_API_KEY",
   brave: "BRAVE_API_KEY",
   tavily: "TAVILY_API_KEY",
+  firecrawl: "FIRECRAWL_API_KEY",
 };
 
 /**

package/src/__tests__/env-drift.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { SEEDS } from "@vellumai/environments";
-
-// Drift guard between the two language-level sources of truth for the set of
-// known environment names:
-//
-//   1. packages/environments/src/seeds.ts       — SEEDS record (TS source of truth)
-//   2. clients/shared/App/VellumEnvironment.swift — Swift `VellumEnvironment` enum
-//
-// The Swift client can't import the TypeScript package, so the two lists are
-// maintained independently and must be kept in lockstep by hand. This test
-// parses the enum cases out of the Swift source and asserts they agree with
-// SEEDS. Adding an environment means updating both sites.
-
-const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
-const SWIFT_ENVIRONMENT = join(
-  REPO_ROOT,
-  "clients",
-  "shared",
-  "App",
-  "VellumEnvironment.swift",
-);
-
-/**
- * Extract the case names declared in the `VellumEnvironment` enum. Matches
- * standalone `case <name>` declaration lines (one identifier, nothing else),
- * which is the enum's own declaration syntax. Switch-statement arms like
- * `case .local:` carry a leading dot and a trailing colon, so they're
- * excluded — the match is anchored to a bare identifier at end of line.
- */
-function extractSwiftEnumCases(source: string): string[] {
-  const names: string[] = [];
-  for (const line of source.split("\n")) {
-    const match = line.match(/^\s*case\s+([a-zA-Z][a-zA-Z0-9]*)\s*$/);
-    if (match) names.push(match[1]!);
-  }
-  return names;
-}
-
-describe("environment name drift guard (TS ↔ Swift)", () => {
-  const seedNames = new Set(Object.keys(SEEDS));
-
-  test("clients/shared/App/VellumEnvironment.swift matches SEEDS", () => {
-    const source = readFileSync(SWIFT_ENVIRONMENT, "utf8");
-    const swiftNames = new Set(extractSwiftEnumCases(source));
-
-    expect(swiftNames.size).toBeGreaterThan(0);
-    expect([...swiftNames].sort()).toEqual([...seedNames].sort());
-  });
-});