@mycadet/cli 0.12.10 → 0.13.0-dev.202610171617.9ea363e

package/src/lib/root-signing-key.ts

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** Persist gateway identity in the service root without following an existing file link. */
+export function persistRootSigningKey(root: string, key: string): void {
+  if (!/^[a-f0-9]{64}$/i.test(key)) {
+    throw new Error("Invalid gateway signing key.");
+  }
+  const directory = join(root, "gateway-security");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (!lstatSync(directory).isDirectory()) {
+    throw new Error("Gateway security root must be a directory.");
+  }
+  const temporary = join(directory, `.signing-key-${randomUUID()}`);
+  try {
+    writeFileSync(temporary, Buffer.from(key, "hex"), {
+      mode: 0o600,
+      flag: "wx",
+    });
+    renameSync(temporary, join(directory, "actor-token-signing-key"));
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}

package/src/lib/runtime-url.ts

@@ -4,35 +4,6 @@ import { hostname } from "node:os";
 import { getLocalLanIPv4 } from "./local";
 import type { AssistantEntry } from "./assistant-config.js";
 
-/**
- * Resolve the URL for a runtime migration endpoint, taking the assistant's
- * topology into account.
- *
- * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
- *   the runtime serves `/v1/migrations/<subpath>` directly. The CLI hits
- *   that path with guardian-token bearer auth.
- * - For cloud-managed (cloud="cadet") assistants, `runtimeUrl` is the
- *   platform host (e.g. `https://cloud.mycadet.ai`). The cloud's
- *   `MigrationViewSet` does NOT expose `export-to-gcs` or arbitrary runtime
- *   migration paths under `/v1/migrations/...`. The wildcard runtime proxy
- *   at `/v1/assistants/<id>/<path:rest>` is what forwards arbitrary runtime
- *   paths to the cloud runtime — vembda's unified proxy bootstraps the
- *   guardian token internally for the runtime call. From the CLI side it's
- *   user-session auth.
- *
- * The `subpath` is appended to the migrations namespace verbatim
- * (e.g. `"export-to-gcs"`, `"import-from-gcs"`, `\`jobs/${jobId}\``).
- */
-export function resolveRuntimeMigrationUrl(
-  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
-  subpath: string,
-): string {
-  if (isCloudHome(entry.cloud)) {
-    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/migrations/${subpath}`;
-  }
-  return `${entry.runtimeUrl}/v1/migrations/${subpath}`;
-}
-
 /**
  * Resolve the URL for a generic runtime endpoint under `/v1/<subpath>`,
  * taking the assistant's topology into account.

package/src/lib/teleport-backup.ts

@@ -1,17 +1,4 @@
-/**
- * Platform (cloud="cadet") half of the pre-teleport safety backup.
- *
- * A platform source is snapshotted through Django's user-facing backup
- * endpoint, which cuts a PVC VolumeSnapshot via vembda. The POST returns as
- * soon as the snapshot object exists; it becomes restorable asynchronously,
- * so {@link createPlatformBackup} polls the listing until the new snapshot
- * reports `ready_to_use` before returning. A snapshot that never becomes
- * ready within the timeout is a backup failure, not a success.
- *
- * Local and docker sources are backed up host-side by `backup-ops` instead,
- * so the restore point survives the source's retirement. Policy shared with
- * the web teleport lives in `@mycadet/local-mode/teleport-backup-policy`.
- */
+/** Cloud API safety backups use session auth and wait for a restorable root tar. */
 
 import {
   MANAGED_BACKUP_READY_POLL_INTERVAL_MS,
@@ -93,7 +80,7 @@ async function fetchPlatformBackups(
 }
 
 /**
- * `created_at` of every restorable PVC snapshot of a cloud assistant:
+ * `created_at` of every restorable root archive of a cloud assistant:
  * `GET /v1/assistants/<id>/backups/`.
  */
 export async function listPlatformBackups(
@@ -109,7 +96,7 @@ export interface CreatePlatformBackupOptions {
 }
 
 /**
- * Take a PVC snapshot of a cloud assistant and wait until it is
+ * Capture a root archive of a cloud assistant and wait until it is
  * restorable: `POST /v1/assistants/<id>/backups/`, then re-list until the
  * returned `snapshot_name` reports `ready_to_use`. Throws if the POST fails
  * or the snapshot is not ready within `timeoutMs`.

package/src/lib/tunnel.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { TUNNEL_PROVIDERS } from "@mycadet/service-contracts/ingress";
 import {
   clearRootProcess,
   loadAllAssistants,
@@ -24,26 +26,24 @@ import { waitForDaemonReady } from "./http-client.js";
 import {
   hasWebhookIntegrations,
   IngressConfigSchema,
-  isNgrokProcess,
   maybeStartNgrokTunnel,
   NGROK_TUNNEL_META,
-  runNgrokTunnel,
+  NGROK_PROVIDER,
   saveNgrokDomain,
 } from "./tunnels/ngrok.js";
-import { stopProcess } from "./process.js";
 import { shellArg } from "./shell-arg.js";
 import { notifyGatewayOfPublicUrl } from "./tunnels/gateway-notify.js";
 import {
   selectRestartTunnelRecord,
   type TunnelProviderName,
 } from "@mycadet/service-contracts/ingress";
-import { runCadetTunnel, CADET_TUNNEL_META } from "./tunnels/cadet.js";
+import { CADET_PROVIDER, CADET_TUNNEL_META } from "./tunnels/cadet.js";
 import {
-  runCloudflareTunnel,
+  CLOUDFLARE_PROVIDER,
   CLOUDFLARE_TUNNEL_META,
 } from "./tunnels/cloudflare.js";
 import {
-  runTailscaleTunnel,
+  TAILSCALE_PROVIDER,
   TAILSCALE_TUNNEL_META,
 } from "./tunnels/tailscale.js";
 
@@ -119,6 +119,25 @@ export interface ProviderTunnelResult {
   waitForExit: Promise<void>;
 }
 
+export interface ProviderStopOptions {
+  record: RootProcessRecord;
+  assistantId?: string;
+  workspaceDir?: string;
+}
+
+export interface TunnelProvider {
+  run(opts: ProviderTunnelOptions): Promise<ProviderTunnelResult>;
+  stop(opts: ProviderStopOptions): Promise<boolean>;
+}
+
+const providers: Record<TunnelProviderName, TunnelProvider> = {
+  ngrok: NGROK_PROVIDER,
+  cloudflare: CLOUDFLARE_PROVIDER,
+  tailscale: TAILSCALE_PROVIDER,
+  cadet: CADET_PROVIDER,
+};
+const providerNameSchema = z.enum(TUNNEL_PROVIDERS);
+
 /**
  * Run a tunnel provider by name — the dispatch `cadet tunnel` uses, so the
  * command layer never names a provider implementation directly. Notifies the
@@ -140,29 +159,7 @@ function runProvider(
   provider: TunnelProviderName,
   opts: ProviderTunnelOptions,
 ): Promise<ProviderTunnelResult> {
-  const base = {
-    port: opts.port,
-    assistantId: opts.assistantId,
-    workspaceDir: opts.workspaceDir,
-  };
-  if (provider === "ngrok") {
-    return runNgrokTunnel({
-      ...base,
-      ...(opts.domain ? { domain: opts.domain } : {}),
-    });
-  }
-  if (provider === "cadet") {
-    return runCadetTunnel(opts);
-  }
-  if (provider === "cloudflare") {
-    return runCloudflareTunnel(base);
-  }
-  return runTailscaleTunnel({
-    ...base,
-    ...(opts.preserveIngressUrl
-      ? { preserveIngressUrl: opts.preserveIngressUrl }
-      : {}),
-  });
+  return providers[provider].run(opts);
 }
 
 /** Drop the saved reserved-domain record (providers that keep one). */
@@ -176,13 +173,31 @@ export function clearReservedDomain(): void {
  * signaling — a stale entry after PID reuse must not kill an unrelated
  * process.
  */
-export async function stopTunnelProcess(): Promise<void> {
+export async function stopTunnelProcess(
+  assistantId?: string,
+  workspaceDir?: string,
+): Promise<boolean> {
   const recorded: RootProcessRecord | undefined = readRootProcesses().tunnel;
-  if (!recorded) return;
-  if (isNgrokProcess(recorded.pid)) {
-    await stopProcess(recorded.pid, "tunnel");
+  if (!recorded) return false;
+  if (
+    assistantId &&
+    recorded.assistantId &&
+    recorded.assistantId !== assistantId
+  ) {
+    throw new Error(
+      `The recorded tunnel belongs to '${recorded.assistantId}', not '${assistantId}'.`,
+    );
   }
-  clearRootProcess("tunnel");
+  const provider = providerNameSchema.parse(
+    recorded.provider ?? DEFAULT_TUNNEL_PROVIDER,
+  );
+  const stopped = await providers[provider].stop({
+    record: recorded,
+    assistantId,
+    workspaceDir,
+  });
+  clearRootProcess("tunnel", recorded.pid);
+  return stopped;
 }
 
 /**
@@ -197,6 +212,43 @@ export function adoptedTunnelStopNotice(pid: number | undefined): string {
   );
 }
 
+/**
+ * Pull the single most meaningful failure line out of a tunnel log so the
+ * `cadet tunnel` wrapper can name why the child died instead of only pointing
+ * at the log file. Priority: nginx emerg/bind failures, ngrok error codes,
+ * auth/usage failures, then any generic error/fatal/failed line — the LAST
+ * match wins (the freshest), capped to keep the console line readable. Falls
+ * back to the last non-empty log line, or null for an empty log.
+ */
+export function summarizeStartupFailure(logText: string): string | null {
+  const lines = logText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) {
+    return null;
+  }
+  const patterns: RegExp[] = [
+    /\[emerg\]/,
+    /bind\(\).*failed/i,
+    /address already in use/i,
+    /ERR_NGROK_\d+/,
+    /authtoken|authentication failed|usage limit|unauthorized/i,
+    /\berror\b|\bfatal\b|\bfailed\b/i,
+  ];
+  const cap = (line: string): string =>
+    line.length > 200 ? `${line.slice(0, 200)}…` : line;
+  for (const pattern of patterns) {
+    const matches = lines.filter((line) => pattern.test(line));
+    const last = matches.at(-1);
+    if (last !== undefined) {
+      return cap(last);
+    }
+  }
+  const lastLine = lines.at(-1);
+  return lastLine === undefined ? null : cap(lastLine);
+}
+
 export {
   ADOPTED_TUNNEL_RE,
   hasWebhookIntegrationsConfigured,
@@ -335,6 +387,7 @@ export async function restoreTunnelEdge(
   console.log(
     `   Tunnel edge ${edge.started ? "started" : "already running"} on 127.0.0.1:${edge.port} (${formatEdgeMode(
       edge.includesWebApp,
+      edge.shellMode,
     )}).`,
   );
   return edge.port;

package/src/lib/tunnels/cadet.ts

@@ -1,5 +1,9 @@
 import { STALE_CLI_UPDATE_HINT } from "../stale-cli-hint.js";
-import type { ProviderMeta, ProviderTunnelOptions } from "../tunnel.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelOptions,
+} from "../tunnel.js";
 
 /**
  * The managed `cadet` tunnel. It is listed in the shared registry so the
@@ -27,3 +31,10 @@ export async function runCadetTunnel(
 ): Promise<never> {
   throw cadetTunnelComingSoonError("cadet");
 }
+
+export const CADET_PROVIDER: TunnelProvider = {
+  run: runCadetTunnel,
+  async stop() {
+    throw cadetTunnelComingSoonError("cadet");
+  },
+};

package/src/lib/tunnels/cloudflare.ts

@@ -1,4 +1,11 @@
-import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { clearRootProcess, stampRootProcess } from "../assistant-config.js";
+import { readProcessCommandLine } from "../process.js";
+import { stopOwnedTunnelAgent } from "./process-lifecycle.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelResult,
+} from "../tunnel.js";
 
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
@@ -106,6 +113,7 @@ export function waitForCloudflareTunnelUrl(
     });
 
     child.on("exit", (code) => {
+      if (child.pid) clearRootProcess("tunnel", child.pid);
       if (resolved) return;
       clearTimeout(timer);
       reject(
@@ -177,6 +185,7 @@ export async function runCloudflareTunnel(
 
   const cleanup = (): void => {
     if (!child.killed) child.kill("SIGTERM");
+    if (child.pid) clearRootProcess("tunnel", child.pid);
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
       clearIngressUrl(workspaceDir, opts.assistantId);
@@ -198,6 +207,7 @@ export async function runCloudflareTunnel(
   });
 
   child.on("exit", (code) => {
+    if (child.pid) clearRootProcess("tunnel", child.pid);
     // Always clear the saved ingress URL when the tunnel process ends so
     // webhook integrations don't keep hitting a dead endpoint.
     if (publicUrl !== undefined) {
@@ -233,6 +243,13 @@ export async function runCloudflareTunnel(
   console.log("");
 
   saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "cloudflare");
+  if (child.pid)
+    stampRootProcess("tunnel", {
+      pid: child.pid,
+      provider: "cloudflare",
+      assistantId: opts.assistantId,
+      startedAt: new Date().toISOString(),
+    });
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
@@ -251,3 +268,21 @@ export const CLOUDFLARE_TUNNEL_META: ProviderMeta = {
   notes: ["No Cloudflare account required for quick tunnels."],
   supportsReservedDomain: false,
 };
+
+export const CLOUDFLARE_PROVIDER: TunnelProvider = {
+  run: runCloudflareTunnel,
+  stop: (opts) =>
+    stopOwnedTunnelAgent(
+      opts,
+      (pid) => {
+        try {
+          return /(?:^|[\\/\s])cloudflared(?:\.exe)?(?:\s|$)/i.test(
+            readProcessCommandLine(pid),
+          );
+        } catch {
+          return false;
+        }
+      },
+      "cloudflared",
+    ),
+};

package/src/lib/tunnels/ngrok.ts

@@ -25,7 +25,12 @@ import { getCurrentEnvironment } from "../environments/resolve.js";
 import { loopbackSafeFetch } from "../loopback-fetch.js";
 import { readProcessCommandLine } from "../process.js";
 import { z } from "zod";
-import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { stopOwnedTunnelAgent } from "./process-lifecycle.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelResult,
+} from "../tunnel.js";
 import { notifyGatewayOfPublicUrl } from "./gateway-notify.js";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
@@ -631,8 +636,12 @@ export async function runNgrokTunnel(
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
-      "Tunnel is already running. Press Ctrl+C to detach (tunnel stays active).",
+      `An ngrok agent from an earlier run is still up serving 127.0.0.1:${port} (${existingUrl}) — this run adopts it instead of starting a new agent.`,
     );
+    console.log(
+      "Adopted agents do not appear in `cadet ps` because this run does not own the process.",
+    );
+    console.log("Press Ctrl+C to detach (tunnel stays active).");
 
     // Block until SIGINT/SIGTERM
     const waitForExit = new Promise<void>((resolve) => {
@@ -783,3 +792,8 @@ export async function runNgrokTunnel(
   // Unreachable: the loop only exits via return, process.exit, or a throw.
   throw new Error("ngrok tunnel did not start.");
 }
+
+export const NGROK_PROVIDER: TunnelProvider = {
+  run: runNgrokTunnel,
+  stop: (opts) => stopOwnedTunnelAgent(opts, isNgrokProcess, "ngrok"),
+};

package/src/lib/tunnels/process-lifecycle.ts

@@ -0,0 +1,26 @@
+import { clearIngressUrl } from "../ingress-config.js";
+import { stopProcess } from "../process.js";
+import type { ProviderStopOptions } from "../tunnel.js";
+
+/** Stop only an identified provider process and retain state on termination failure. */
+export async function stopOwnedTunnelAgent(
+  opts: ProviderStopOptions,
+  matches: (pid: number) => boolean,
+  label: string,
+): Promise<boolean> {
+  let stopped = false;
+  if (matches(opts.record.pid)) {
+    stopped = await stopProcess(opts.record.pid, "tunnel");
+    if (!stopped && matches(opts.record.pid)) {
+      throw new Error(
+        `Could not stop ${label} process ${opts.record.pid}; saved tunnel state was retained.`,
+      );
+    }
+  }
+  if (opts.workspaceDir)
+    clearIngressUrl(
+      opts.workspaceDir,
+      opts.assistantId ?? opts.record.assistantId,
+    );
+  return stopped;
+}

package/src/lib/tunnels/tailscale.ts

@@ -1,4 +1,16 @@
-import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { z } from "zod";
+import {
+  clearRootProcess,
+  readRootProcesses,
+  stampRootProcess,
+} from "../assistant-config.js";
+import { readProcessCommandLine, stopProcess } from "../process.js";
+import type {
+  TunnelProvider,
+  ProviderStopOptions,
+  ProviderMeta,
+  ProviderTunnelResult,
+} from "../tunnel.js";
 
 import { spawnSync } from "node:child_process";
 import { win32 } from "node:path";
@@ -7,6 +19,7 @@ import { GATEWAY_PORT } from "../constants.js";
 import { ensureBinaryInstalled } from "../ensure-binary.js";
 import {
   clearIngressUrl,
+  loadRawConfig,
   getDefaultWorkspaceDir,
   readLockfileIngressUrl,
   saveIngressUrl,
@@ -418,6 +431,16 @@ export async function runTailscaleTunnel(
   );
   console.log("or stop it later with: tailscale serve --https=443 off");
 
+  const previous = opts.preserveIngressUrl
+    ? readRootProcesses().tunnel
+    : undefined;
+  stampRootProcess("tunnel", {
+    ...(previous?.provider !== "tailscale" ? { previous } : {}),
+    pid: process.pid,
+    provider: "tailscale",
+    assistantId: opts.assistantId,
+    startedAt: new Date().toISOString(),
+  });
   const teardown = (): void => {
     console.log(
       `\nStopping tailscale serve and clearing the ${publishedLabel}...`,
@@ -441,6 +464,7 @@ export async function runTailscaleTunnel(
       );
     }
     if (shouldClearIngressUrl(result)) {
+      clearRootProcess("tunnel", process.pid);
       retractServeUrl(opts, workspaceDir, previousLockfileIngressUrl);
     } else {
       console.error(
@@ -475,3 +499,57 @@ export const TAILSCALE_TUNNEL_META: ProviderMeta = {
   ],
   supportsReservedDomain: false,
 };
+
+const stoppedTailscaleStateSchema = z.object({
+  ingress: z
+    .object({
+      publicBaseUrl: z.string().optional(),
+      pairingTunnel: z.object({ provider: z.string() }).optional(),
+    })
+    .optional(),
+});
+
+export async function stopTailscaleTunnel(
+  opts: ProviderStopOptions,
+  deps: TailscaleDeps = {
+    findBinary: async () => probeTailscaleBinary(),
+    run: realRun,
+  },
+): Promise<boolean> {
+  const binary = await deps.findBinary();
+  if (!binary) throw new Error(getTailscaleInstallMessage());
+  const result = stopTailscaleServe(binary, deps);
+  if (result.status !== 0)
+    throw new Error(`Could not stop tailscale serve: ${joinOutput(result)}`);
+  // The serve belongs to tailscaled; only the Cadet supervisor may be signaled.
+  let supervisor = false;
+  try {
+    const command = readProcessCommandLine(opts.record.pid);
+    supervisor =
+      /cadet/i.test(command) && /(?:^|\s)tunnel(?:\s|$)/.test(command);
+  } catch {
+    /* The supervisor may already have exited. */
+  }
+  if (supervisor && opts.record.pid !== process.pid)
+    await stopProcess(opts.record.pid, "tunnel supervisor");
+  if (opts.workspaceDir) {
+    const state = stoppedTailscaleStateSchema.parse(
+      loadRawConfig(opts.workspaceDir),
+    ).ingress;
+    const assistantId = opts.assistantId ?? opts.record.assistantId;
+    retractServeUrl(
+      {
+        assistantId,
+        preserveIngressUrl: state?.pairingTunnel?.provider === "tailscale",
+      },
+      opts.workspaceDir,
+      state?.publicBaseUrl ?? null,
+    );
+  }
+  return true;
+}
+
+export const TAILSCALE_PROVIDER: TunnelProvider = {
+  run: runTailscaleTunnel,
+  stop: stopTailscaleTunnel,
+};