@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/src/lib/live-voice/tunnel.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  buildTunnelLiveVoiceUrl,
+  tunnelHostForPlatformUrl,
+  tunnelWsScheme,
+} from "./tunnel.js";
+
+const ORIGINAL_TUNNEL_HOST = process.env.CADET_TUNNEL_HOST;
+
+afterEach(() => {
+  if (ORIGINAL_TUNNEL_HOST === undefined) {
+    delete process.env.CADET_TUNNEL_HOST;
+  } else {
+    process.env.CADET_TUNNEL_HOST = ORIGINAL_TUNNEL_HOST;
+  }
+});
+
+describe("tunnelHostForPlatformUrl", () => {
+  test("maps a platform host onto its environment's tunnel", () => {
+    delete process.env.CADET_TUNNEL_HOST;
+    expect(tunnelHostForPlatformUrl("https://cloud.mycadet.ai")).toBe(
+      "tunnel.mycadet.ai",
+    );
+    expect(tunnelHostForPlatformUrl("https://dev-cloud.mycadet.ai")).toBe(
+      "tunnel-dev.mycadet.ai",
+    );
+  });
+
+  test("falls back to production tunnel for a host outside the convention", () => {
+    delete process.env.CADET_TUNNEL_HOST;
+    // A local platform predicts no tunnel of its own; guessing one would be
+    // worse than dialing the host that certainly exists.
+    expect(tunnelHostForPlatformUrl("http://localhost:8000")).toBe(
+      "tunnel.mycadet.ai",
+    );
+    expect(tunnelHostForPlatformUrl("not a url")).toBe("tunnel.mycadet.ai");
+  });
+
+  test("the env override wins, which is how a local vel up tunnel is reached", () => {
+    process.env.CADET_TUNNEL_HOST = "localhost:8501";
+    expect(tunnelHostForPlatformUrl("https://cloud.mycadet.ai")).toBe(
+      "localhost:8501",
+    );
+  });
+});
+
+describe("tunnelWsScheme", () => {
+  test("downgrades to ws only for loopback", () => {
+    expect(tunnelWsScheme("localhost:8501")).toBe("ws");
+    expect(tunnelWsScheme("127.0.0.1:8501")).toBe("ws");
+    expect(tunnelWsScheme("tunnel.mycadet.ai")).toBe("wss");
+  });
+});
+
+describe("buildTunnelLiveVoiceUrl", () => {
+  test("prefixes the assistant id, which is what selects the tunnel", () => {
+    delete process.env.CADET_TUNNEL_HOST;
+    const url = new URL(
+      buildTunnelLiveVoiceUrl({
+        platformUrl: "https://cloud.mycadet.ai",
+        assistantId: "01a02514-e452-7019-88d5-30828f42cf17",
+        token: "tok_abc",
+      }),
+    );
+
+    expect(url.protocol).toBe("wss:");
+    expect(url.host).toBe("tunnel.mycadet.ai");
+    expect(url.pathname).toBe(
+      "/01a02514-e452-7019-88d5-30828f42cf17/v1/live-voice",
+    );
+    expect(url.searchParams.get("token")).toBe("tok_abc");
+  });
+
+  test("encodes a token rather than letting it break the query", () => {
+    delete process.env.CADET_TUNNEL_HOST;
+    const url = new URL(
+      buildTunnelLiveVoiceUrl({
+        platformUrl: "https://cloud.mycadet.ai",
+        assistantId: "a1",
+        token: "a+b/c=&d",
+      }),
+    );
+    expect(url.searchParams.get("token")).toBe("a+b/c=&d");
+  });
+
+  test("uses ws against a loopback tunnel so a local stack is reachable", () => {
+    process.env.CADET_TUNNEL_HOST = "localhost:8501";
+    const url = new URL(
+      buildTunnelLiveVoiceUrl({
+        platformUrl: "http://localhost:8000",
+        assistantId: "a1",
+        token: "t",
+      }),
+    );
+    expect(url.protocol).toBe("ws:");
+    expect(url.host).toBe("localhost:8501");
+  });
+});

package/src/lib/live-voice/tunnel.ts

