@vellumai/cli 0.10.2-dev.202606251104.36cd100 → 0.10.2-dev.202606251257.2eba8a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.2-dev.202606251104.36cd100",
+  "version": "0.10.2-dev.202606251257.2eba8a4",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/statefulset.test.ts

@@ -111,6 +111,7 @@ describe("getBuilderManagedEnvKeys", () => {
 describe("buildServiceRunArgs extra env routing", () => {
   const opts: BuildServiceRunArgsOpts = {
     gatewayPort: 18080,
+    assistantPort: 18081,
     imageTags: {
       assistant: "assistant:test",
       gateway: "gateway:test",

package/src/commands/rollback.ts

@@ -8,6 +8,7 @@ import {
 import {
   captureImageRefs,
   GATEWAY_INTERNAL_PORT,
+  ASSISTANT_INTERNAL_PORT,
   dockerResourceNames,
   startContainers,
   stopContainers,
@@ -324,6 +325,9 @@ export async function rollback(): Promise<void> {
       // use default
     }
 
+    // Recover the assistant host port from the entry, fall back to default.
+    const assistantPort = entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+
     // Notify connected clients that a rollback is about to begin (best-effort)
     console.log("📢 Notifying connected clients...");
     await broadcastUpgradeEvent(
@@ -373,6 +377,7 @@ export async function rollback(): Promise<void> {
         extraAssistantEnv,
         extraGatewayEnv,
         gatewayPort,
+        assistantPort,
         imageTags: previousImageRefs,
         instanceName,
         res,
@@ -399,6 +404,7 @@ export async function rollback(): Promise<void> {
           gatewayDigest: newDigests?.gateway,
           cesDigest: newDigests?.["credential-executor"],
           networkName: res.network,
+          assistantPort,
         },
         previousContainerInfo: entry.containerInfo,
         // Clear the backup path — it belonged to the upgrade we just rolled back

package/src/commands/upgrade.ts

@@ -14,6 +14,7 @@ import {
 import {
   captureImageRefs,
   GATEWAY_INTERNAL_PORT,
+  ASSISTANT_INTERNAL_PORT,
   dockerResourceNames,
   startContainers,
   stopContainers,
@@ -432,6 +433,9 @@ async function upgradeDocker(
     // use default
   }
 
+  // Recover the assistant host port from the entry, fall back to default.
+  const assistantPort = entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+
   // Create pre-upgrade backup (best-effort, daemon must be running)
   await broadcastUpgradeEvent(
     entry.runtimeUrl,
@@ -483,6 +487,7 @@ async function upgradeDocker(
       extraAssistantEnv,
       extraGatewayEnv,
       gatewayPort,
+      assistantPort,
       imageTags,
       instanceName,
       res,
@@ -506,6 +511,7 @@ async function upgradeDocker(
         gatewayDigest: newDigests?.gateway,
         cesDigest: newDigests?.["credential-executor"],
         networkName: res.network,
+        assistantPort,
       },
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
@@ -589,6 +595,7 @@ async function upgradeDocker(
             extraAssistantEnv,
             extraGatewayEnv,
             gatewayPort,
+            assistantPort,
             imageTags: previousImageRefs,
             instanceName,
             res,
@@ -654,6 +661,7 @@ async function upgradeDocker(
                 rollbackDigests?.["credential-executor"] ??
                 previousImageRefs["credential-executor"],
               networkName: res.network,
+              assistantPort,
             },
             previousContainerInfo: undefined,
             previousDbMigrationVersion: undefined,

package/src/lib/__tests__/docker.test.ts

@@ -27,6 +27,7 @@ function buildAssistantArgs(
   const res = dockerResourceNames(instanceName);
   const builders = buildServiceRunArgs({
     gatewayPort: 7830,
+    assistantPort: 7821,
     imageTags,
     instanceName,
     res,
@@ -41,6 +42,7 @@ function buildGatewayArgs(
   const res = dockerResourceNames(instanceName);
   const builders = buildServiceRunArgs({
     gatewayPort: 7830,
+    assistantPort: 7821,
     imageTags,
     instanceName,
     res,
@@ -84,13 +86,15 @@ describe("buildServiceRunArgs — assistant", () => {
   });
 
   test("publishes the assistant HTTP port on all host interfaces so sibling bot containers can reach the daemon via host.docker.internal on both Docker Desktop and Linux", () => {
-    const args = buildAssistantArgs();
+    const args = buildAssistantArgs({ assistantPort: 18000 });
     // The port mapping is expressed as two adjacent args: "-p" then the spec.
     // Bound to all interfaces (no `127.0.0.1:` prefix) because on vanilla
     // Linux Docker, host.docker.internal:host-gateway resolves to the Docker
     // bridge gateway IP — packets arrive at the bridge interface, not
     // loopback, so a 127.0.0.1 DNAT rule would not match.
-    const portSpec = `${ASSISTANT_INTERNAL_PORT}:${ASSISTANT_INTERNAL_PORT}`;
+    // The host-side port is dynamically allocated (not fixed at 7821) so
+    // concurrent instances on the same host don't collide.
+    const portSpec = `18000:${ASSISTANT_INTERNAL_PORT}`;
     const portIndex = args.indexOf(portSpec);
     expect(portIndex).toBeGreaterThan(0);
     expect(args[portIndex - 1]).toBe("-p");

package/src/lib/assistant-config.ts

@@ -74,6 +74,14 @@ export interface ContainerInfo {
   cesDigest?: string;
   /** Docker network name for the service group */
   networkName?: string;
+  /**
+   * Host-side port the assistant HTTP API is published on. Dynamically
+   * allocated at hatch time so concurrent instances don't collide on the
+   * default (7821). Stored so rollback/upgrade can rebind the same port
+   * instead of re-allocating (which could grab a different port if another
+   * process took it in the interim).
+   */
+  assistantPort?: number;
 }
 
 /**

package/src/lib/docker.ts

@@ -23,7 +23,7 @@ import { buildHatchConfigValues, writeInitialConfig } from "./config-utils";
 import { buildServiceRunArgs } from "./statefulset.js";
 import type { Species } from "./constants";
 import { getOrCreateHostDeviceId } from "./device-id.js";
-import { getDefaultPorts } from "./environments/paths.js";
+import { ASSISTANT_INTERNAL_PORT, getDefaultPorts } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
 import { logHatchNextSteps } from "./hatch-next-steps.js";
@@ -711,6 +711,7 @@ export async function startContainers(
     extraAssistantEnv?: Record<string, string>;
     extraGatewayEnv?: Record<string, string>;
     gatewayPort: number;
+    assistantPort: number;
     imageTags: Record<ServiceName, string>;
     instanceName: string;
     res: ReturnType<typeof dockerResourceNames>;
@@ -934,6 +935,7 @@ function startFileWatcher(opts: {
   extraAssistantEnv?: Record<string, string>;
   extraGatewayEnv?: Record<string, string>;
   gatewayPort: number;
+  assistantPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
   repoRoot: string;
@@ -941,7 +943,7 @@ function startFileWatcher(opts: {
   netnsContainer?: string;
   assistantCaCertPath?: string;
 }): () => void {
-  const { gatewayPort, imageTags, instanceName, repoRoot, res } = opts;
+  const { gatewayPort, assistantPort, imageTags, instanceName, repoRoot, res } = opts;
 
   const { dirs: watchDirs, files: watchFiles } = collectWatchTargets(repoRoot);
 
@@ -957,6 +959,7 @@ function startFileWatcher(opts: {
     extraAssistantEnv: opts.extraAssistantEnv,
     extraGatewayEnv: opts.extraGatewayEnv,
     gatewayPort,
+    assistantPort,
     imageTags,
     instanceName,
     res,
@@ -1136,6 +1139,30 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
       }
     }
 
+    // Allocate the assistant HTTP API host port. Same dynamic-allocation
+    // strategy as the gateway port: the env-default (production 7821 /
+    // non-prod overrides) is the *preferred* starting point, and we walk
+    // upward until we find a free port. Without this, two concurrent
+    // `vellum hatch --remote docker` on the same host collide on a fixed
+    // 7821 bind ("port is already allocated"). Unused when netnsContainer
+    // is set — no host ports are published in that mode.
+    let assistantPort: number;
+    if (params.netnsContainer) {
+      assistantPort = ASSISTANT_INTERNAL_PORT;
+    } else {
+      const preferredAssistantPort = getDefaultPorts(
+        getCurrentEnvironment(),
+      ).daemon;
+      assistantPort = await findOpenPort(preferredAssistantPort, {
+        exclude: [gatewayPort],
+      });
+      if (assistantPort !== preferredAssistantPort) {
+        log(
+          `Preferred assistant port ${preferredAssistantPort} is in use; allocated ${assistantPort} for this instance.`,
+        );
+      }
+    }
+
     const imageTags: Record<ServiceName, string> = {
       assistant: "",
       "credential-executor": "",
@@ -1404,6 +1431,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         extraAssistantEnv,
         extraGatewayEnv,
         gatewayPort,
+        assistantPort,
         imageTags,
         instanceName,
         res,
@@ -1432,6 +1460,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         gatewayDigest: imageDigests?.gateway,
         cesDigest: imageDigests?.["credential-executor"],
         networkName: res.network,
+        assistantPort,
       },
     };
     emitProgress(5, 6, "Saving configuration...");
@@ -1502,6 +1531,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         extraAssistantEnv,
         extraGatewayEnv,
         gatewayPort,
+        assistantPort,
         imageTags,
         instanceName,
         repoRoot,

package/src/lib/port-allocator.ts

@@ -21,10 +21,11 @@ import { createServer } from "net";
  */
 export async function findOpenPort(
   preferred: number,
-  options: { maxAttempts?: number; host?: string } = {},
+  options: { maxAttempts?: number; host?: string; exclude?: number[] } = {},
 ): Promise<number> {
   const maxAttempts = options.maxAttempts ?? 50;
   const host = options.host ?? "0.0.0.0";
+  const exclude = new Set(options.exclude ?? []);
 
   if (!Number.isInteger(preferred) || preferred < 1 || preferred > 65535) {
     throw new Error(
@@ -41,6 +42,7 @@ export async function findOpenPort(
   for (let offset = 0; offset < maxAttempts; offset++) {
     const port = preferred + offset;
     if (port > 65535) break;
+    if (exclude.has(port)) continue;
     try {
       await probePort(port, host);
       return port;

package/src/lib/statefulset.ts

@@ -85,8 +85,9 @@ interface VolumeMount {
 interface PortSpec {
   containerPort: number;
   /**
-   * Host-side port. Literal string = use as-is. `"{{ gatewayPort }}"` is
-   * a sentinel replaced with the instance-specific gateway port at build time.
+   * Host-side port. Literal string = use as-is. `"{{ gatewayPort }}"` and
+   * `"{{ assistantPort }}"` are sentinels replaced with the instance-specific
+   * gateway / assistant host ports at build time.
    */
   hostPort?: string;
   description?: string;
@@ -172,7 +173,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
         },
         {
           containerPort: ASSISTANT_INTERNAL_PORT,
-          hostPort: `${ASSISTANT_INTERNAL_PORT}`,
+          hostPort: "{{ assistantPort }}",
           description: "Assistant HTTP API",
         },
       ],
@@ -261,6 +262,13 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
 
 export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
   gatewayPort: number;
+  /**
+   * Host-side port for the assistant HTTP API. Allocated dynamically by
+   * `hatchDocker` (mirroring `gatewayPort`) so concurrent instances on the
+   * same host don't collide on a fixed port bind. Unused when
+   * `netnsContainer` is set (no host ports are published in that mode).
+   */
+  assistantPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
   res: DockerResourceNames;
@@ -353,6 +361,7 @@ export function buildServiceRunArgs(
 ): Record<ServiceName, () => string[]> {
   const {
     gatewayPort,
+    assistantPort,
     imageTags,
     instanceName,
     res,
@@ -396,7 +405,9 @@ export function buildServiceRunArgs(
           const hostSide =
             port.hostPort === "{{ gatewayPort }}"
               ? `${gatewayPort}`
-              : port.hostPort;
+              : port.hostPort === "{{ assistantPort }}"
+                ? `${assistantPort}`
+                : port.hostPort;
           if (hostSide !== undefined) {
             args.push("-p", `${hostSide}:${port.containerPort}`);
           }

package/src/lib/upgrade-lifecycle.ts

@@ -13,6 +13,7 @@ import {
   DOCKER_READY_TIMEOUT_MS,
   dockerResourceNames,
   GATEWAY_INTERNAL_PORT,
+  ASSISTANT_INTERNAL_PORT,
   startContainers,
   stopContainers,
 } from "./docker.js";
@@ -685,6 +686,9 @@ export async function performDockerRollback(
     // use default
   }
 
+  // Recover the assistant host port from the entry, fall back to default.
+  const assistantPort = entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+
   // Broadcast SSE "starting" event
   console.log("📢 Notifying connected clients...");
   await broadcastUpgradeEvent(
@@ -746,6 +750,7 @@ export async function performDockerRollback(
       extraAssistantEnv,
       extraGatewayEnv,
       gatewayPort,
+      assistantPort,
       imageTags: targetImageTags,
       instanceName,
       res,
@@ -785,6 +790,7 @@ export async function performDockerRollback(
         gatewayDigest: newDigests?.gateway,
         cesDigest: newDigests?.["credential-executor"],
         networkName: res.network,
+        assistantPort,
       },
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
@@ -867,6 +873,7 @@ export async function performDockerRollback(
             extraAssistantEnv,
             extraGatewayEnv,
             gatewayPort,
+            assistantPort,
             imageTags: currentImageRefs,
             instanceName,
             res,
@@ -919,6 +926,7 @@ export async function performDockerRollback(
                 revertDigests?.["credential-executor"] ??
                 currentImageRefs["credential-executor"],
               networkName: res.network,
+              assistantPort,
             },
             previousContainerInfo: undefined,
             previousDbMigrationVersion: undefined,