@vellumai/cli 0.8.5 → 0.8.7

package/AGENTS.md

@@ -63,6 +63,12 @@ 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.
 
+## Process liveness
+
+Use `resolveProcessState()` from `lib/process.ts` when checking whether a daemon or gateway should be (re)started. It combines PID existence with an HTTP `/healthz` probe, a readiness grace period, and a [`isVellumProcess()`](https://man7.org/linux/man-pages/man1/ps.1.html) guard against PID reuse — see the function's JSDoc for the full flow.
+
+Reserve `isProcessAlive()` for teardown paths (`sleep`, `retire`) where you need to kill a process regardless of its health.
+
 ## Docker Volume Management
 
 The CLI creates and manages six per-instance Docker volumes with strict per-service access boundaries (least-privilege at the container level).

package/bun.lock

@@ -5,6 +5,8 @@
     "": {
       "name": "@vellumai/cli",
       "dependencies": {
+        "@vellumai/environments": "file:../packages/environments",
+        "@vellumai/local-mode": "file:../packages/local-mode",
         "chalk": "5.6.2",
         "ink": "6.8.0",
         "nanoid": "5.1.7",
@@ -135,6 +137,10 @@
 
     "@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.58.0", "", { "dependencies": { "@typescript-eslint/types": "8.58.0", "eslint-visitor-keys": "^5.0.0" } }, "sha512-XJ9UD9+bbDo4a4epraTwG3TsNPeiB9aShrUneAVXy8q4LuwowN+qu89/6ByLMINqvIMeI9H9hOHQtg/ijrYXzQ=="],
 
+    "@vellumai/environments": ["@vellumai/environments@file:../packages/environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
+    "@vellumai/local-mode": ["@vellumai/local-mode@file:../packages/local-mode", { "dependencies": { "@vellumai/environments": "file:../environments" }, "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
@@ -397,6 +403,8 @@
 
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
+    "@vellumai/local-mode/@vellumai/environments": ["@vellumai/environments@file:../packages/environments", {}],
+
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],

package/knip.json

@@ -7,5 +7,10 @@
     "src/lib/platform-releases.ts",
     "src/lib/cli-error.ts"
   ],
-  "project": ["src/**/*.ts", "src/**/*.tsx"]
+  "project": ["src/**/*.ts", "src/**/*.tsx"],
+  "ignoreDependencies": [
+    "@vellumai/environments",
+    "@vellumai/local-mode",
+    "@vellumai/web"
+  ]
 }

package/node_modules/@vellumai/environments/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/environments",
+      "devDependencies": {
+        "@types/bun": "1.3.11",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+  }
+}

package/node_modules/@vellumai/environments/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/environments",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/environments/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Package boundary tests for @vellumai/environments.
+ *
+ * This package is the lowest layer of the shared-packages hierarchy: pure
+ * environment types and constants with no runtime dependencies. It must
+ * stay a leaf so any consumer (CLI, assistant, local-mode host) can depend
+ * on it without dragging in a dependency tree.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins and its own relative modules — no `@vellumai/*`
+ *    packages and no third-party runtime imports.
+ * 2. Declares no runtime `dependencies` (devDependencies only).
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/** A bare specifier is anything that is not a relative or node-builtin import. */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins and relative modules", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @vellumai/environments:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@vellumai/environments is a pure types/constants leaf and must\n" +
+          "import only node builtins and its own relative modules.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with no runtime dependencies", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({});
+  });
+});

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

@@ -0,0 +1,11 @@
+/**
+ * @vellumai/environments — the single source of truth for Vellum's known
+ * deployment environments (names, platform/web URLs, per-service port
+ * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
+ * host library so the environment list is defined exactly once on the TS
+ * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ *
+ * Intentionally free of runtime dependencies: pure types and constants only.
+ */
+export * from "./types.js";
+export * from "./seeds.js";

package/{src/lib/environments → node_modules/@vellumai/environments/src}/seeds.ts

