@vellumai/cli 0.6.3 → 0.6.4

package/src/lib/environments/seeds.ts

@@ -0,0 +1,46 @@
+import type { EnvironmentDefinition } from "./types.js";
+
+/**
+ * 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.
+ * Two other TS sites duplicate the name list:
+ *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
+ *   - `clients/chrome-extension/native-host/src/lockfile.ts`
+ *     (`NON_PRODUCTION_ENVIRONMENTS`, excludes `production`)
+ * Drift between these three 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 all three sites import
+ * from one place.
+ *
+ * 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
+ * new environment must add it here and rebuild.
+ */
+export const SEEDS: Record<string, EnvironmentDefinition> = {
+  production: {
+    name: "production",
+    platformUrl: "https://platform.vellum.ai",
+  },
+  staging: {
+    name: "staging",
+    platformUrl: "https://staging-platform.vellum.ai",
+  },
+  test: {
+    name: "test",
+    // Non-functional URL — used only by unit tests for URL resolution, never
+    // hit in production.
+    platformUrl: "https://test-platform.vellum.ai",
+  },
+  dev: {
+    name: "dev",
+    platformUrl: "https://dev-platform.vellum.ai",
+  },
+  local: {
+    name: "local",
+    platformUrl: "http://localhost:8000",
+    // assistantPlatformUrl: "http://host.docker.internal:8000",
+    // ^ uncomment this once dockerized hatch path is live.
+    // The assistant runs in a different network namespace than the host.
+  },
+};

package/src/lib/environments/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment type definitions. Environments are deployment targets with
+ * their own platform backend and their own isolated on-host state. See the
+ * "Coexisting environments" design doc for the full model.
+ */
+
+/**
+ * Per-service default port set. Phase 5 (per-environment port offsets) is
+ * deferred from MVP, so today every environment uses the same port set. The
+ * shape exists so the rest of the stack can call `getDefaultPorts(env)` and
+ * gain per-env offsets later without changing any call sites.
+ */
+export interface PortMap {
+  daemon: number;
+  gateway: number;
+  qdrant: number;
+  ces: number;
+  outboundProxy: number;
+  tcp: number;
+}
+
+/**
+ * A resolved environment definition. Required fields are `name` and
+ * `platformUrl`. All other fields are optional and declared upfront — new
+ * fields are additive, never breaking. `name` is intentionally typed as
+ * `string` (not `keyof SEEDS`) so custom environments can be represented by
+ * future layers (user config file, ad-hoc env vars, etc.).
+ */
+export interface EnvironmentDefinition {
+  name: string;
+  platformUrl: string;
+
+  /**
+   * Override for the platform URL the assistant process itself uses. Only
+   * differs from `platformUrl` when the assistant runs in a different network
+   * namespace than the host (e.g. Docker on macOS, where the host's localhost
+   * is reached via `host.docker.internal`). Falls back to `platformUrl` when
+   * unset.
+   */
+  assistantPlatformUrl?: string;
+
+  /** Human-readable label for UI surfaces. */
+  displayName?: string;
+
+  /** Hint for UI surfaces that want to tint or badge their display. */
+  tintColor?: string;
+
+  /** Per-service port overrides merged on top of defaults. */
+  portsOverride?: Partial<PortMap>;
+
+  /** Override for the XDG config directory. */
+  configDirOverride?: string;
+
+  /**
+   * Override for the directory containing the lockfile. Populated by the
+   * resolver from `VELLUM_LOCKFILE_DIR` (an existing e2e test escape hatch)
+   * so path helpers don't read env vars directly.
+   */
+  lockfileDirOverride?: string;
+}

package/src/lib/gcp.ts

@@ -503,7 +503,18 @@ export async function hatchGcp(
       }
     }
 
