@vellumai/cli 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/teleport.test.ts

@@ -2201,6 +2201,9 @@ describe("platform credential injection", () => {
         "device-id-123",
         "my-local",
         "cli",
+        undefined, // assistantVersion (gateway unreachable in test)
+        expect.any(String), // platformUrl from getPlatformUrl()
+        undefined, // ingressUrl (gateway unreachable in test)
       );
       expect(injectCredentialsIntoAssistantMock).toHaveBeenCalledWith({
         gatewayUrl: "http://localhost:7821",

package/src/commands/client.ts

@@ -12,12 +12,19 @@ import {
 } from "../lib/constants";
 import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4 } from "../lib/local";
+import {
+  CLI_INTERFACE_ID,
+  getClientRegistrationHeaders,
+} from "../lib/client-identity";
 import {
   fetchOrganizationId,
   readPlatformToken,
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 
+const SUPPORTED_INTERFACES = ["cli"] as const;
+type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
+
 const ANSI = {
   reset: "\x1b[0m",
   bold: "\x1b[1m",
@@ -36,6 +43,8 @@ interface ParsedArgs {
   platformToken?: string;
   /** Guardian JWT (Authorization: Bearer), set for local assistants. */
   bearerToken?: string;
+  /** Interface identifier sent as X-Vellum-Interface-Id on all requests. */
+  interfaceId: SupportedInterface;
   project?: string;
   zone?: string;
 }
@@ -54,7 +63,9 @@ function parseArgs(): ParsedArgs {
       (arg === "--url" ||
         arg === "-u" ||
         arg === "--assistant-id" ||
-        arg === "-a") &&
+        arg === "-a" ||
+        arg === "--interface" ||
+        arg === "-i") &&
       args[i + 1]
     ) {
       flagArgs.push(arg, args[++i]);
@@ -109,6 +120,8 @@ function parseArgs(): ParsedArgs {
       ? undefined
       : (loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined);
 
+  let interfaceId: SupportedInterface = CLI_INTERFACE_ID;
+
   for (let i = 0; i < flagArgs.length; i++) {
     const flag = flagArgs[i];
     if ((flag === "--url" || flag === "-u") && flagArgs[i + 1]) {
@@ -118,6 +131,21 @@ function parseArgs(): ParsedArgs {
       flagArgs[i + 1]
     ) {
       assistantId = flagArgs[++i];
+    } else if ((flag === "--interface" || flag === "-i") && flagArgs[i + 1]) {
+      const value = flagArgs[++i];
+      if (value === "web") {
+        console.error(
+          `--interface web is not yet supported. Coming soon.`,
+        );
+        process.exit(1);
+      }
+      if (!(SUPPORTED_INTERFACES as readonly string[]).includes(value)) {
+        console.error(
+          `Unknown interface '${value}'. Supported: ${SUPPORTED_INTERFACES.join(", ")}.`,
+        );
+        process.exit(1);
+      }
+      interfaceId = value as SupportedInterface;
     }
   }
 
@@ -128,6 +156,7 @@ function parseArgs(): ParsedArgs {
     cloud,
     platformToken,
     bearerToken,
+    interfaceId,
     project: entry?.project,
     zone: entry?.zone,
   };
@@ -184,6 +213,7 @@ ${ANSI.bold}ARGUMENTS:${ANSI.reset}
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
     -a, --assistant-id <id>    Assistant ID
+    -i, --interface <id>       Interface identifier (default: cli)
     -h, --help                 Show this help message
 
 ${ANSI.bold}DEFAULTS:${ANSI.reset}
@@ -206,14 +236,22 @@ export async function client(): Promise<void> {
     cloud,
     platformToken,
     bearerToken,
+    interfaceId,
     project,
     zone,
   } = parseArgs();
 
   tuiLog.init();
-  tuiLog.info("session start", { runtimeUrl, assistantId, species, cloud });
+  tuiLog.info("session start", {
+    runtimeUrl,
+    assistantId,
+    species,
+    cloud,
+    interfaceId,
+  });
 
-  // Build pre-constructed auth headers so all fetch sites share a single object.
+  // Build pre-constructed request headers merged from auth + client registration.
+  // Spreading into every fetch site ensures consistency across REST and SSE endpoints.
   let auth: Record<string, string> | undefined;
   if (cloud === "vellum" && platformToken) {
     const orgId = await fetchOrganizationId(platformToken).catch((err) => {
@@ -223,9 +261,13 @@ export async function client(): Promise<void> {
     auth = {
       "X-Session-Token": platformToken,
       ...(orgId ? { "Vellum-Organization-Id": orgId } : {}),
+      ...getClientRegistrationHeaders(interfaceId),
+    };
+  } else {
+    auth = {
+      ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+      ...getClientRegistrationHeaders(interfaceId),
     };
-  } else if (bearerToken) {
-    auth = { Authorization: `Bearer ${bearerToken}` };
   }
 
   const { renderChatApp } = await import("../components/DefaultMainScreen");

package/src/commands/events.ts

@@ -139,9 +139,6 @@ export async function events(): Promise<void> {
     query,
     headers: getClientRegistrationHeaders(),
   })) {
-    if (!event.message) {
-      continue;
-    }
     if (jsonOutput) {
       console.log(JSON.stringify(event));
     } else {

package/src/commands/login.ts

@@ -10,6 +10,10 @@ import {
   setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
+import {
+  fetchAssistantIngressUrl,
+  fetchCurrentVersion,
+} from "../lib/upgrade-lifecycle.js";
 import {
   clearPlatformToken,
   ensureSelfHostedLocalRegistration,
@@ -210,12 +214,19 @@ export async function login(): Promise<void> {
       if (entry && entry.cloud !== "vellum") {
         const orgId = await fetchOrganizationId(token);
         const clientInstallationId = computeDeviceId();
+        const [assistantVersion, ingressUrl] = await Promise.all([
+          fetchCurrentVersion(entry.runtimeUrl),
+          fetchAssistantIngressUrl(entry.runtimeUrl, entry.bearerToken),
+        ]);
         const registration = await ensureSelfHostedLocalRegistration(
           token,
           orgId,
           clientInstallationId,
           entry.assistantId,
           "cli",
+          assistantVersion,
+          getPlatformUrl(),
+          ingressUrl,
         );
         console.log(
           `Registered assistant: ${registration.assistant.name} (${registration.assistant.id})`,

package/src/commands/rollback.ts

@@ -340,7 +340,7 @@ export async function rollback(): Promise<void> {
     const signingKey =
       capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex");
 
-    // Build extra env vars, excluding keys managed by serviceDockerRunArgs
+    // Build extra env vars, excluding keys managed by buildServiceRunArgs
     const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
     for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
       if (process.env[envVar]) {

package/src/commands/teleport.ts

@@ -47,7 +47,10 @@ import { hatchLocal } from "../lib/hatch-local.js";
 import { retireLocal } from "../lib/retire-local.js";
 import { validateAssistantName } from "../lib/retire-archive.js";
 import { stopProcessByPidFile } from "../lib/process.js";
-import { fetchCurrentVersion } from "../lib/upgrade-lifecycle.js";
+import {
+  fetchAssistantIngressUrl,
+  fetchCurrentVersion,
+} from "../lib/upgrade-lifecycle.js";
 import { compareVersions } from "../lib/version-compat.js";
 import { join } from "node:path";
 
@@ -1066,12 +1069,19 @@ async function tryInjectPlatformCredentials(
     const user = await fetchCurrentUser(token);
     const orgId = await fetchOrganizationId(token);
     const clientInstallationId = computeDeviceId();
+    const [assistantVersion, ingressUrl] = await Promise.all([
+      fetchCurrentVersion(entry.runtimeUrl),
+      fetchAssistantIngressUrl(entry.runtimeUrl, entry.bearerToken),
+    ]);
     const registration = await ensureSelfHostedLocalRegistration(
       token,
       orgId,
       clientInstallationId,
       entry.assistantId,
       "cli",
+      assistantVersion,
+      getPlatformUrl(),
+      ingressUrl,
     );
 
     // Resolve the API key: 1) fresh from registration, 2) existing from

package/src/commands/upgrade.ts

@@ -429,9 +429,9 @@ async function upgradeDocker(
 
   // Build the set of extra env vars to replay on the new assistant container.
   // Captured env vars serve as the base; keys already managed by
-  // serviceDockerRunArgs are excluded to avoid duplicates.
+  // buildServiceRunArgs are excluded to avoid duplicates.
   const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
-  // Only exclude keys that serviceDockerRunArgs will actually set
+  // Only exclude keys that buildServiceRunArgs will actually set
   for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
     if (process.env[envVar]) {
       envKeysSetByRunArgs.add(envVar);

package/src/components/DefaultMainScreen.tsx

@@ -12,7 +12,7 @@ import {
 import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 
 import { removeAssistantEntry } from "../lib/assistant-config";
-import { getClientRegistrationHeaders } from "../lib/client-identity";
+
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { callDoctorDaemon, type ChatLogEntry } from "../lib/doctor-client";
 import { checkHealth } from "../lib/health-check";
@@ -352,13 +352,11 @@ async function* streamEvents(
 ): AsyncGenerator<SseEvent> {
   const params = new URLSearchParams({ conversationKey });
   const url = `${baseUrl}/v1/assistants/${assistantId}/events?${params.toString()}`;
-  const clientHeaders = getClientRegistrationHeaders();
-  tuiLog.info("sse connect", { url, clientHeaders });
+  tuiLog.info("sse connect", { url, authHeaders: Object.keys(auth ?? {}) });
   const response = await fetch(url, {
     headers: {
       Accept: "text/event-stream",
       ...auth,
-      ...clientHeaders,
     },
     signal,
   });

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

@@ -4,9 +4,9 @@ import {
   AVATAR_DEVICE_ENV_VAR,
   dockerResourceNames,
   resolveAvatarDevicePath,
-  serviceDockerRunArgs,
   type ServiceName,
 } from "../docker.js";
+import { buildServiceRunArgs } from "../statefulset.js";
 
 const instanceName = "test-instance";
 const imageTags: Record<ServiceName, string> = {
@@ -16,10 +16,10 @@ const imageTags: Record<ServiceName, string> = {
 };
 
 function buildAssistantArgs(
-  overrides: Partial<Parameters<typeof serviceDockerRunArgs>[0]> = {},
+  overrides: Partial<Parameters<typeof buildServiceRunArgs>[0]> = {},
 ): string[] {
   const res = dockerResourceNames(instanceName);
-  const builders = serviceDockerRunArgs({
+  const builders = buildServiceRunArgs({
     gatewayPort: 7830,
     imageTags,
     instanceName,
@@ -30,10 +30,10 @@ function buildAssistantArgs(
 }
 
 function buildGatewayArgs(
-  overrides: Partial<Parameters<typeof serviceDockerRunArgs>[0]> = {},
+  overrides: Partial<Parameters<typeof buildServiceRunArgs>[0]> = {},
 ): string[] {
   const res = dockerResourceNames(instanceName);
-  const builders = serviceDockerRunArgs({
+  const builders = buildServiceRunArgs({
     gatewayPort: 7830,
     imageTags,
     instanceName,
@@ -43,7 +43,7 @@ function buildGatewayArgs(
   return builders.gateway();
 }
 
-describe("serviceDockerRunArgs — assistant", () => {
+describe("buildServiceRunArgs — assistant", () => {
   test("does not grant elevated capabilities or disable security profiles", () => {
     const args = buildAssistantArgs();
     expect(args).not.toContain("--privileged");
@@ -103,7 +103,7 @@ describe("serviceDockerRunArgs — assistant", () => {
   });
 });
 
-describe("serviceDockerRunArgs — gateway", () => {
+describe("buildServiceRunArgs — gateway", () => {
   const savedVelayBaseUrl = process.env.VELAY_BASE_URL;
 
   beforeEach(() => {

package/src/lib/client-identity.ts

@@ -11,7 +11,7 @@ import { randomUUID } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 
-const CLI_INTERFACE_ID = "cli";
+export const CLI_INTERFACE_ID = "cli";
 
 let cached: string | null = null;
 
@@ -56,12 +56,16 @@ export function getClientId(): string {
 
 /**
  * Headers that identify this CLI client to the assistant daemon.
- * Attach to SSE streaming connections so the ClientRegistry can
- * track connected clients and their capabilities.
+ * Attach to all requests so the ClientRegistry can track connected
+ * clients and their capabilities.
+ *
+ * @param interfaceId - Override the interface ID (default: "cli").
  */
-export function getClientRegistrationHeaders(): Record<string, string> {
+export function getClientRegistrationHeaders(
+  interfaceId: string = CLI_INTERFACE_ID,
+): Record<string, string> {
   return {
     "X-Vellum-Client-Id": getClientId(),
-    "X-Vellum-Interface-Id": CLI_INTERFACE_ID,
+    "X-Vellum-Interface-Id": interfaceId,
   };
 }

package/src/lib/docker.ts

@@ -13,7 +13,7 @@ import {
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { writeInitialConfig } from "./config-utils";
-import { buildServiceRunArgs } from "./docker-statefulset.js";
+import { buildServiceRunArgs } from "./statefulset.js";
 import type { Species } from "./constants";
 import { getDefaultPorts } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
@@ -39,9 +39,8 @@ export const DOCKERHUB_IMAGES: Record<ServiceName, string> = {
   gateway: `${DOCKERHUB_ORG}/vellum-gateway`,
 };
 
-/** Internal ports exposed by each service's Dockerfile. */
-export const ASSISTANT_INTERNAL_PORT = 7821;
-export const GATEWAY_INTERNAL_PORT = 7830;
+/** Internal ports exposed by each service's Dockerfile. Re-exported from environments/paths.ts. */
+export { ASSISTANT_INTERNAL_PORT, GATEWAY_INTERNAL_PORT } from "./environments/paths.js";
 
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
 export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
@@ -560,28 +559,6 @@ async function buildAllImages(
   );
 }
 
-/**
- * Build `docker run` argument arrays for each service in the StatefulSet.
- *
- * Delegates to `buildServiceRunArgs` from `docker-statefulset.ts`, which owns
- * the declarative container / volume / env spec. Signature preserved for
- * backward compatibility with callers throughout this file.
- */
-export function serviceDockerRunArgs(opts: {
-  signingKey?: string;
-  bootstrapSecret?: string;
-  cesServiceToken?: string;
-  extraAssistantEnv?: Record<string, string>;
-  gatewayPort: number;
-  imageTags: Record<ServiceName, string>;
-  defaultWorkspaceConfigPath?: string;
-  instanceName: string;
-  res: ReturnType<typeof dockerResourceNames>;
-}): Record<ServiceName, () => string[]> {
-  const avatarDevice = resolveAvatarDevicePath();
-  return buildServiceRunArgs({ ...opts, avatarDevicePath: avatarDevice });
-}
-
 /** The order in which services must be started. */
 export const SERVICE_START_ORDER: ServiceName[] = [
   "assistant",
@@ -604,7 +581,7 @@ export async function startContainers(
   },
   log: (msg: string) => void,
 ): Promise<void> {
-  const runArgs = serviceDockerRunArgs(opts);
+  const runArgs = buildServiceRunArgs({ ...opts, avatarDevicePath: resolveAvatarDevicePath() });
   for (const service of SERVICE_START_ORDER) {
     log(`🚀 Starting ${service} container...`);
     await exec("docker", runArgs[service]());
@@ -782,7 +759,7 @@ function startFileWatcher(opts: {
   let rebuilding = false;
 
   const configs = serviceImageConfigs(repoRoot, imageTags);
-  const runArgs = serviceDockerRunArgs({
+  const runArgs = buildServiceRunArgs({
     signingKey: opts.signingKey,
     bootstrapSecret: opts.bootstrapSecret,
     cesServiceToken: opts.cesServiceToken,
@@ -790,6 +767,7 @@ function startFileWatcher(opts: {
     imageTags,
     instanceName,
     res,
+    avatarDevicePath: resolveAvatarDevicePath(),
   });
   const containerForService: Record<ServiceName, string> = {
     assistant: res.assistantContainer,

package/src/lib/environments/paths.ts

@@ -98,6 +98,26 @@ export function getDefaultPorts(env: EnvironmentDefinition): PortMap {
   };
 }
 
+/**
+ * Runtime state directory for an environment (upgrade logs, etc.).
+ * Production uses `~/.local/share/vellum/`; non-production environments
+ * use `~/.local/share/vellum-<env>/`.
+ */
+export function getStateDir(env: EnvironmentDefinition): string {
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    return join(xdgDataHome(), "vellum");
+  }
+  return join(xdgDataHome(), `vellum-${env.name}`);
+}
+
+/**
+ * Named port constants derived from `DEFAULT_PORTS`.
+ * These are the ports the assistant and gateway services bind to *inside*
+ * their container (or process). They are stable across environments.
+ */
+export const ASSISTANT_INTERNAL_PORT = DEFAULT_PORTS.daemon;
+export const GATEWAY_INTERNAL_PORT = DEFAULT_PORTS.gateway;
+
 function xdgDataHome(): string {
   return (
     process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share")

package/src/lib/local.ts

@@ -840,6 +840,42 @@ export function isGatewayWatchModeAvailable(): boolean {
   }
 }
 
+/**
+ * Write (or overwrite) a shell wrapper at `<workspace>/bin/assistant` that
+ * pre-injects the three instance-specific env vars before exec-ing the real
+ * assistant binary from the app bundle.
+ *
+ * This lets developers invoke `<workspace>/bin/assistant <command>` directly
+ * from the terminal without manually setting env vars.  Only created when a
+ * compiled `assistant` binary is present adjacent to the CLI executable (i.e.
+ * inside a desktop app bundle) — a no-op in source/watch mode.
+ *
+ * The wrapper is idempotent: safe to call on every daemon wake.
+ */
+function writeAssistantWrapper(resources: LocalInstanceResources): void {
+  const assistantBinary = join(dirname(process.execPath), "assistant");
+  if (!existsSync(assistantBinary)) return;
+
+  const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
+  const protectedDir = join(resources.instanceDir, ".vellum", "protected");
+  const binDir = join(workspaceDir, "bin");
+
+  mkdirSync(binDir, { recursive: true });
+  const wrapperPath = join(binDir, "assistant");
+  writeFileSync(
+    wrapperPath,
+    [
+      "#!/bin/sh",
+      `export VELLUM_WORKSPACE_DIR="${workspaceDir}"`,
+      `export CREDENTIAL_SECURITY_DIR="${protectedDir}"`,
+      `export GATEWAY_SECURITY_DIR="${protectedDir}"`,
+      `exec "${assistantBinary}" "$@"`,
+      "",
+    ].join("\n"),
+    { mode: 0o755 },
+  );
+}
+
 // NOTE: startLocalDaemon() is the CLI-side daemon lifecycle manager.
 // It should eventually converge with
 // assistant/src/daemon/daemon-control.ts::startDaemon which is the
@@ -850,6 +886,7 @@ export async function startLocalDaemon(
   options?: DaemonStartOptions,
 ): Promise<void> {
   warnIfLegacyWorkspaceFallbackDetected(resources);
+  writeAssistantWrapper(resources);
 
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.

package/src/lib/platform-client.ts

@@ -213,6 +213,7 @@ export async function ensureSelfHostedLocalRegistration(
   clientPlatform: string,
   assistantVersion?: string,
   platformUrl?: string,
+  publicBaseUrl?: string,
 ): Promise<EnsureRegistrationResponse> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const body: Record<string, string> = {
@@ -223,6 +224,9 @@ export async function ensureSelfHostedLocalRegistration(
   if (assistantVersion) {
     body.assistant_version = assistantVersion;
   }
+  if (publicBaseUrl) {
+    body.public_ingress_url = publicBaseUrl;
+  }
 
   const response = await fetch(
     `${resolvedUrl}/v1/assistants/self-hosted-local/ensure-registration/`,

package/src/lib/{docker-statefulset.ts → statefulset.ts}

@@ -1,25 +1,19 @@
 /**
- * Declarative StatefulSet spec for the Docker service group.
+ * Declarative StatefulSet spec for the assistant service group.
  *
- * Mirrors the schema of the platform's `stateful_template.yaml` (vembda).
- * Container names, volume names, and env var names are kept in sync with
- * the K8s template so the two topologies are auditable side-by-side.
- *
- * This file is self-contained — it does not import from `docker.ts` to
- * avoid a circular dependency. Constants are inlined from their definitions
- * in `docker.ts` and must be kept in sync if those change.
+ * Defines the static topology of all three containers (assistant, gateway,
+ * credential-executor), their volumes, ports, and env vars. Used by both
+ * the hatch and upgrade flows to build `docker run` argument arrays.
  */
 
 import { existsSync } from "fs";
 
+import {
+  ASSISTANT_INTERNAL_PORT,
+  GATEWAY_INTERNAL_PORT,
+} from "./environments/paths.js";
 import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
 
-// ---------------------------------------------------------------------------
-// Constants (mirrored from docker.ts — keep in sync)
-// ---------------------------------------------------------------------------
-
-const GATEWAY_INTERNAL_PORT = 7830;
-const ASSISTANT_INTERNAL_PORT = 7821;
 const AVATAR_DEVICE_ENV_VAR = "VELLUM_AVATAR_DEVICE";
 
 /** Logical service name used throughout the CLI. */

package/src/lib/upgrade-lifecycle.ts

@@ -1,7 +1,6 @@
 import { randomBytes } from "crypto";
 import { spawnSync } from "child_process";
 import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { homedir } from "os";
 import { join } from "path";
 
 import type { AssistantEntry } from "./assistant-config.js";
@@ -16,6 +15,8 @@ import {
   startContainers,
   stopContainers,
 } from "./docker.js";
+import { getStateDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loadGuardianToken } from "./guardian-token.js";
 import { getPlatformUrl } from "./platform-client.js";
 import { resolveImageRefs } from "./platform-releases.js";
@@ -26,11 +27,9 @@ import { compareVersions } from "./version-compat.js";
 // Failure log capture
 // ---------------------------------------------------------------------------
 
-/** XDG-compliant directory for upgrade failure logs */
+/** XDG-compliant directory for upgrade failure logs, scoped to the current environment. */
 function getUpgradeLogsDir(): string {
-  const stateHome =
-    process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state");
-  return join(stateHome, "vellum", "upgrade-logs");
+  return join(getStateDir(getCurrentEnvironment()), "upgrade-logs");
 }
 
 /**
@@ -207,6 +206,38 @@ export async function fetchCurrentVersion(
   return undefined;
 }
 
+/**
+ * Best-effort fetch of the assistant's configured public ingress URL from the
+ * gateway `integrations/ingress/config` endpoint.  Returns `undefined` when
+ * the gateway is unreachable, the bearer token is missing, or no public URL
+ * is configured.
+ */
+export async function fetchAssistantIngressUrl(
+  runtimeUrl: string,
+  bearerToken?: string,
+): Promise<string | undefined> {
+  if (!bearerToken) return undefined;
+  try {
+    const resp = await fetch(`${runtimeUrl}/integrations/ingress/config`, {
+      headers: { Authorization: `Bearer ${bearerToken}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (resp.ok) {
+      const body = (await resp.json()) as {
+        publicBaseUrl?: string;
+        managedCallbacks?: boolean;
+      };
+      // Ignore managed-callback URLs — those belong to the platform, not the
+      // self-hosted assistant's own ingress.
+      if (body.managedCallbacks) return undefined;
+      return body.publicBaseUrl || undefined;
+    }
+  } catch {
+    // Best-effort
+  }
+  return undefined;
+}
+
 /**
  * Determine the version that was running before the current one.
  *
@@ -605,7 +636,7 @@ export async function performDockerRollback(
   const signingKey =
     capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex");
 
-  // Build extra env vars, excluding keys managed by serviceDockerRunArgs
+  // Build extra env vars, excluding keys managed by buildServiceRunArgs
   const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
   for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
     if (process.env[envVar]) {