@vellumai/cli 0.6.5 → 0.7.0

package/src/lib/local.ts

@@ -1,5 +1,5 @@
 import { execFileSync, execSync, spawn } from "child_process";
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import {
   existsSync,
   mkdirSync,
@@ -8,10 +8,13 @@ import {
   writeFileSync,
 } from "fs";
 import { createRequire } from "module";
-import { homedir, hostname, networkInterfaces, platform } from "os";
+import { homedir, hostname, networkInterfaces, platform, tmpdir } from "os";
 import { dirname, join } from "path";
 
-import { type LocalInstanceResources } from "./assistant-config.js";
+import {
+  getDaemonPidPath,
+  type LocalInstanceResources,
+} from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
 import { stopProcessByPidFile } from "./process.js";
@@ -19,6 +22,107 @@ import { openLogFile, pipeToLogFile } from "./xdg-log.js";
 
 const _require = createRequire(import.meta.url);
 
+// macOS AF_UNIX path limit (sun_path is 104 bytes, null-terminated → 103 usable).
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+
+// The longest socket filename we place in the workspace directory.
+// assistant-skill.sock = 20 chars, plus 1 for the "/" separator = 21 overhead.
+const LONGEST_SOCKET_FILENAME = "assistant-skill.sock";
+
+/**
+ * Warn when an assistant appears to have legacy data in the global workspace.
+ *
+ * Old local startup paths could launch the daemon without
+ * `VELLUM_WORKSPACE_DIR`, causing writes to fall back to `~/.vellum/workspace`.
+ * New local instance launches pin the workspace under
+ * `<instanceDir>/.vellum/workspace`. If we detect data only in the legacy
+ * global path, warn with migration instructions so users are not surprised by
+ * missing history/settings after the fix.
+ */
+function warnIfLegacyWorkspaceFallbackDetected(
+  resources: LocalInstanceResources,
+): void {
+  const instanceWorkspace = join(resources.instanceDir, ".vellum", "workspace");
+  const instanceDbPath = join(instanceWorkspace, "data", "db", "assistant.db");
+
+  const legacyWorkspace = join(homedir(), ".vellum", "workspace");
+  const legacyDbPath = join(legacyWorkspace, "data", "db", "assistant.db");
+
+  // Legacy "first local" entries use ~/.vellum directly; no drift possible.
+  if (instanceWorkspace === legacyWorkspace) return;
+
+  if (existsSync(legacyDbPath) && !existsSync(instanceDbPath)) {
+    console.warn("");
+    console.warn(
+      "WARNING: Detected legacy workspace data in ~/.vellum/workspace for this local assistant.",
+    );
+    console.warn("   What this means:");
+    console.warn(
+      "   - An older startup path likely wrote assistant data to the global workspace.",
+    );
+    console.warn(
+      "   - This assistant now uses its instance workspace instead:",
+    );
+    console.warn(`     ${instanceWorkspace}`);
+    console.warn("   What to do:");
+    console.warn(
+      "   1. Stop the assistant before migrating files (retire/sleep or quit app).",
+    );
+    console.warn(
+      "   2. Copy needed data from ~/.vellum/workspace into the instance workspace.",
+    );
+    console.warn(
+      `      Example: cp -a ~/.vellum/workspace/data/db/assistant.db* ${join(instanceWorkspace, "data", "db")}/`,
+    );
+    console.warn(
+      "   3. Re-launch and confirm history/settings appear as expected.",
+    );
+    console.warn("");
+  }
+}
+
+/**
+ * On macOS, if `{workspaceDir}/assistant-skill.sock` would exceed the
+ * 103-byte AF_UNIX path limit, compute a short tmpdir-based IPC socket
+ * directory and return it.  Returns `undefined` when no override is needed
+ * (the workspace path is short enough, or we're not on macOS).
+ */
+function computeIpcSocketDirOverride(workspaceDir: string): string | undefined {
+  if (platform() !== "darwin") return undefined;
+
+  const longestPath = join(workspaceDir, LONGEST_SOCKET_FILENAME);
+  if (
+    Buffer.byteLength(longestPath, "utf8") <= DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+  ) {
+    return undefined;
+  }
+
+  // Use a short hash of the workspace dir so multiple instances get
+  // distinct socket directories under /tmp.
+  const hash = createHash("sha256")
+    .update(workspaceDir)
+    .digest("hex")
+    .slice(0, 12);
+  return join(tmpdir(), `vellum-ipc-${hash}`);
+}
+
+/**
+ * If the workspace path is too long for AF_UNIX sockets on macOS, compute
+ * a short override directory and set all IPC socket env vars on the target
+ * env object. No-op on non-macOS or when paths are within limits.
+ */
+function applyIpcSocketDirOverride(env: Record<string, string>): void {
+  const workspaceDir =
+    env.VELLUM_WORKSPACE_DIR || join(homedir(), ".vellum", "workspace");
+  const override = computeIpcSocketDirOverride(workspaceDir);
+  if (!override) return;
+
+  mkdirSync(override, { recursive: true });
+  env.GATEWAY_IPC_SOCKET_DIR = override;
+  env.ASSISTANT_IPC_SOCKET_DIR = override;
+  env.ASSISTANT_SKILL_IPC_SOCKET_DIR = override;
+}
+
 function isAssistantSourceDir(dir: string): boolean {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts")))
@@ -222,10 +326,9 @@ async function startDaemonFromSource(
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
 
   // Ensure the directory containing PID/socket files exists. For named
-  // instances this is instanceDir/.vellum/ (matching daemon's getRootDir()).
-  mkdirSync(dirname(resources.pidFile), { recursive: true });
-
-  const pidFile = resources.pidFile;
+  // instances this is instanceDir/.vellum/workspace/ (matching daemon's getWorkspaceDir()).
+  const pidFile = getDaemonPidPath(resources);
+  mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   if (existsSync(pidFile)) {
@@ -290,6 +393,11 @@ async function startDaemonFromSource(
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.VELLUM_WORKSPACE_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
     env.GATEWAY_SECURITY_DIR = join(
       resources.instanceDir,
       ".vellum",
@@ -349,9 +457,8 @@ async function startDaemonWatchFromSource(
     throw new Error(`Daemon main.ts not found at ${mainPath}`);
   }
 
-  mkdirSync(dirname(resources.pidFile), { recursive: true });
-
-  const pidFile = resources.pidFile;
+  const pidFile = getDaemonPidPath(resources);
+  mkdirSync(dirname(pidFile), { recursive: true });
 
   // --- Lifecycle guard: prevent split-brain daemon state ---
   // If a daemon is already running, skip spawning a new one.
@@ -417,6 +524,11 @@ async function startDaemonWatchFromSource(
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.VELLUM_WORKSPACE_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
     env.GATEWAY_SECURITY_DIR = join(
       resources.instanceDir,
       ".vellum",
@@ -769,6 +881,8 @@ export async function startLocalDaemon(
   resources: LocalInstanceResources,
   options?: DaemonStartOptions,
 ): Promise<void> {
+  warnIfLegacyWorkspaceFallbackDetected(resources);
+
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.
   // This covers both the desktop app (VELLUM_DESKTOP_APP) and the case where
@@ -779,7 +893,7 @@ export async function startLocalDaemon(
     // In watch mode, skip the bundled binary and use source (bun --watch
     // only works with source files, not compiled binaries).
 
-    const pidFile = resources.pidFile;
+    const pidFile = getDaemonPidPath(resources);
 
     // If a daemon is already running, skip spawning a new one.
     // This prevents cascading kill→restart cycles when multiple callers
@@ -902,6 +1016,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.VELLUM_WORKSPACE_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "workspace",
+        );
         daemonEnv.GATEWAY_SECURITY_DIR = join(
           resources.instanceDir,
           ".vellum",
@@ -917,6 +1036,8 @@ export async function startLocalDaemon(
         daemonEnv.ACTOR_TOKEN_SIGNING_KEY = options.signingKey;
       }
 
+      applyIpcSocketDirOverride(daemonEnv);
+
       // Write a sentinel PID file before spawning so concurrent hatch() calls
       // see the file and fall through to the isDaemonResponsive() port check
       // instead of racing to spawn a duplicate daemon.
@@ -1071,9 +1192,9 @@ export async function startGateway(
           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).
+    // Pin gateway workspace/security paths to the named instance so parent
+    // env vars cannot leak a different workspace. The gateway opens the
+    // assistant DB directly for guardian bootstrap.
     ...(resources
       ? {
           BASE_DATA_DIR: resources.instanceDir,
@@ -1090,6 +1211,9 @@ export async function startGateway(
         }
       : {}),
   };
+
+  applyIpcSocketDirOverride(gatewayEnv);
+
   if (publicUrl) {
     console.log(`   Ingress URL: ${publicUrl}`);
   }
@@ -1186,7 +1310,7 @@ export async function stopLocalProcesses(
   const vellumDir = resources
     ? join(resources.instanceDir, ".vellum")
     : join(homedir(), ".vellum");
-  const daemonPidFile = resources?.pidFile ?? join(vellumDir, "vellum.pid");
+  const daemonPidFile = getDaemonPidPath(resources);
   await stopProcessByPidFile(daemonPidFile, "daemon");
 
   const gatewayPidFile = join(vellumDir, "gateway.pid");

package/src/lib/orphan-detection.ts

@@ -1,8 +1,5 @@
 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 {
@@ -74,38 +71,8 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
 
-  // 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 || seenPids.has(pid)) continue;
-      if (isProcessAlive(pid)) {
-        results.push({ name, pid, source: "pid file" });
-        seenPids.add(pid);
-      }
-    }
-  }
-
-  // Strategy 2: Process table scan
+  // Process table scan — discover orphaned processes by scanning the OS
+  // process table rather than reading PID files from the workspace.
   try {
     const output = await execOutput("sh", [
       "-c",

package/src/lib/platform-client.ts

@@ -40,6 +40,19 @@ export function getPlatformUrl(): string {
   );
 }
 
+/**
+ * Resolve the web app (Next.js) base URL for browser-facing pages like
+ * `/account/login`. Mirrors `VellumEnvironment.resolvedWebURL` on the
+ * Swift side.
+ *
+ * Resolution order:
+ *   1. `VELLUM_WEB_URL` env var (explicit override)
+ *   2. The current environment's seed web URL
+ */
+export function getWebUrl(): string {
+  return process.env.VELLUM_WEB_URL?.trim() || getCurrentEnvironment().webUrl;
+}
+
 export function readPlatformToken(): string | null {
   try {
     return readFileSync(getPlatformTokenPath(), "utf-8").trim();
@@ -516,6 +529,30 @@ export async function checkExistingPlatformAssistant(
   return active ?? null;
 }
 
+/**
+ * Fetch all active assistants for the authenticated user from the platform.
+ * Returns an empty array on failure (non-fatal).
+ */
+export async function fetchPlatformAssistants(
+  token: string,
+  platformUrl?: string,
+): Promise<HatchedAssistant[]> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/v1/assistants/`;
+
+  const response = await fetch(url, {
+    headers: await authHeaders(token, platformUrl),
+  });
+
+  if (!response.ok) return [];
+
+  const body = (await response.json()) as {
+    results?: HatchedAssistant[];
+  };
+
+  return (body.results ?? []).filter((a) => a.status === "active");
+}
+
 export interface PlatformUser {
   id: string;
   email: string;
@@ -913,3 +950,181 @@ export async function platformPollImportStatus(
     error: body.error,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Unified signed-url + job-status endpoints (teleport-gcs-unify)
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union representing the unified migration job status shape
+ * returned by `GET /v1/migrations/jobs/{job_id}/` on both the platform and
+ * the local runtime.
+ */
+export type UnifiedJobStatus =
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "processing";
+    }
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "complete";
+      bundleKey?: string;
+      result?: unknown;
+    }
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "failed";
+      error: string;
+    };
+
+interface RawUnifiedJobStatus {
+  job_id: string;
+  type: "export" | "import";
+  status: "processing" | "complete" | "failed";
+  bundle_key?: string;
+  result?: unknown;
+  error?: string;
+}
+
+/**
+ * Normalise the wire-format job-status payload into the TypeScript
+ * discriminated union. Shared between platform and local-runtime helpers
+ * since both endpoints return the same shape.
+ */
+export function parseUnifiedJobStatus(
+  raw: RawUnifiedJobStatus,
+): UnifiedJobStatus {
+  if (raw.status === "processing") {
+    return { jobId: raw.job_id, type: raw.type, status: "processing" };
+  }
+  if (raw.status === "complete") {
+    return {
+      jobId: raw.job_id,
+      type: raw.type,
+      status: "complete",
+      bundleKey: raw.bundle_key,
+      result: raw.result,
+    };
+  }
+  return {
+    jobId: raw.job_id,
+    type: raw.type,
+    status: "failed",
+    error: raw.error ?? "Job failed without an error message",
+  };
+}
+
+/**
+ * Request a signed URL from the platform for either uploading a new bundle
+ * or downloading an existing one. Calls `POST /v1/migrations/signed-url/`.
+ *
+ * - `operation: "upload"` (optionally with `contentType` / `contentLength`)
+ *   returns a URL the CLI can PUT a bundle to.
+ * - `operation: "download"` with a `bundleKey` returns a URL the local
+ *   runtime can GET the bundle from during an import-from-GCS flow.
+ *
+ * Retries once with a fresh org-ID cache on 401 to match the retry pattern
+ * used by other authenticated platform helpers. 503 is bubbled up so
+ * callers can decide to fall back (e.g. legacy inline upload).
+ */
+export async function platformRequestSignedUrl(
+  params: {
+    operation: "upload" | "download";
+    bundleKey?: string;
+    contentType?: string;
+    contentLength?: number;
+  },
+  token: string,
+  platformUrl?: string,
+): Promise<{
+  url: string;
+  bundleKey: string;
+  expiresAt: string;
+  maxContentLength?: number;
+}> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const body: Record<string, unknown> = { operation: params.operation };
+  if (params.bundleKey !== undefined) body.bundle_key = params.bundleKey;
+  if (params.contentType !== undefined) body.content_type = params.contentType;
+  if (params.contentLength !== undefined) {
+    body.content_length = params.contentLength;
+  }
+
+  const doRequest = async (): Promise<Response> =>
+    fetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
+      method: "POST",
+      headers: await authHeaders(token, platformUrl),
+      body: JSON.stringify(body),
+    });
+
+  let response = await doRequest();
+
+  if (response.status === 401) {
+    // Invalidate the cached org-ID (if any) and retry once with a fresh
+    // lookup. For session-token callers, a 401 frequently means the
+    // cached org ID is stale — calling doRequest() again without clearing
+    // the cache would just send the same stale header and fail again.
+    orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+    response = await doRequest();
+  }
+
+  if (response.status === 201 || response.status === 200) {
+    const json = (await response.json()) as {
+      url: string;
+      bundle_key: string;
+      expires_at: string;
+      max_content_length?: number;
+    };
+    return {
+      url: json.url,
+      bundleKey: json.bundle_key,
+      expiresAt: json.expires_at,
+      maxContentLength: json.max_content_length,
+    };
+  }
+
+  if (response.status === 503) {
+    throw new Error(
+      `Signed URL endpoint unavailable (503) — caller may fall back`,
+    );
+  }
+
+  const errorBody = (await response.json().catch(() => ({}))) as {
+    detail?: string;
+  };
+  throw new Error(
+    errorBody.detail ??
+      `Failed to request signed URL: ${response.status} ${response.statusText}`,
+  );
+}
+
+/**
+ * Poll the unified job-status endpoint on the platform. Calls
+ * `GET /v1/migrations/jobs/{jobId}/` and parses into {@link UnifiedJobStatus}.
+ */
+export async function platformPollJobStatus(
+  jobId: string,
+  token: string,
+  platformUrl?: string,
+): Promise<UnifiedJobStatus> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/migrations/jobs/${jobId}/`, {
+    headers: await authHeaders(token, platformUrl),
+  });
+
+  if (response.status === 404) {
+    throw new Error("Migration job not found");
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Job status check failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const raw = (await response.json()) as RawUnifiedJobStatus;
+  return parseUnifiedJobStatus(raw);
+}

package/src/lib/retire-local.ts

@@ -2,7 +2,11 @@ import { spawn } from "child_process";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 
-import { getBaseDir, loadAllAssistants } from "./assistant-config.js";
+import {
+  getBaseDir,
+  getDaemonPidPath,
+  loadAllAssistants,
+} from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import {
   stopOrphanedDaemonProcesses,
@@ -41,7 +45,7 @@ export async function retireLocal(
     return;
   }
 
-  const daemonPidFile = resources.pidFile;
+  const daemonPidFile = getDaemonPidPath(resources);
   const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon");
 
   // Stop gateway via PID file — use a longer timeout because the gateway has a