@@ -25,15 +25,11 @@ function portBlock(base: number): PortMap {
 }
 
 /**
- * Built-in environment definitions. Mirrors Swift's
- * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
- * the TS-side source of truth for the set of known environment names.
- * One other TS site duplicates the name list:
- *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
- * Drift between these two sites is caught at test time by
- * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
- * list into a `packages/environments` package so both sites import
- * from one place.
+ * 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`.
  *
  * 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/node_modules/@vellumai/environments/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/local-mode/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/local-mode",
+      "dependencies": {
+        "@vellumai/environments": "file:../environments",
+      },
+      "devDependencies": {
+        "@types/bun": "1.3.11",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "@vellumai/environments": ["@vellumai/environments@file:../environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+  }
+}

package/node_modules/@vellumai/local-mode/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@vellumai/local-mode",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@vellumai/environments": "file:../environments"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/local-mode/src/__tests__/hatch.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+
+import type { CliInvocation } from "../util";
+
+class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+let lastChild: FakeChild;
+const spawnArgs: Array<[string, string[]]> = [];
+const spawnMock = mock((command: string, args: string[]) => {
+  spawnArgs.push([command, args]);
+  lastChild = new FakeChild();
+  return lastChild;
+});
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runHatch: typeof import("../hatch").runHatch;
+
+beforeAll(async () => {
+  ({ runHatch } = await import("../hatch"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("runHatch", () => {
+  test("spawns the CLI and parses the assistant id from stdout", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from("Hatching local assistant: asst-42\n"),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true, assistantId: "asst-42" });
+    expect(spawnArgs[0]).toEqual(["bun", ["run", "cli", "hatch", "vellum"]]);
+  });
+
+  test("a non-zero exit resolves to a failure carrying the CLI's output", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stderr.emit("data", Buffer.from("daemon already running"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      status: 500,
+      error: "daemon already running",
+    });
+  });
+
+  test("a non-zero exit with no output carries a descriptive fallback error", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.emit("close", 1);
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("exited with code 1");
+    }
+  });
+
+  test("a zero exit whose stdout has no parseable id fails instead of returning a blank id", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.stdout.emit("data", Buffer.from("done, but no id line\n"));
+    lastChild.emit("close", 0);
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("no assistant id");
+    }
+  });
+
+  test("a spawn failure resolves to a failure rather than rejecting", async () => {
+    const pending = runHatch(invocation, "vellum");
+    lastChild.emit("error", new Error("ENOENT"));
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("ENOENT");
+    }
+  });
+});

package/node_modules/@vellumai/local-mode/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Package boundary tests for @vellumai/local-mode.
+ *
+ * This package is the shared local-assistant host surface. It sits one layer
+ * above @vellumai/environments (its only allowed @vellumai dependency) and
+ * uses node builtins for filesystem, child-process, and network work.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins, its own relative modules, and
+ *    `@vellumai/environments` — no other `@vellumai/*` packages and no
+ *    third-party runtime imports (so any bundler host can inline it).
+ * 2. Declares exactly one runtime dependency: `@vellumai/environments`.
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+const ALLOWED_PACKAGES = new Set(["@vellumai/environments"]);
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/**
+ * A specifier is forbidden when it is neither relative, a node builtin, nor
+ * one of the explicitly allowed `@vellumai/*` packages.
+ */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  if (ALLOWED_PACKAGES.has(spec)) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins, relative modules, and @vellumai/environments", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @vellumai/local-mode:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@vellumai/local-mode may import only node builtins, its own\n" +
+          "relative modules, and @vellumai/environments. Any other dependency\n" +
+          "would break bundler hosts that inline this source-only package.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with only the @vellumai/environments dependency", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({
+      "@vellumai/environments": "file:../environments",
+    });
+  });
+});

package/node_modules/@vellumai/local-mode/src/config.ts