@@ -0,0 +1,200 @@
+/**
+ * The cloud leg of a live-voice session: minting a tunnel WS token and building
+ * the URL it opens.
+ *
+ * A platform-hosted assistant is not reachable the way a local one is. Its
+ * gateway sits behind tunnel, tunnel performs no user authentication of its own,
+ * and the gateway upstream accepts only an actor edge JWT or a tunnel
+ * attestation. The CLI holds neither for a cloud instance: what it has is a
+ * platform session token, which is the wrong credential for the socket but the
+ * right one for the platform.
+ *
+ * So the connection is made in two hops, the same two the web voice room makes
+ * (`clients/web/src/domains/chat/voice/live-voice/connection.ts`):
+ *
+ *  1. POST the platform for a short-lived, org+assistant-scoped WS token.
+ *  2. Open `wss://<tunnel>/<assistantId>/v1/live-voice?token=<wsToken>`.
+ *
+ * tunnel consumes the token on the upgrade and injects the authenticated user
+ * and org downstream as `X-Tunnel-*` headers alongside its bridge proof. The
+ * gateway reads that attestation rather than the query param, and pins it to
+ * the assistant's bound guardian (`requireManagedGuardian`). The token is
+ * therefore an admission ticket for one upgrade, not a session credential.
+ *
+ * Two properties of that ticket shape this module's API. It lives for
+ * `LIVE_VOICE_WS_TOKEN_TTL` (60 seconds) and it is **single-use**: the
+ * validator consumes it atomically, so the same token cannot open a second
+ * socket. Minting is consequently tied to connecting, and a reconnect has to
+ * mint again rather than reuse what resolution returned.
+ */
+
+import { tunnelHostForPlatformHost } from "@mycadet/service-contracts/ingress";
+
+import { authHeaders } from "../platform-client.js";
+
+/** Production tunnel, when the platform host implies nothing more specific. */
+const DEFAULT_TUNNEL_HOST = "tunnel.mycadet.ai";
+
+/** Give up on the mint rather than hang the session behind a stalled platform. */
+const MINT_TIMEOUT_MS = 10_000;
+
+export class TunnelWsTokenError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "TunnelWsTokenError";
+    this.status = status;
+  }
+}
+
+/**
+ * The tunnel host serving a given platform base URL.
+ *
+ * `CADET_TUNNEL_HOST` wins when set, which is how a local `vel up` stack is
+ * reached: its tunnel is a loopback port that no naming convention predicts.
+ * Otherwise the deployment convention maps the platform host onto its sibling
+ * (`cloud.mycadet.ai` to `tunnel.mycadet.ai`, `dev-cloud.mycadet.ai` to
+ * `tunnel-dev.mycadet.ai`). A host outside that convention, including localhost,
+ * yields the production default, because guessing a tunnel for it would be
+ * worse than dialing the one host that certainly exists.
+ */
+export function tunnelHostForPlatformUrl(platformUrl: string): string {
+  const override = process.env.CADET_TUNNEL_HOST?.trim();
+  if (override) {
+    return override;
+  }
+  try {
+    return (
+      tunnelHostForPlatformHost(new URL(platformUrl).host) ??
+      DEFAULT_TUNNEL_HOST
+    );
+  } catch {
+    return DEFAULT_TUNNEL_HOST;
+  }
+}
+
+/**
+ * `ws` for a loopback tunnel, `wss` for everything else.
+ *
+ * The local `vel up` tunnel is plain HTTP on a loopback port, which a `wss` dial
+ * cannot reach. Mirrors `getTunnelWsScheme` in the web client so the two ends of
+ * the transport cannot disagree about which scheme a host takes.
+ */
+export function tunnelWsScheme(host: string): "ws" | "wss" {
+  let hostname: string;
+  try {
+    ({ hostname } = new URL(`http://${host}`));
+  } catch {
+    return "wss";
+  }
+  return hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]" ||
+    hostname === "::1"
+    ? "ws"
+    : "wss";
+}
+
+/**
+ * Build the tunnel live-voice URL.
+ *
+ * The `/<assistantId>` prefix is what selects the tunnel: tunnel strips it to
+ * recover the upstream path, and matches that path against its allowlist and
+ * against the scope recorded for the token. The token rides as `?token=`
+ * because a WebSocket upgrade from a non-browser client still cannot carry a
+ * credential anywhere tunnel reads except the query string.
+ */
+export function buildTunnelLiveVoiceUrl(args: {
+  platformUrl: string;
+  assistantId: string;
+  token: string;
+}): string {
+  const host = tunnelHostForPlatformUrl(args.platformUrl);
+  const url = new URL(
+    `${tunnelWsScheme(host)}://${host}/${args.assistantId}/v1/live-voice`,
+  );
+  url.searchParams.set("token", args.token);
+  return url.toString();
+}
+
+interface LiveVoiceTokenResponse {
+  token?: unknown;
+  expiresAt?: unknown;
+}
+
+/**
+ * Mint a single-use tunnel WS token for one assistant.
+ *
+ * Authenticates with the CLI's stored platform session token. The mint
+ * endpoint pins its authenticators to the user-session ones
+ * (`SessionAuthentication` and `XSessionTokenAuthentication`) and deliberately
+ * excludes API-key auth, so `X-Session-Token` is the CLI's way in and a
+ * `vak_` key is not: a caller holding only an API key cannot mint here, by
+ * design on the platform's side.
+ *
+ * Throws {@link TunnelWsTokenError} carrying the HTTP status, so the caller can
+ * tell "sign in again" (401) from "not your assistant" (403) from a platform
+ * that is simply down.
+ */
+export async function mintTunnelWsToken(args: {
+  platformUrl: string;
+  assistantId: string;
+  sessionToken: string;
+}): Promise<string> {
+  const url = `${args.platformUrl.replace(/\/+$/, "")}/v1/auth/live-voice-token/`;
+  // `authHeaders` resolves `Cadet-Organization-Id`, which the endpoint needs
+  // to scope the token, and which is cached per token so a session does not
+  // pay for an extra round trip.
+  const headers = await authHeaders(args.sessionToken, args.platformUrl);
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ assistantId: args.assistantId }),
+      signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new TunnelWsTokenError(
+      0,
+      `Could not reach the Cadet Cloud to authorize the voice session: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  if (!response.ok) {
+    throw new TunnelWsTokenError(
+      response.status,
+      describeMintFailure(response.status),
+    );
+  }
+
+  const body = (await response.json().catch(() => ({}))) as
+    | LiveVoiceTokenResponse
+    | undefined;
+  const token = typeof body?.token === "string" ? body.token.trim() : "";
+  if (!token) {
+    throw new TunnelWsTokenError(
+      response.status,
+      "The Cadet Cloud returned no voice session token.",
+    );
+  }
+  return token;
+}
+
+/** Turn a mint rejection into something the user can act on. */
+function describeMintFailure(status: number): string {
+  if (status === 401) {
+    return "Not signed in to the Cadet Cloud. Run 'cadet login' and try again.";
+  }
+  if (status === 403) {
+    return "This account cannot open a voice session on that assistant. Check that it belongs to the organization you are signed in to.";
+  }
+  if (status === 404) {
+    return "The Cadet Cloud does not offer voice session tokens. It may be running an older release.";
+  }
+  return `The Cadet Cloud refused to authorize the voice session (HTTP ${status}).`;
+}

package/src/lib/local-hatch-lock.ts

@@ -0,0 +1,335 @@
+import { execFileSync } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "fs";
+import { hostname, platform, userInfo } from "os";
+import { dirname, join } from "path";
+
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_RETRY_MS = 100;
+const MAX_LOCK_AGE_MS = DEFAULT_TIMEOUT_MS - 60_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const LIVE_OWNER_RECOVERY_GRACE_MS = 10_000;
+
+interface LocalHatchLockOptions {
+  lockPath?: string;
+  liveOwnerRecoveryGraceMs?: number;
+  timeoutMs?: number;
+  retryMs?: number;
+}
+
+interface LockOwner {
+  pid: number;
+  processStartedAt?: string;
+  token: string;
+}
+
+interface LockSnapshot {
+  owner?: LockOwner;
+  signature: string;
+}
+
+export function resolveLocalHatchLockPath(): string {
+  const machineKey = createHash("sha256")
+    .update(hostname())
+    .digest("hex")
+    .slice(0, 12);
+  return join(
+    userInfo().homedir,
+    ".cache",
+    "cadet",
+    "runtime",
+    machineKey,
+    "local-hatch.lock",
+  );
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function processStartedAt(pid: number): string | undefined {
+  const [file, args] =
+    platform() === "win32"
+      ? [
+          "powershell.exe",
+          [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}').CreationDate.ToString('o')`,
+          ],
+        ]
+      : ["ps", ["-o", "lstart=", "-p", String(pid)]];
+  try {
+    const value = execFileSync(file, args, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: platform() === "win32" ? 5_000 : 1_000,
+      windowsHide: true,
+    }).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseOwner(raw: string): LockOwner | undefined {
+  try {
+    const parsed = JSON.parse(raw) as {
+      pid?: unknown;
+      processStartedAt?: unknown;
+      token?: unknown;
+    };
+    if (
+      typeof parsed.pid === "number" &&
+      Number.isInteger(parsed.pid) &&
+      parsed.pid > 0 &&
+      typeof parsed.token === "string" &&
+      parsed.token.length > 0
+    ) {
+      return {
+        pid: parsed.pid,
+        processStartedAt:
+          typeof parsed.processStartedAt === "string" &&
+          parsed.processStartedAt.length > 0
+            ? parsed.processStartedAt
+            : undefined,
+        token: parsed.token,
+      };
+    }
+  } catch {}
+  return undefined;
+}
+
+function readSnapshot(path: string): LockSnapshot | undefined {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return {
+      owner: parseOwner(raw),
+      signature: createHash("sha256").update(raw).digest("hex"),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readOwner(path: string): LockOwner | undefined {
+  return readSnapshot(path)?.owner;
+}
+
+function fileAgeMs(path: string): number | undefined {
+  try {
+    return Date.now() - statSync(path).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+const expiredLiveOwners = new Map<string, number>();
+
+function ownerIsActive(
+  path: string,
+  owner: LockOwner | undefined,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const ageMs = fileAgeMs(path);
+  if (!owner) {
+    return ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS;
+  }
+  if (!processIsAlive(owner.pid)) {
+    return false;
+  }
+  if (owner.processStartedAt) {
+    const currentStartedAt = processStartedAt(owner.pid);
+    if (currentStartedAt) {
+      expiredLiveOwners.delete(owner.token);
+      return currentStartedAt === owner.processStartedAt;
+    }
+  }
+  if (ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS) {
+    expiredLiveOwners.delete(owner.token);
+    return true;
+  }
+
+  const firstExpiredAt = expiredLiveOwners.get(owner.token) ?? Date.now();
+  expiredLiveOwners.set(owner.token, firstExpiredAt);
+  if (Date.now() - firstExpiredAt < liveOwnerRecoveryGraceMs) {
+    return true;
+  }
+  return false;
+}
+
+function writeOwnerFile(path: string, owner: LockOwner): void {
+  const fd = openSync(path, "wx", 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(owner) + "\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function acquireRecoveryClaim(
+  lockPath: string,
+  staleSignature: string,
+  owner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): (() => void) | undefined {
+  const recoveryKey = staleSignature.slice(0, 16);
+  for (let generation = 0; generation < 100; generation++) {
+    const claimPath = `${lockPath}.recovery-${recoveryKey}-${generation}`;
+    try {
+      writeOwnerFile(claimPath, owner);
+      return () => releaseLock(claimPath, owner.token);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (
+        ownerIsActive(claimPath, readOwner(claimPath), liveOwnerRecoveryGraceMs)
+      ) {
+        return undefined;
+      }
+    }
+  }
+  return undefined;
+}
+
+function removeStaleLock(
+  lockPath: string,
+  recoveryOwner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const staleSnapshot = readSnapshot(lockPath);
+  if (!staleSnapshot) {
+    return true;
+  }
+  if (ownerIsActive(lockPath, staleSnapshot.owner, liveOwnerRecoveryGraceMs)) {
+    return false;
+  }
+
+  const releaseRecoveryClaim = acquireRecoveryClaim(
+    lockPath,
+    staleSnapshot.signature,
+    recoveryOwner,
+    liveOwnerRecoveryGraceMs,
+  );
+  if (!releaseRecoveryClaim) {
+    return false;
+  }
+
+  try {
+    const currentSnapshot = readSnapshot(lockPath);
+    if (!currentSnapshot) {
+      return true;
+    }
+    if (currentSnapshot.signature !== staleSnapshot.signature) {
+      return false;
+    }
+    if (
+      ownerIsActive(lockPath, currentSnapshot.owner, liveOwnerRecoveryGraceMs)
+    ) {
+      return false;
+    }
+    try {
+      unlinkSync(lockPath);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ENOENT";
+    }
+  } finally {
+    releaseRecoveryClaim();
+  }
+}
+
+function releaseLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function refreshLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    const now = new Date();
+    utimesSync(lockPath, now, now);
+  } catch {}
+}
+
+/**
+ * Serialize local assistant startup across CLI processes. Port availability is
+ * machine-wide even when callers use different lockfile or XDG directories,
+ * so allocation must remain exclusive until the new services have bound their
+ * ports and the assistant entry has been persisted.
+ */
+export async function withLocalHatchLock<T>(
+  action: () => Promise<T>,
+  options: LocalHatchLockOptions = {},
+): Promise<T> {
+  const lockPath = options.lockPath ?? resolveLocalHatchLockPath();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+  const liveOwnerRecoveryGraceMs =
+    options.liveOwnerRecoveryGraceMs ?? LIVE_OWNER_RECOVERY_GRACE_MS;
+  const deadline = Date.now() + timeoutMs;
+  const owner: LockOwner = {
+    pid: process.pid,
+    processStartedAt: processStartedAt(process.pid),
+    token: `${process.pid}-${randomUUID()}`,
+  };
+
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+
+  while (true) {
+    try {
+      writeOwnerFile(lockPath, owner);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (removeStaleLock(lockPath, owner, liveOwnerRecoveryGraceMs)) {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for another local assistant to finish starting (${lockPath})`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryMs));
+      continue;
+    }
+
+    const heartbeat = setInterval(
+      () => refreshLock(lockPath, owner.token),
+      HEARTBEAT_INTERVAL_MS,
+    );
+    try {
+      return await action();
+    } finally {
+      clearInterval(heartbeat);
+      releaseLock(lockPath, owner.token);
+    }
+  }
+}