@vellumai/cli 0.6.3 → 0.6.5

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,307 @@ 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;
+}
+
+// ---------------------------------------------------------------------------
+// API key reprovisioning
+// ---------------------------------------------------------------------------
+
+export interface ReprovisionApiKeyResponse {
+  provisioning: {
+    assistant_api_key: string;
+  };
+}
+
+/**
+ * Reprovision (rotate) the API key for a self-hosted local assistant.
+ *
+ * Calls `POST /v1/assistants/self-hosted-local/reprovision-api-key/`.
+ * Returns a fresh API key. The previous key is revoked server-side.
+ */
+export async function reprovisionAssistantApiKey(
+  token: string,
+  organizationId: string,
+  clientInstallationId: string,
+  runtimeAssistantId: string,
+  clientPlatform: string,
+  assistantVersion?: string,
+  platformUrl?: string,
+): Promise<ReprovisionApiKeyResponse> {
+  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/reprovision-api-key/`,
+    {
+      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 API key reprovisioning.");
+  }
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `API key reprovisioning failed (${response.status}): ${detail || response.statusText}`,
+    );
+  }
+
+  return (await response.json()) as ReprovisionApiKeyResponse;
+}
+
+// ---------------------------------------------------------------------------
+// Credential reading from running assistant via gateway
+// ---------------------------------------------------------------------------
+
+export interface GatewayCredentialResult {
+  /** The credential value, if found. */
+  value: string | null;
+  /** True when the gateway/daemon was unreachable (network error, timeout, etc.). */
+  unreachable: boolean;
+}
+
+/**
+ * Read an existing credential from the assistant's secret store via the
+ * gateway-proxied `POST /v1/secrets/read` endpoint (with `reveal: true`).
+ *
+ * Returns a result distinguishing "key not found" (`value: null,
+ * unreachable: false`) from "gateway unreachable" (`value: null,
+ * unreachable: true`). Callers should only reprovision when the gateway
+ * is reachable but the key is genuinely missing — reprovisioning while
+ * the gateway is down would revoke the old key server-side without being
+ * able to inject the replacement.
+ *
+ * Never throws.
+ */
+export async function readGatewayCredential(
+  gatewayUrl: string,
+  name: string,
+  bearerToken?: string,
+): Promise<GatewayCredentialResult> {
+  try {
+    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/read`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ type: "credential", name, reveal: true }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      // 5xx means the gateway/daemon backend is down — treat as unreachable
+      // so callers don't revoke a potentially valid key.
+      return { value: null, unreachable: response.status >= 500 };
+    }
+
+    const json = (await response.json()) as {
+      found: boolean;
+      value?: string;
+      unreachable?: boolean;
+    };
+    // The daemon's /v1/secrets/read returns `unreachable: true` when the
+    // credential backend (CES) can't be reached. Respect that signal.
+    if (json.unreachable) {
+      return { value: null, unreachable: true };
+    }
+    return {
+      value: json.found && json.value ? json.value : null,
+      unreachable: false,
+    };
+  } catch {
+    // Network error, timeout, or gateway down
+    return { value: null, unreachable: true };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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 +458,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 +485,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;

package/src/lib/retire-apple-container.ts

@@ -0,0 +1,102 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config.js";
+
+/**
+ * Retire an Apple Container assistant by sending a retire command to the
+ * macOS app via the management socket. The app handles the full lifecycle:
+ * stop the pod, archive the instance directory, remove the guardian token,
+ * deregister from the platform, and remove the lockfile entry.
+ */
+export async function retireAppleContainer(
+  name: string,
+  entry: AssistantEntry,
+): Promise<void> {
+  console.log(`\u{1F5D1}\ufe0f  Retiring Apple Container assistant '${name}'...\n`);
+
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${name}'.\n` +
+        "The assistant may not be running. If the macOS app is closed, " +
+        "open it and try again.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped. Open the macOS app and try again.",
+    );
+    process.exit(1);
+  }
+
+  const handshake = JSON.stringify({ action: "retire" }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      socket.write(handshake);
+    });
+
+    const TIMEOUT_MS = 30_000;
+    const chunks: Buffer[] = [];
+    let totalLen = 0;
+
+    socket.setTimeout(TIMEOUT_MS);
+    socket.on("timeout", () => {
+      console.error("Timed out waiting for retire response from the macOS app.");
+      socket.destroy();
+      process.exit(1);
+    });
+
+    socket.on("data", (data: Buffer) => {
+      chunks.push(data);
+      totalLen += data.length;
+      const accumulated = Buffer.concat(chunks, totalLen);
+      const nlIndex = accumulated.indexOf(0x0a);
+      if (nlIndex === -1) return;
+
+      const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+      socket.destroy();
+
+      let response: { status: string; message?: string };
+      try {
+        response = JSON.parse(responseLine) as {
+          status: string;
+          message?: string;
+        };
+      } catch {
+        reject(new Error("Invalid response from management socket."));
+        return;
+      }
+
+      if (response.status === "ok") {
+        console.log(`\u2705 Apple Container assistant '${name}' retired.`);
+        resolve();
+      } else {
+        reject(
+          new Error(
+            `Retire failed: ${response.message || "unknown error"}`,
+          ),
+        );
+      }
+    });
+
+    socket.on("error", (err) => {
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("end", () => {
+      if (chunks.length === 0) {
+        reject(
+          new Error(
+            "Management socket closed without responding. " +
+              "The macOS app may have crashed during retire.",
+          ),
+        );
+      }
+    });
+  });
+}