@@ -0,0 +1,59 @@
+import os from "node:os";
+import path from "node:path";
+
+import { SEEDS } from "@vellumai/environments";
+
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+
+export interface LocalEndpointConfig {
+  lockfilePaths: string[];
+  configDir: string;
+  webUrl: string;
+  platformUrl: string;
+}
+
+/**
+ * Resolve config from environment variables (Vite plugin context, where
+ * `env` comes from `loadEnv` and process.env).
+ */
+export function resolveLocalConfigFromEnv(
+  env: Record<string, string>,
+): LocalEndpointConfig {
+  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+  const seed = SEEDS[vellumEnv] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME]!;
+
+  return {
+    lockfilePaths: resolveLockfilePaths(env),
+    configDir: resolveConfigDir(env),
+    webUrl: env.VELLUM_WEB_URL || seed.webUrl,
+    platformUrl: env.VELLUM_PLATFORM_URL || seed.platformUrl,
+  };
+}
+
+export function resolveLockfilePaths(env: Record<string, string>): string[] {
+  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+  const lockfileDir = env.VELLUM_LOCKFILE_DIR;
+
+  if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
+    const dir = lockfileDir ?? os.homedir();
+    return [
+      path.join(dir, ".vellum.lock.json"),
+      path.join(dir, ".vellum.lockfile.json"),
+    ];
+  }
+
+  const xdgConfigHome =
+    env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  const dir = lockfileDir ?? path.join(xdgConfigHome, `vellum-${vellumEnv}`);
+  return [path.join(dir, "lockfile.json")];
+}
+
+export function resolveConfigDir(env: Record<string, string>): string {
+  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+  const xdgConfigHome =
+    env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
+    return path.join(xdgConfigHome, "vellum");
+  }
+  return path.join(xdgConfigHome, `vellum-${vellumEnv}`);
+}

package/node_modules/@vellumai/local-mode/src/gateway-proxy.ts

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+
+const GATEWAY_PATTERN = /^(?:\/assistant)?\/__gateway\/(\d+)(\/.*)?$/;
+
+export interface GatewayTarget {
+  port: number;
+  path: string;
+}
+
+export type GatewayParseResult =
+  | { match: true; valid: true; target: GatewayTarget }
+  | { match: true; valid: false }
+  | { match: false };
+
+export function parseGatewayUrl(pathname: string): GatewayParseResult {
+  const match = pathname.match(GATEWAY_PATTERN);
+  if (!match) return { match: false };
+
+  const port = parseInt(match[1]!, 10);
+  if (port < 1024 || port > 65535) return { match: true, valid: false };
+
+  return { match: true, valid: true, target: { port, path: match[2] || "/" } };
+}
+
+function addPortFromUrl(url: unknown, ports: Set<number>): void {
+  if (typeof url !== "string") return;
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") return;
+    const port = Number(parsed.port);
+    if (Number.isInteger(port) && port >= 1024 && port <= 65535) {
+      ports.add(port);
+    }
+  } catch {
+    // malformed URL — skip
+  }
+}
+
+export function readAllowedGatewayPorts(lockfilePaths: string[]): Set<number> {
+  const ports = new Set<number>();
+  for (const candidate of lockfilePaths) {
+    try {
+      const raw = fs.readFileSync(candidate, "utf-8");
+      const data = JSON.parse(raw) as {
+        assistants?: Array<{
+          gatewayUrl?: unknown;
+          localUrl?: unknown;
+          resources?: { gatewayPort?: unknown };
+        }>;
+      };
+      const assistants = Array.isArray(data.assistants) ? data.assistants : [];
+      for (const assistant of assistants) {
+        if (!assistant) continue;
+        addPortFromUrl(assistant.gatewayUrl, ports);
+        addPortFromUrl(assistant.localUrl, ports);
+        const gp = assistant.resources?.gatewayPort;
+        if (typeof gp === "number" && Number.isInteger(gp) && gp >= 1024 && gp <= 65535) {
+          ports.add(gp);
+        }
+      }
+      if (ports.size > 0) return ports;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") return new Set<number>();
+    }
+  }
+  return ports;
+}