-    const sshUser = userInfo().username;
+    let sshUser: string;
+    try {
+      sshUser = userInfo().username;
+    } catch {
+      sshUser = process.env.USER ?? "";
+    }
+    if (!sshUser) {
+      console.error(
+        "Error: Could not determine SSH username. Set the USER environment variable and try again.",
+      );
+      process.exit(1);
+    }
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
     const providerApiKeys: Record<string, string> = {};
     for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {

package/src/lib/guardian-token.ts

@@ -7,9 +7,12 @@ import {
   readFileSync,
   writeFileSync,
 } from "fs";
-import { homedir, platform } from "os";
+import { platform } from "os";
 import { dirname, join } from "path";
 
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
 export interface GuardianTokenData {
@@ -24,14 +27,9 @@ export interface GuardianTokenData {
   leasedAt: string;
 }
 
-function getXdgConfigHome(): string {
-  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-}
-
 function getGuardianTokenPath(assistantId: string): string {
   return join(
-    getXdgConfigHome(),
-    "vellum",
+    getConfigDir(getCurrentEnvironment()),
     "assistants",
     assistantId,
     "guardian-token.json",
@@ -39,7 +37,7 @@ function getGuardianTokenPath(assistantId: string): string {
 }
 
 function getPersistedDeviceIdPath(): string {
-  return join(getXdgConfigHome(), "vellum", "device-id");
+  return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
 
 function hashWithSalt(input: string): string {
@@ -82,7 +80,7 @@ function getWindowsMachineGuid(): string | null {
   }
 }
 
-function getOrCreatePersistedDeviceId(): string {
+export function getOrCreatePersistedDeviceId(): string {
   const path = getPersistedDeviceIdPath();
   try {
     const existing = readFileSync(path, "utf-8").trim();
@@ -161,7 +159,7 @@ export function saveGuardianToken(
 /**
  * Call POST /v1/guardian/init on the remote gateway to bootstrap a JWT
  * credential pair. The returned tokens are persisted locally under
- * `$XDG_CONFIG_HOME/vellum/assistants/<assistantId>/guardian-token.json`.
+ * `$XDG_CONFIG_HOME/vellum{-env}/assistants/<assistantId>/guardian-token.json`.
  */
 export async function leaseGuardianToken(
   gatewayUrl: string,

package/src/lib/hatch-local.ts

@@ -312,20 +312,9 @@ export async function hatchLocal(
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
-  }
-
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config. Keep the
+  // lockfile save/sync inside the same scope so syncConfigToLockfile() reads
+  // this instance's workspace/config.json rather than a stale default path.
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
@@ -333,13 +322,29 @@ export async function hatchLocal(
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
-    serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources: { ...resources, signingKey },
   };
-  emitProgress(7, 7, "Saving configuration...");
-  saveAssistantEntry(localEntry);
-  setActiveAssistant(instanceName);
-  syncConfigToLockfile();
+
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  try {
+    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+    if (ngrokChild?.pid) {
+      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+    }
+
+    emitProgress(7, 7, "Saving configuration...");
+    saveAssistantEntry(localEntry);
+    setActiveAssistant(instanceName);
+    syncConfigToLockfile();
+  } finally {
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
+    }
+  }
 
   if (process.env.VELLUM_DESKTOP_APP) {
     installCLISymlink();

package/src/lib/local.ts

@@ -283,12 +283,18 @@ async function startDaemonFromSource(
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_CLOUD: "local",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -404,12 +410,18 @@ async function startDaemonWatchFromSource(
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -855,11 +867,16 @@ export async function startLocalDaemon(
         HOME: process.env.HOME || home,
         PATH: [...extraDirs, basePath].filter(Boolean).join(":"),
       };
-      // Forward optional config env vars the daemon may need
+      // Forward optional config env vars the daemon may need.
+      // `VELLUM_ENVIRONMENT` must be forwarded so the daemon resolves
+      // env-scoped paths (device ID, platform/guardian tokens, XDG
+      // config dir) to the same location as the CLI that spawned it.
       for (const key of [
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
+        "GATEWAY_SECURITY_DIR",
+        "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
@@ -885,6 +902,11 @@ export async function startLocalDaemon(
       // all paths under the instance directory and listens on its own port.
       if (resources) {
         daemonEnv.BASE_DATA_DIR = resources.instanceDir;
+        daemonEnv.GATEWAY_SECURITY_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "protected",
+        );
         daemonEnv.RUNTIME_HTTP_PORT = String(resources.daemonPort);
         daemonEnv.GATEWAY_PORT = String(resources.gatewayPort);
         daemonEnv.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -1043,10 +1065,29 @@ export async function startGateway(
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
-    ...(watch ? { VELLUM_DEV: "1" } : {}),
-    // Set BASE_DATA_DIR so the gateway loads the correct credentials and
-    // workspace config for this instance (mirrors the daemon env setup).
-    ...(resources ? { BASE_DATA_DIR: resources.instanceDir } : {}),
+    ...(watch
+      ? {
+          VELLUM_DEV: "1",
+          VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
+        }
+      : {}),
+    // Set VELLUM_WORKSPACE_DIR and GATEWAY_SECURITY_DIR so the gateway
+    // loads the correct credentials and workspace config for this instance
+    // (mirrors the daemon env setup).
+    ...(resources
+      ? {
+          VELLUM_WORKSPACE_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "workspace",
+          ),
+          GATEWAY_SECURITY_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "protected",
+          ),
+        }
+      : {}),
   };
   if (publicUrl) {
     console.log(`   Ingress URL: ${publicUrl}`);

package/src/lib/orphan-detection.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
+import { loadAllAssistants } from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -72,20 +73,35 @@ export interface OrphanedProcess {
 export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
-  const vellumDir = join(homedir(), ".vellum");
 
-  // Strategy 1: PID file scan
-  const pidFiles: Array<{ file: string; name: string }> = [
-    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
-    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
-    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
-  ];
+  // Collect every known local instance's `.vellum/` directory from the
+  // lockfile so orphan detection scans all containers under the current
+  // multi-instance data layout, not just the legacy `~/.vellum/` root.
+  const dirs = new Set<string>();
+  for (const entry of loadAllAssistants()) {
+    if (entry.cloud !== "local" || !entry.resources) continue;
+    dirs.add(join(entry.resources.instanceDir, ".vellum"));
+  }
+  // Preserve the legacy root scan for installs that predate multi-instance
+  // tracking. This catches orphans from a pre-upgrade `~/.vellum/` that
+  // may not have a lockfile entry at all.
+  dirs.add(join(homedir(), ".vellum"));
+
+  // Strategy 1: PID file scan — check every known data directory.
+  for (const dir of dirs) {
+    const pidFiles: Array<{ file: string; name: string }> = [
+      { file: join(dir, "vellum.pid"), name: "assistant" },
+      { file: join(dir, "gateway.pid"), name: "gateway" },
+      { file: join(dir, "qdrant.pid"), name: "qdrant" },
+    ];
 
-  for (const { file, name } of pidFiles) {
-    const pid = readPidFile(file);
-    if (pid && isProcessAlive(pid)) {
-      results.push({ name, pid, source: "pid file" });
-      seenPids.add(pid);
+    for (const { file, name } of pidFiles) {
+      const pid = readPidFile(file);
+      if (!pid || seenPids.has(pid)) continue;
+      if (isProcessAlive(pid)) {
+        results.push({ name, pid, source: "pid file" });
+        seenPids.add(pid);
+      }
     }
   }
 

package/src/lib/platform-client.ts

@@ -6,36 +6,37 @@ import {
   existsSync,
   mkdirSync,
 } from "fs";
-import { homedir } from "os";
 import { join, dirname } from "path";
 
-function getXdgConfigHome(): string {
-  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-}
+import { getLockfilePlatformBaseUrl } from "./assistant-config.js";
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 
 function getPlatformTokenPath(): string {
-  return join(getXdgConfigHome(), "vellum", "platform-token");
+  return join(getConfigDir(getCurrentEnvironment()), "platform-token");
 }
 
+/**
+ * Resolve the platform API base URL. Resolution order:
+ *   1. `platformBaseUrl` persisted on the lockfile by
+ *      {@link syncConfigToLockfile} when the active assistant was last
+ *      hatched/waked. This is the source of truth for "what URL does the
+ *      currently-active assistant target" — reading the workspace
+ *      `config.json` directly is incorrect for multi-instance and
+ *      non-production XDG layouts because the CLI process has no way to
+ *      know which instance to read from without first consulting the
+ *      lockfile anyway.
+ *   2. `VELLUM_PLATFORM_URL` env var (explicit override, e.g. in CI).
+ *   3. The current environment's seed URL (e.g. `https://dev-platform.vellum.ai`
+ *      for `VELLUM_ENVIRONMENT=dev`, `https://platform.vellum.ai` for prod).
+ *      This makes the CLI environment-aware when no lockfile entry exists yet.
+ */
 export function getPlatformUrl(): string {
-  let configUrl: string | undefined;
-  try {
-    const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-    const configPath = join(base, ".vellum", "workspace", "config.json");
-    if (existsSync(configPath)) {
-      const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-        string,
-        unknown
-      >;
-      const val = (raw.platform as Record<string, unknown> | undefined)
-        ?.baseUrl;
-      if (typeof val === "string" && val.trim()) configUrl = val.trim();
-    }
-  } catch {
-    // Config not available — fall through
-  }
+  const lockfileUrl = getLockfilePlatformBaseUrl();
   return (
-    configUrl || process.env.VELLUM_PLATFORM_URL || "https://platform.vellum.ai"
+    lockfileUrl ||
+    process.env.VELLUM_PLATFORM_URL?.trim() ||
+    getCurrentEnvironment().platformUrl
   );
 }
 
@@ -146,10 +147,173 @@ export interface HatchedAssistant {
   status: string;
 }
 
+export interface HatchAssistantResult {
+  assistant: HatchedAssistant;
+  /** true when the platform returned an existing assistant (HTTP 200) */
+  reusedExisting: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Self-hosted local assistant registration
+// ---------------------------------------------------------------------------
+
+export interface EnsureRegistrationResponse {
+  assistant: { id: string; name: string };
+  registration: {
+    client_installation_id: string;
+    runtime_assistant_id: string;
+    client_platform: string;
+  };
+  assistant_api_key: string | null;
+  webhook_secret: string;
+}
+
+/**
+ * Register (or re-confirm) a self-hosted local assistant with the platform.
+ *
+ * Calls `POST /v1/assistants/self-hosted-local/ensure-registration/`.
+ * The endpoint is idempotent: the first call provisions an API key;
+ * subsequent calls return `assistant_api_key: null`.
+ */
+export async function ensureSelfHostedLocalRegistration(
+  token: string,
+  organizationId: string,
+  clientInstallationId: string,
+  runtimeAssistantId: string,
+  clientPlatform: string,
+  assistantVersion?: string,
+  platformUrl?: string,
+): Promise<EnsureRegistrationResponse> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const body: Record<string, string> = {
+    client_installation_id: clientInstallationId,
+    runtime_assistant_id: runtimeAssistantId,
+    client_platform: clientPlatform,
+  };
+  if (assistantVersion) {
+    body.assistant_version = assistantVersion;
+  }
+
+  const response = await fetch(
+    `${resolvedUrl}/v1/assistants/self-hosted-local/ensure-registration/`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Session-Token": token,
+        "Vellum-Organization-Id": organizationId,
+      },
+      body: JSON.stringify(body),
+    },
+  );
+
+  if (response.status === 401 || response.status === 403) {
+    throw new Error("Authentication required for assistant registration.");
+  }
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Registration failed (${response.status}): ${detail || response.statusText}`,
+    );
+  }
+
+  return (await response.json()) as EnsureRegistrationResponse;
+}
+
+// ---------------------------------------------------------------------------
+// Credential injection into running assistant via gateway
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject a single credential into the assistant's secret store via the
+ * gateway's `POST /v1/secrets` endpoint.
+ *
+ * Mirrors the desktop app's `GatewayHTTPClient.post(path: "secrets", …)`
+ * calls in `LocalAssistantBootstrapService.swift`.
+ */
+async function injectGatewayCredential(
+  gatewayUrl: string,
+  name: string,
+  value: string,
+  bearerToken?: string,
+): Promise<boolean> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+  if (bearerToken) {
+    headers["Authorization"] = `Bearer ${bearerToken}`;
+  }
+
+  const response = await fetch(`${gatewayUrl}/v1/secrets`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ type: "credential", name, value }),
+    signal: AbortSignal.timeout(10_000),
+  });
+  return response.ok;
+}
+
+export interface CredentialInjectionParams {
+  gatewayUrl: string;
+  bearerToken?: string;
+  assistantApiKey?: string | null;
+  platformAssistantId: string;
+  platformBaseUrl: string;
+  organizationId: string;
+  userId?: string;
+  webhookSecret?: string | null;
+}
+
+/**
+ * Inject platform credentials into a running assistant via the gateway,
+ * mirroring `LocalAssistantBootstrapService.injectKeyIntoAssistant` et al.
+ *
+ * Each credential is posted individually. Failures are collected but do
+ * not prevent the remaining credentials from being injected.
+ *
+ * Returns true if all injections succeeded.
+ */
+export async function injectCredentialsIntoAssistant(
+  params: CredentialInjectionParams,
+): Promise<boolean> {
+  const inject = (name: string, value: string) =>
+    injectGatewayCredential(params.gatewayUrl, name, value, params.bearerToken);
+
+  const promises: Promise<boolean>[] = [];
+
+  if (params.assistantApiKey) {
+    promises.push(inject("vellum:assistant_api_key", params.assistantApiKey));
+  }
+
+  promises.push(
+    inject("vellum:platform_assistant_id", params.platformAssistantId),
+  );
+
+  promises.push(inject("vellum:platform_base_url", params.platformBaseUrl));
+
+  promises.push(
+    inject("vellum:platform_organization_id", params.organizationId),
+  );
+
+  if (params.userId) {
+    promises.push(inject("vellum:platform_user_id", params.userId));
+  }
+
+  if (params.webhookSecret) {
+    promises.push(inject("vellum:webhook_secret", params.webhookSecret));
+  }
+
+  const results = await Promise.all(promises);
+  return results.every(Boolean);
+}
+
 export async function hatchAssistant(
   token: string,
   platformUrl?: string,
-): Promise<HatchedAssistant> {
+): Promise<HatchAssistantResult> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/assistants/hatch/`;
 
@@ -160,7 +324,8 @@ export async function hatchAssistant(
   });
 
   if (response.ok) {
-    return (await response.json()) as HatchedAssistant;
+    const assistant = (await response.json()) as HatchedAssistant;
+    return { assistant, reusedExisting: response.status === 200 };
   }
 
   if (response.status === 401 || response.status === 403) {
@@ -186,6 +351,37 @@ export async function hatchAssistant(
   );
 }
 
+/**
+ * Lightweight pre-check: returns the first active managed assistant for the
+ * authenticated user, or `null` if none exists. Calls `GET /v1/assistants/`
+ * and looks for any assistant with status "active".
+ *
+ * Used by the teleport flow to block BEFORE the expensive GCS upload when
+ * the user already has a platform assistant.
+ */
+export async function checkExistingPlatformAssistant(
+  token: string,
+  platformUrl?: string,
+): Promise<HatchedAssistant | null> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/v1/assistants/`;
+
+  const response = await fetch(url, {
+    headers: await authHeaders(token, platformUrl),
+  });
+
+  if (!response.ok) {
+    // Non-fatal: if the list call fails, fall through and let hatch handle it.
+    return null;
+  }
+
+  const body = (await response.json()) as {
+    results?: HatchedAssistant[];
+  };
+  const active = body.results?.find((a) => a.status === "active");
+  return active ?? null;
+}
+
 export interface PlatformUser {
   id: string;
   email: string;