@vellumai/cli 0.8.12 → 0.9.0-dev.202606162243.4268db3

package/src/lib/docker.ts

@@ -15,7 +15,6 @@ import cliPkg from "../../package.json";
 
 import {
   findAssistantByName,
-  normalizeVersion,
   saveAssistantEntry,
   setActiveAssistant,
 } from "./assistant-config";
@@ -275,8 +274,53 @@ function ensureLocalBinOnPath(): void {
   }
 }
 
-export interface HatchDockerOptions {
+export interface HatchDockerParams {
+  /** Assistant species to hatch (e.g. `"vellum"`). */
+  species: Species;
+  /** Run detached without attaching to logs or interactive setup. */
+  detached?: boolean;
+  /** Instance display name. Defaults to an auto-generated name. */
+  name?: string | null;
+  /** Build from a local source tree and hot-reload on change. */
+  watch?: boolean;
+  /** Hatch-time config values (key → value). */
+  configValues?: Record<string, string>;
+  /** Extra env vars forwarded into the assistant container. */
+  flagEnvVars?: Record<string, string>;
   setupProviderCredentials?: boolean;
+  /**
+   * Path to a local source tree to build images from before hatching. When
+   * provided, this path is used directly as the repo root and no file
+   * watcher is started — useful for callers (e.g. evals) that want each
+   * run to pick up local CLI changes without keeping a long-lived watcher
+   * process around. `--watch` independently auto-detects the repo root and
+   * also enables hot-reload.
+   */
+  sourcePath?: string | null;
+  analyze?: boolean;
+  /**
+   * Name of an existing container whose network namespace the assistant,
+   * gateway, and credential-executor join (`--network=container:<name>`),
+   * instead of the assistant owning a freshly-created per-instance network.
+   * When set, hatch creates no Docker network and publishes no host ports —
+   * the namespace owner is responsible for publishing the gateway port — so
+   * `gatewayPort` must also be supplied (the owner had to publish it before
+   * hatch ran).
+   */
+  netnsContainer?: string;
+  /**
+   * Explicit host port to record as the gateway's `runtimeUrl` instead of
+   * auto-allocating a free port. Required alongside `netnsContainer`, where
+   * the namespace owner — not hatch — owns port allocation and publishing.
+   */
+  gatewayPort?: number;
+  /**
+   * Host path to a PEM CA bundle bind-mounted into the assistant container
+   * and trusted at process start via `NODE_EXTRA_CA_CERTS`. Lets the daemon
+   * trust a TLS-terminating egress proxy from its very first outbound
+   * connection.
+   */
+  assistantCaCertPath?: string;
 }
 
 export type DockerProviderCredentialSetupAction =
@@ -670,6 +714,8 @@ export async function startContainers(
     imageTags: Record<ServiceName, string>;
     instanceName: string;
     res: ReturnType<typeof dockerResourceNames>;
+    netnsContainer?: string;
+    assistantCaCertPath?: string;
   },
   log: (msg: string) => void,
 ): Promise<void> {
@@ -892,6 +938,8 @@ function startFileWatcher(opts: {
   instanceName: string;
   repoRoot: string;
   res: ReturnType<typeof dockerResourceNames>;
+  netnsContainer?: string;
+  assistantCaCertPath?: string;
 }): () => void {
   const { gatewayPort, imageTags, instanceName, repoRoot, res } = opts;
 
@@ -913,6 +961,8 @@ function startFileWatcher(opts: {
     instanceName,
     res,
     avatarDevicePath: resolveAvatarDevicePath(),
+    netnsContainer: opts.netnsContainer,
+    assistantCaCertPath: opts.assistantCaCertPath,
   });
   const containerForService: Record<ServiceName, string> = {
     assistant: res.assistantContainer,
@@ -1031,31 +1081,19 @@ function startFileWatcher(opts: {
   };
 }
 
-export interface HatchDockerOptions {
-  /**
-   * Path to a local source tree to build images from before hatching. When
-   * provided, this path is used directly as the repo root and no file
-   * watcher is started — useful for callers (e.g. evals) that want each
-   * run to pick up local CLI changes without keeping a long-lived watcher
-   * process around. `--watch` independently auto-detects the repo root and
-   * also enables hot-reload.
-   */
-  sourcePath?: string | null;
-  analyze?: boolean;
-}
+export async function hatchDocker(params: HatchDockerParams): Promise<void> {
+  const {
+    species,
+    detached = false,
+    name = null,
+    configValues = {},
+    flagEnvVars = {},
+  } = params;
+  let watch = params.watch ?? false;
 
-export async function hatchDocker(
-  species: Species,
-  detached: boolean,
-  name: string | null,
-  watch: boolean = false,
-  configValues: Record<string, string> = {},
-  flagEnvVars: Record<string, string> = {},
-  options: HatchDockerOptions = {},
-): Promise<void> {
   resetLogFile("hatch.log");
   const provider =
-    options.setupProviderCredentials === false
+    params.setupProviderCredentials === false
       ? undefined
       : resolveHatchProvider(configValues);
 
@@ -1070,21 +1108,32 @@ export async function hatchDocker(
     await ensureDockerInstalled();
 
     const instanceName = generateInstanceName(species, name);
-    // Resolve the gateway's host port dynamically. The env-default
+    // Resolve the gateway's host port. When joining an externally-owned
+    // network namespace, the owner has already published the gateway port,
+    // so the caller — not hatch — owns port allocation; use the supplied
+    // port verbatim. Otherwise resolve it dynamically: the env-default
     // (production 7830 / non-prod overrides) is just the *preferred*
-    // starting point — if it's taken by another local assistant, eval
-    // run, or unrelated process, we walk upward until we find a free
-    // port. This replaces the previous "first one in wins, everyone
-    // else gets a docker bind error" behavior and removes the need for
-    // an orphan-cleanup pre-flight in the evals harness.
-    const preferredGatewayPort = getDefaultPorts(
-      getCurrentEnvironment(),
-    ).gateway;
-    const gatewayPort = await findOpenPort(preferredGatewayPort);
-    if (gatewayPort !== preferredGatewayPort) {
-      log(
-        `Preferred gateway port ${preferredGatewayPort} is in use; allocated ${gatewayPort} for this instance.`,
-      );
+    // starting point — if it's taken by another local assistant, eval run,
+    // or unrelated process, we walk upward until we find a free port, so
+    // concurrent instances don't collide on a docker bind error.
+    let gatewayPort: number;
+    if (params.netnsContainer) {
+      if (params.gatewayPort === undefined) {
+        throw new Error(
+          "hatchDocker: gatewayPort is required when netnsContainer is set (the namespace owner publishes the port before hatch runs)",
+        );
+      }
+      gatewayPort = params.gatewayPort;
+    } else {
+      const preferredGatewayPort = getDefaultPorts(
+        getCurrentEnvironment(),
+      ).gateway;
+      gatewayPort = await findOpenPort(preferredGatewayPort);
+      if (gatewayPort !== preferredGatewayPort) {
+        log(
+          `Preferred gateway port ${preferredGatewayPort} is in use; allocated ${gatewayPort} for this instance.`,
+        );
+      }
     }
 
     const imageTags: Record<ServiceName, string> = {
@@ -1094,8 +1143,8 @@ export async function hatchDocker(
     };
 
     const sourcePath =
-      typeof options.sourcePath === "string" && options.sourcePath.length > 0
-        ? options.sourcePath
+      typeof params.sourcePath === "string" && params.sourcePath.length > 0
+        ? params.sourcePath
         : null;
     const buildFromSource = sourcePath !== null;
     let repoRoot: string | undefined;
@@ -1152,8 +1201,6 @@ export async function hatchDocker(
       log("✅ Docker images built");
     }
 
-    let releaseVersion: string | undefined;
-
     if (!mode.build || !repoRoot) {
       emitProgress(2, 6, "Pulling images...");
 
@@ -1190,9 +1237,6 @@ export async function hatchDocker(
             `⚠️  Platform releases unavailable; falling back to CLI version ${versionTag}`,
           );
         }
-        if (versionTag !== "latest") {
-          releaseVersion = normalizeVersion(versionTag);
-        }
         log("🔍 Resolving image references...");
         const resolved = await resolveImageRefs(versionTag, log);
         imageTags.assistant = resolved.imageTags.assistant;
@@ -1247,8 +1291,15 @@ export async function hatchDocker(
     const res = dockerResourceNames(instanceName);
 
     emitProgress(3, 6, "Creating volumes...");
-    log("📁 Creating network and volumes...");
-    await exec("docker", ["network", "create", res.network]);
+    // When joining an externally-owned network namespace, the owner already
+    // provides the network stack — creating a per-instance network here would
+    // be unused and leak on teardown.
+    if (params.netnsContainer) {
+      log("📁 Joining existing network namespace; creating volumes...");
+    } else {
+      log("📁 Creating network and volumes...");
+      await exec("docker", ["network", "create", res.network]);
+    }
     await exec("docker", ["volume", "create", res.socketVolume]);
     await exec("docker", ["volume", "create", res.assistantIpcVolume]);
     await exec("docker", ["volume", "create", res.gatewayIpcVolume]);
@@ -1356,6 +1407,8 @@ export async function hatchDocker(
         imageTags,
         instanceName,
         res,
+        netnsContainer: params.netnsContainer,
+        assistantCaCertPath: params.assistantCaCertPath,
       },
       log,
     );
@@ -1370,7 +1423,6 @@ export async function hatchDocker(
       cloud: "docker",
       species,
       hatchedAt: new Date().toISOString(),
-      version: releaseVersion,
       guardianBootstrapSecret: ownSecret,
       containerInfo: {
         assistantImage: imageTags.assistant,
@@ -1396,7 +1448,7 @@ export async function hatchDocker(
       logFd,
       runtimeUrl,
       containersUpAt,
-      analyze: options.analyze ?? false,
+      analyze: params.analyze ?? false,
     });
 
     if (!ready && !(watch && repoRoot)) {
@@ -1454,6 +1506,8 @@ export async function hatchDocker(
         instanceName,
         repoRoot,
         res,
+        netnsContainer: params.netnsContainer,
+        assistantCaCertPath: params.assistantCaCertPath,
       });
 
       await new Promise<void>((resolve) => {

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/feature-flags.test.ts

@@ -0,0 +1,157 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "./feature-flags.js";
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-feature-flags-test-"));
+const originalFetch = globalThis.fetch;
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+
+function writeLockfile(): void {
+  mkdirSync(testDir, { recursive: true });
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify(
+      {
+        activeAssistant: "assistant-1",
+        assistants: [
+          {
+            assistantId: "assistant-1",
+            runtimeUrl: "http://127.0.0.1:7830",
+            cloud: "local",
+          },
+        ],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function mockFetch(response: Response): void {
+  const fetchMock = async () => response;
+  globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+}
+
+function mockFetchWithUrls(response: Response): string[] {
+  const urls: string[] = [];
+  const fetchMock = async (input: RequestInfo | URL) => {
+    urls.push(String(input));
+    return response;
+  };
+  globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  return urls;
+}
+
+describe("isAssistantFeatureFlagEnabled", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    writeLockfile();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  afterAll(() => {
+    if (originalLockfileDir === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+    }
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("returns true when the assistant flag is enabled", async () => {
+    mockFetch(
+      jsonResponse({
+        flags: [{ key: WEB_REMOTE_INGRESS_FLAG, enabled: true }],
+      }),
+    );
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG),
+    ).resolves.toBe(true);
+  });
+
+  test("uses the supplied runtime URL instead of a stale lockfile runtimeUrl", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify(
+        {
+          activeAssistant: "assistant-1",
+          assistants: [
+            {
+              assistantId: "assistant-1",
+              runtimeUrl: "https://stale-tunnel.ngrok-free.dev",
+              cloud: "local",
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    const urls = mockFetchWithUrls(
+      jsonResponse({
+        flags: [{ key: WEB_REMOTE_INGRESS_FLAG, enabled: true }],
+      }),
+    );
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG, {
+        runtimeUrl: "http://127.0.0.1:9123",
+      }),
+    ).resolves.toBe(true);
+
+    expect(urls).toEqual([
+      "http://127.0.0.1:9123/v1/assistants/assistant-1/feature-flags",
+    ]);
+  });
+
+  test("returns false when the assistant flag is disabled or missing", async () => {
+    mockFetch(
+      jsonResponse({
+        flags: [{ key: WEB_REMOTE_INGRESS_FLAG, enabled: false }],
+      }),
+    );
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG),
+    ).resolves.toBe(false);
+
+    mockFetch(jsonResponse({ flags: [] }));
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG),
+    ).resolves.toBe(false);
+  });
+
+  test("throws when the gateway rejects the flag request", async () => {
+    mockFetch(jsonResponse({ error: "nope" }, 500));
+
+    await expect(
+      isAssistantFeatureFlagEnabled("assistant-1", WEB_REMOTE_INGRESS_FLAG),
+    ).rejects.toThrow("Failed to fetch feature flags");
+  });
+});

package/src/lib/feature-flags.ts

@@ -0,0 +1,38 @@
+import { AssistantClient } from "./assistant-client.js";
+
+export const WEB_REMOTE_INGRESS_FLAG = "web-remote-ingress";
+
+type FeatureFlagEntry = {
+  key?: unknown;
+  enabled?: unknown;
+};
+
+type FeatureFlagsResponse = {
+  flags?: FeatureFlagEntry[];
+};
+
+export async function isAssistantFeatureFlagEnabled(
+  assistantId: string,
+  key: string,
+  opts: { runtimeUrl?: string } = {},
+): Promise<boolean> {
+  const client = new AssistantClient({
+    assistantId,
+    runtimeUrl: opts.runtimeUrl,
+  });
+  const res = await client.get("/feature-flags");
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(
+      `Failed to fetch feature flags: HTTP ${res.status} ${body}`.trim(),
+    );
+  }
+
+  const data = (await res.json()) as FeatureFlagsResponse;
+  const flag = data.flags?.find((entry) => entry.key === key);
+  return flag?.enabled === true;
+}
+
+export function formatFeatureFlagGateMessage(flagKey: string): string {
+  return `This command is behind the \`${flagKey}\` feature flag. Enable it with \`vellum flags set ${flagKey} true\` and try again.`;
+}

package/src/lib/hatch-local.ts

@@ -290,7 +290,6 @@ export async function hatchLocal(
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
-    version: cliPkg.version,
     resources: { ...resources, signingKey },
     guardianBootstrapSecret: bootstrapSecret,
   };

package/src/lib/local.ts

@@ -17,6 +17,7 @@ import {
 } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
+import { stopIngressNginx } from "./nginx-ingress.js";
 import {
   resolveProcessState,
   stopProcess,
@@ -1240,4 +1241,8 @@ export async function stopLocalProcesses(
       unlinkSync(ngrokPidFile);
     } catch {}
   }
+
+  // Stop the nginx ingress if one is fronting this gateway (it guards against
+  // PID reuse itself, mirroring the ngrok handling above).
+  await stopIngressNginx(join(vellumDir, "workspace"));
 }