package/src/lib/ssh-apple-container.ts

@@ -0,0 +1,166 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config";
+
+/**
+ * Connect to an Apple Container assistant via its management socket.
+ * Sends a JSON handshake then relays stdin/stdout in raw mode.
+ */
+export async function sshAppleContainer(
+  entry: AssistantEntry,
+  command?: string[],
+  service?: string,
+): Promise<void> {
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${entry.assistantId}'.\n` +
+        "The assistant may not have finished starting. Try again in a moment.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped. Run 'vellum hatch' to start it.",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `🔗 Connecting to ${entry.assistantId} via apple container exec...\n`,
+  );
+
+  const cols = process.stdout.columns || 120;
+  const rows = process.stdout.rows || 40;
+
+  const handshake =
+    JSON.stringify({
+      command: command && command.length > 0 ? command : ["/bin/bash"],
+      service: service || "vellum-assistant",
+      cols,
+      rows,
+    }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      // Send handshake as soon as connected.
+      socket.write(handshake);
+    });
+
+    // 10s handshake timeout — matches SSH ConnectTimeout.
+    const HANDSHAKE_TIMEOUT_MS = 10_000;
+    let handshakeComplete = false;
+    const handshakeChunks: Buffer[] = [];
+    let handshakeLen = 0;
+
+    socket.setTimeout(HANDSHAKE_TIMEOUT_MS);
+    socket.on("timeout", () => {
+      if (!handshakeComplete) {
+        console.error(
+          "Timed out waiting for handshake response from management socket.",
+        );
+        socket.destroy();
+        process.exit(1);
+      }
+      // After handshake, no timeout — interactive session runs indefinitely.
+    });
+
+    socket.on("data", (data: Buffer) => {
+      if (!handshakeComplete) {
+        // Accumulate raw buffers until we find a newline (end of JSON response).
+        handshakeChunks.push(data);
+        handshakeLen += data.length;
+        const accumulated = Buffer.concat(handshakeChunks, handshakeLen);
+        const nlIndex = accumulated.indexOf(0x0a);
+        if (nlIndex === -1) return; // Wait for more data.
+
+        const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+        const remainder = accumulated.slice(nlIndex + 1);
+        handshakeComplete = true;
+        socket.setTimeout(0); // Disable timeout for interactive session.
+
+        let response: { status: string; message?: string };
+        try {
+          response = JSON.parse(responseLine) as {
+            status: string;
+            message?: string;
+          };
+        } catch {
+          console.error("Invalid handshake response from management socket.");
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        if (response.status !== "ok") {
+          console.error(`Exec failed: ${response.message || "unknown error"}`);
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        // Handshake succeeded — enter raw mode and relay stdio.
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(true);
+        }
+        process.stdin.resume();
+        process.stdin.pipe(socket);
+
+        // Write any raw bytes that arrived after the handshake newline.
+        if (remainder.length > 0) {
+          process.stdout.write(remainder);
+        }
+
+        // From now on, relay socket data to stdout.
+        return;
+      }
+
+      // Raw mode: relay container output to stdout.
+      process.stdout.write(data);
+    });
+
+    socket.on("end", () => {
+      cleanup();
+      if (handshakeComplete) {
+        resolve();
+      } else {
+        reject(
+          new Error(
+            "Management socket closed before handshake completed. " +
+              "The assistant may be restarting.",
+          ),
+        );
+      }
+    });
+
+    socket.on("error", (err) => {
+      cleanup();
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("close", () => {
+      cleanup();
+      if (handshakeComplete) {
+        resolve();
+      } else {
+        reject(
+          new Error(
+            "Management socket closed before handshake completed. " +
+              "The assistant may be restarting.",
+          ),
+        );
+      }
+    });
+
+    function cleanup(): void {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      process.stdin.unpipe(socket);
+      process.stdin.pause();
+    }
+  });
+}