@mycadet/cli 0.12.7 → 0.12.8

package/src/lib/{ngrok.ts → tunnels/ngrok.ts}

@@ -1,18 +1,31 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
-import { GATEWAY_PORT } from "./constants.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import { GATEWAY_PORT } from "../constants.js";
+import { clearRootProcess, stampRootProcess } from "../assistant-config.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
-  loadNgrokDomain,
   loadRawConfig,
   saveIngressUrl,
-  saveNgrokDomain,
-} from "./ingress-config.js";
-import { loopbackSafeFetch } from "./loopback-fetch.js";
+} from "../ingress-config.js";
+import { getConfigDir } from "../environments/paths.js";
+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 { notifyGatewayOfPublicUrl } from "./gateway-notify.js";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
@@ -42,6 +55,14 @@ export const IngressConfigSchema = z.object({
   publicBaseUrl: z.string().optional(),
 });
 
+/** Per-provider copy `cadet tunnel`'s help renders for ngrok. */
+export const NGROK_TUNNEL_META: ProviderMeta = {
+  reach: "Public tunnel that webhook integrations can reach",
+  install: "install: brew install ngrok/ngrok/ngrok",
+  domainExample: "my-assistant.ngrok.app",
+  supportsReservedDomain: true,
+};
+
 /**
  * Check whether ngrok is installed and accessible on the PATH.
  * Returns the version string if installed, null otherwise.
@@ -118,9 +139,106 @@ function staleAgentDiagnostic(tunnels: NgrokTunnel[], port: number): string {
 
 /** Recovery copy for a saved domain whose reservation may have lapsed. */
 function savedDomainRecoveryHint(domain: string): string {
-  return `The saved ngrok domain '${domain}' (ingress.ngrok.domain in the workspace config) may no longer be reserved. Run \`cadet tunnel --provider ngrok --clear-domain\` to drop it and tunnel without one.`;
+  return `The saved ngrok domain '${domain}' (${ngrokConfigPath()}) may no longer be reserved. Run \`cadet tunnel --provider ngrok --clear-domain\` to drop it and tunnel without one.`;
+}
+
+const NGROK_TUNNEL_NAME = "cadet";
+
+const NgrokTunnelDefSchema = z.looseObject({
+  proto: z.string().optional(),
+  addr: z.string().optional(),
+  domain: z.string().optional(),
+});
+
+const NgrokConfigFileSchema = z.looseObject({
+  version: z.string().optional(),
+  tunnels: z.record(z.string(), NgrokTunnelDefSchema).optional(),
+});
+
+type NgrokConfigFile = z.infer<typeof NgrokConfigFileSchema>;
+type NgrokTunnelDef = z.infer<typeof NgrokTunnelDefSchema>;
+
+/**
+ * The ngrok-format config file this CLI owns in the XDG config dir, layered
+ * over the user's root ngrok config at spawn time (`--config` files merge in
+ * order, later wins; the user's authtoken keeps living in their root config).
+ * It is also the source of truth for the reserved domain at this layer — the
+ * workspace config no longer records one.
+ */
+export function ngrokConfigPath(): string {
+  return join(getConfigDir(getCurrentEnvironment()), "tunnels", "ngrok.yaml");
+}
+
+function readNgrokConfigFile(): NgrokConfigFile {
+  const path = ngrokConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = NgrokConfigFileSchema.safeParse(
+      parseYaml(readFileSync(path, "utf-8")),
+    );
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeNgrokConfigFile(config: NgrokConfigFile): void {
+  const path = ngrokConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, stringifyYaml(config));
 }
 
+/**
+ * Persist a reserved ngrok domain in the XDG ngrok config; null clears it.
+ *
+ * The reserved domain is an ngrok reservation concept (cloudflare quick
+ * tunnels and tailscale serve have no equivalent), which is why this lives in
+ * the ngrok provider module rather than the shared ingress-config helpers.
+ */
+export function saveNgrokDomain(domain: string | null): void {
+  const config = readNgrokConfigFile();
+  const cadet: NgrokTunnelDef = {
+    ...config.tunnels?.[NGROK_TUNNEL_NAME],
+    proto: "http",
+  };
+  if (domain) {
+    cadet.domain = domain;
+  } else {
+    delete cadet.domain;
+  }
+  const tunnels: Record<string, NgrokTunnelDef> = { ...config.tunnels };
+  tunnels[NGROK_TUNNEL_NAME] = cadet;
+  const next: NgrokConfigFile = { ...config, version: config.version ?? "2" };
+  next.tunnels = tunnels;
+  writeNgrokConfigFile(next);
+}
+
+/** Read the reserved ngrok domain from the XDG ngrok config, if saved. */
+export function loadNgrokDomain(): string | null {
+  const domain = readNgrokConfigFile().tunnels?.[NGROK_TUNNEL_NAME]?.domain;
+  return domain?.trim() ? domain : null;
+}
+
+/**
+ * Check whether a PID belongs to an ngrok process via its command line, so a
+ * recorded pid is verified before it is signaled (PID reuse guard).
+ */
+export function isNgrokProcess(pid: number): boolean {
+  try {
+    return /ngrok/i.test(readProcessCommandLine(pid));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Matches the adoption line the tunnel workflows print when they find an
+ * already-running tunnel, so the detached-tunnel supervisor can detect
+ * adoption without this module's implementation details leaking into the
+ * command layer.
+ */
+export const ADOPTED_TUNNEL_RE = /Found existing ngrok tunnel: (\S+)/;
+
 /** Whether a tunnel public URL's host equals the given reserved domain. */
 function urlMatchesDomain(publicUrl: string, domain: string): boolean {
   try {
@@ -133,15 +251,42 @@ function urlMatchesDomain(publicUrl: string, domain: string): boolean {
 }
 
 /**
- * Start an ngrok process tunneling HTTP traffic to the given local port.
+ * Write the cadet-owned XDG ngrok config for this run: the tunnel definition
+ * `ngrok start` reads, carrying the loopback target and — when reserved — the
+ * bound domain. The file is layered over the user's root ngrok config at
+ * spawn, so their authtoken and settings keep applying untouched.
+ */
+function writeNgrokConfig(targetPort: number, domain?: string): void {
+  const config = readNgrokConfigFile();
+  const cadet: NgrokTunnelDef = {
+    ...config.tunnels?.[NGROK_TUNNEL_NAME],
+    proto: "http",
+    // Explicit over a bare port, which ngrok expands to `localhost`, whose
+    // ::1 answer resolves first on macOS and races the edge's IPv4 bind.
+    addr: `127.0.0.1:${targetPort}`,
+  };
+  if (domain) {
+    cadet.domain = domain;
+  }
+  const tunnels: Record<string, NgrokTunnelDef> = { ...config.tunnels };
+  tunnels[NGROK_TUNNEL_NAME] = cadet;
+  const next: NgrokConfigFile = { ...config, version: config.version ?? "2" };
+  next.tunnels = tunnels;
+  writeNgrokConfigFile(next);
+}
+
+/**
+ * Start an ngrok process tunneling HTTP traffic to the given local port, via
+ * the cadet-owned XDG config (`ngrok start cadet`) so the agent never collides
+ * with the host machine's root ngrok config.
  *
  * When `logFilePath` is provided, stdout/stderr are redirected to that file
  * instead of being piped. This avoids keeping pipe handles open in the
  * parent process — which would either prevent the CLI from exiting (if
  * handles are left open) or send SIGPIPE to ngrok (if destroyed).
  *
- * When `domain` is set, the tunnel binds that reserved ngrok domain via
- * `--domain=<domain>`.
+ * When `domain` is set, the spawned tunnel binds that reserved ngrok domain,
+ * recorded in the XDG config alongside the loopback target.
  *
  * Returns the spawned child process.
  */
@@ -159,12 +304,13 @@ export function startNgrokProcess(
     stdio = ["ignore", fd, fd];
   }
 
-  // Explicit over a bare port, which ngrok expands to `localhost`, whose ::1
-  // answer resolves first on macOS and races the edge's IPv4 bind.
-  const args = ["http", `127.0.0.1:${targetPort}`, "--log=stdout"];
-  if (domain) {
-    args.push(`--domain=${domain}`);
-  }
+  writeNgrokConfig(targetPort, domain);
+  const args = [
+    "start",
+    NGROK_TUNNEL_NAME,
+    `--config=${ngrokConfigPath()}`,
+    "--log=stdout",
+  ];
 
   const child = spawn("ngrok", args, {
     detached: true,
@@ -225,10 +371,7 @@ export function hasWebhookIntegrations(
   const telegram = TelegramIntegrationSchema.safeParse(config.telegram);
   if (telegram.success && telegram.data.botUsername) return true;
   const twilio = TwilioIntegrationSchema.safeParse(config.twilio);
-  if (
-    twilio.success &&
-    (twilio.data.accountSid || twilio.data.phoneNumber)
-  ) {
+  if (twilio.success && (twilio.data.accountSid || twilio.data.phoneNumber)) {
     return true;
   }
   return false;
@@ -282,7 +425,7 @@ export async function maybeStartNgrokTunnel(
   workspaceDir: string,
   assistantId?: string,
 ): Promise<ChildProcess | null> {
-  // Managed/containerized deployments route webhooks through the platform's
+  // Managed/containerized deployments route webhooks through the cloud's
   // callback proxy. ngrok is not needed and would not be reachable from the
   // platform anyway — skip it entirely.
   const isContainerized =
@@ -295,7 +438,7 @@ export async function maybeStartNgrokTunnel(
   const version = getNgrokVersion();
   if (!version) return null;
 
-  const savedDomain = loadNgrokDomain(workspaceDir) ?? undefined;
+  const savedDomain = loadNgrokDomain() ?? undefined;
 
   // Reuse an existing tunnel if one is already running
   const runningTunnels = (await queryNgrokTunnels()) ?? [];
@@ -312,6 +455,10 @@ export async function maybeStartNgrokTunnel(
     }
     console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl, assistantId, "ngrok");
+    await notifyGatewayOfPublicUrl(existingUrl, assistantId);
+    // The adopted tunnel belongs to some other agent we do not own a pid for,
+    // so any recorded tunnel process entry would be stale from here on.
+    clearRootProcess("tunnel");
     return null;
   }
   if (runningTunnels.length > 0) {
@@ -339,6 +486,15 @@ export async function maybeStartNgrokTunnel(
   try {
     const publicUrl = await waitForNgrokUrl(targetPort, savedDomain);
     saveIngressUrl(workspaceDir, publicUrl, assistantId, "ngrok");
+    await notifyGatewayOfPublicUrl(publicUrl, assistantId);
+    if (ngrokProcess.pid) {
+      stampRootProcess("tunnel", {
+        pid: ngrokProcess.pid,
+        provider: "ngrok",
+        startedAt: new Date().toISOString(),
+        assistantId,
+      });
+    }
     console.log(`   Tunnel established: ${publicUrl}`);
 
     return ngrokProcess;
@@ -350,6 +506,7 @@ export async function maybeStartNgrokTunnel(
       console.warn(`   ⚠ ${savedDomainRecoveryHint(savedDomain)}`);
     }
     if (!ngrokProcess.killed) ngrokProcess.kill("SIGTERM");
+    clearRootProcess("tunnel");
     return null;
   }
 }
@@ -370,11 +527,13 @@ export interface RunNgrokTunnelOptions {
 
 /**
  * Run the ngrok tunnel workflow: check installation, find or start a tunnel,
- * save the public URL to config, and block until exit or signal.
+ * and save the public URL to config. Hands the URL back so the tunnel level
+ * can notify the gateway of it; `waitForExit` settles when the run ends
+ * (process exit, signal, or detach).
  */
 export async function runNgrokTunnel(
   opts: RunNgrokTunnelOptions = {},
-): Promise<void> {
+): Promise<ProviderTunnelResult> {
   const version = getNgrokVersion();
   if (!version) {
     console.error("Error: ngrok is not installed.");
@@ -397,7 +556,7 @@ export async function runNgrokTunnel(
 
   // The saved domain is standing intent: a run without --domain reuses it,
   // and only an explicit --domain rewrites it.
-  const domain = opts.domain ?? loadNgrokDomain(workspaceDir) ?? undefined;
+  const domain = opts.domain ?? loadNgrokDomain() ?? undefined;
   if (domain && !opts.domain) {
     console.log(`Using saved ngrok domain: ${domain}`);
   }
@@ -426,8 +585,10 @@ export async function runNgrokTunnel(
     }
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl, opts.assistantId, "ngrok");
+    // Not our child process: a recorded entry would be stale or foreign.
+    clearRootProcess("tunnel");
     if (opts.domain) {
-      saveNgrokDomain(workspaceDir, opts.domain);
+      saveNgrokDomain(opts.domain);
     }
     console.log("Ingress URL saved to config.");
     console.log("");
@@ -436,11 +597,11 @@ export async function runNgrokTunnel(
     );
 
     // Block until SIGINT/SIGTERM
-    await new Promise<void>((resolve) => {
+    const waitForExit = new Promise<void>((resolve) => {
       process.on("SIGINT", () => resolve());
       process.on("SIGTERM", () => resolve());
     });
-    return;
+    return { publicUrl: existingUrl, waitForExit };
   }
 
   console.log(`Starting ngrok tunnel to localhost:${port}...`);
@@ -453,6 +614,7 @@ export async function runNgrokTunnel(
     if (!ngrokProcess.killed) {
       ngrokProcess.kill("SIGTERM");
     }
+    clearRootProcess("tunnel");
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
       clearIngressUrl(workspaceDir, opts.assistantId);
@@ -510,15 +672,24 @@ export async function runNgrokTunnel(
   // The domain is standing intent, not tunnel state: cleanup clears the
   // ingress URL but leaves the domain saved for wake/daemon restores.
   saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "ngrok");
+  if (ngrokProcess.pid) {
+    stampRootProcess("tunnel", {
+      pid: ngrokProcess.pid,
+      provider: "ngrok",
+      startedAt: new Date().toISOString(),
+      assistantId: opts.assistantId,
+    });
+  }
   if (opts.domain) {
-    saveNgrokDomain(workspaceDir, opts.domain);
+    saveNgrokDomain(opts.domain);
   }
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
 
   // Keep running until the ngrok process exits or we receive a signal
-  await new Promise<void>((resolve) => {
+  const waitForExit = new Promise<void>((resolve) => {
     ngrokProcess.on("exit", () => resolve());
   });
+  return { publicUrl, waitForExit };
 }

package/src/lib/{tailscale-tunnel.ts → tunnels/tailscale.ts}

@@ -1,7 +1,9 @@
+import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+
 import { spawnSync } from "node:child_process";
 import { win32 } from "node:path";
 
-import { GATEWAY_PORT } from "./constants.js";
+import { GATEWAY_PORT } from "../constants.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
@@ -9,7 +11,7 @@ import {
   saveIngressUrl,
   savePairingTunnel,
   stampLockfileIngressUrl,
-} from "./ingress-config.js";
+} from "../ingress-config.js";
 
 // ── Tailscale CLI discovery + invocation ────────────────────────────────────
 
@@ -351,7 +353,7 @@ export function stopTailscaleServe(
  */
 export async function runTailscaleTunnel(
   opts: RunTailscaleTunnelOptions = {},
-): Promise<void> {
+): Promise<ProviderTunnelResult> {
   const deps = realTailscaleDeps();
   // What this run publishes, and therefore what Ctrl+C takes back.
   const publishedLabel = opts.preserveIngressUrl
@@ -375,7 +377,7 @@ export async function runTailscaleTunnel(
     "This URL is reachable only from devices signed in to your tailnet.",
   );
   console.log(
-    "For public webhook ingress, use --provider ngrok or --provider cloudflare.",
+    "For public webhook ingress, run `cadet tunnel --help` to see the public providers.",
   );
   console.log("");
   console.log(
@@ -429,5 +431,17 @@ export async function runTailscaleTunnel(
   // Hold the process open until a signal fires. The serve itself lives in
   // tailscaled, so there is no child process to await — the registered signal
   // listeners keep the event loop alive.
-  await new Promise<void>(() => {});
+  const waitForExit = new Promise<void>(() => {});
+  return { publicUrl, waitForExit };
 }
+
+/** Per-provider copy `cadet tunnel`'s help renders for tailscale. */
+export const TAILSCALE_TUNNEL_META: ProviderMeta = {
+  reach: "Tailnet-only tunnel, reachable from your own devices",
+  install: "install: https://tailscale.com/download, then run `tailscale up`",
+  notes: [
+    "When webhook integrations are configured it records its URL for device",
+    "pairing only, leaving the saved webhook callback base as it is.",
+  ],
+  supportsReservedDomain: false,
+};

package/src/lib/upgrade-lifecycle.ts

@@ -24,7 +24,7 @@ import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loadGuardianToken } from "./guardian-token.js";
 import { classifyReadyzResponse } from "./http-client.js";
-import { fetchReleases, resolveImageRefs } from "./platform-releases.js";
+import { fetchReleases, resolveImageRefs } from "./cloud-releases.js";
 import { z } from "zod";
 
 const GatewayHealthSchema = z.object({
@@ -332,7 +332,7 @@ export async function fetchAssistantIngressUrl(
         publicBaseUrl?: string;
         managedCallbacks?: boolean;
       };
-      // Ignore managed-callback URLs — those belong to the platform, not the
+      // Ignore managed-callback URLs — those belong to the cloud, not the
       // self-hosted assistant's own ingress.
       if (body.managedCallbacks) return undefined;
       return body.publicBaseUrl || undefined;
@@ -348,7 +348,7 @@ export async function fetchAssistantIngressUrl(
  *
  * Checks (in order):
  *  1. `entry.previousVersion` (saved by the upgrade flow from health).
- *  2. The releases list from the platform API — finds the version
+ *  2. The releases list from the cloud API — finds the version
  *     immediately before `currentVersion`.
  *
  * Returns `undefined` when neither source yields a result.
@@ -869,8 +869,6 @@ export async function performDockerRollback(
     );
 
     // Capture new digests from the rolled-back containers
-    const newDigests = await captureImageRefs(res);
-
     // Swap current/previous state to enable "rollback the rollback"
     const updatedEntry: AssistantEntry = {
       ...entry,
@@ -878,10 +876,6 @@ export async function performDockerRollback(
         assistantImage: targetImageTags.assistant,
         gatewayImage: targetImageTags.gateway,
         cesImage: targetImageTags["credential-executor"],
-        assistantDigest: newDigests?.assistant,
-        gatewayDigest: newDigests?.gateway,
-        cesDigest: newDigests?.["credential-executor"],
-        networkName: res.network,
         assistantPort,
       },
       previousContainerInfo: entry.containerInfo,
@@ -1030,7 +1024,6 @@ export async function performDockerRollback(
           }
 
           // Restore lockfile state
-          const revertDigests = await captureImageRefs(res);
           const revertedEntry: AssistantEntry = {
             ...entry,
             containerInfo: {
@@ -1042,13 +1035,6 @@ export async function performDockerRollback(
               cesImage:
                 entry.containerInfo?.cesImage ??
                 currentImageRefs["credential-executor"],
-              assistantDigest:
-                revertDigests?.assistant ?? currentImageRefs.assistant,
-              gatewayDigest: revertDigests?.gateway ?? currentImageRefs.gateway,
-              cesDigest:
-                revertDigests?.["credential-executor"] ??
-                currentImageRefs["credential-executor"],
-              networkName: res.network,
               assistantPort,
             },
             previousContainerInfo: undefined,

package/src/lib/upgrade-preflight.ts

@@ -1,4 +1,4 @@
-import type { ReleaseListItem } from "./platform-releases.js";
+import type { ReleaseListItem } from "./cloud-releases.js";
 import { compareVersions, versionsEqual } from "./version-compat.js";
 
 export interface UpgradeTargetResolution {
@@ -88,7 +88,7 @@ export interface UpgradePollState {
 }
 
 /**
- * Completion predicate for the platform upgrade poll loop. Pure.
+ * Completion predicate for the cloud upgrade poll loop. Pure.
  *
  * The primary signal is the DB-backed `current_release_version` (works while
  * the service group restarts or the assistant sleeps); the upgrade-status

package/src/lib/workos-pkce.ts

@@ -103,9 +103,9 @@ export function selectWorkosClientId(
 }
 
 export async function fetchWorkosClientId(
-  platformUrl: string,
+  cloudUrl: string,
 ): Promise<string> {
-  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/config`;
+  const url = `${new URL(cloudUrl).origin}/_allauth/app/v1/config`;
   const response = await loopbackSafeFetch(url);
   if (!response.ok) {
     throw new Error(`Failed to fetch auth config (${response.status})`);
@@ -157,13 +157,13 @@ export async function exchangeCodeWithWorkos(options: {
   return parsed.data.access_token;
 }
 
-/** Exchange the WorkOS access token for a platform session token. */
+/** Exchange the WorkOS access token for a cloud session token. */
 export async function exchangeAccessTokenForSession(
-  platformUrl: string,
+  cloudUrl: string,
   clientId: string,
   accessToken: string,
 ): Promise<string> {
-  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/auth/provider/token`;
+  const url = `${new URL(cloudUrl).origin}/_allauth/app/v1/auth/provider/token`;
   const response = await loopbackSafeFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },

package/node_modules/@mycadet/assistant-api/events/platform-disconnected.ts

@@ -1,21 +0,0 @@
-/**
- * `platform_disconnected` SSE event.
- *
- * Emitted by the platform-disconnect route after stored platform
- * credentials are deleted, notifying connected clients that the platform
- * connection is gone.
- *
- * Canonical wire-contract source. Daemon code imports the type
- * directly from this file; external consumers import via
- * `@mycadet/assistant-api`.
- */
-
-import { z } from "zod";
-
-export const PlatformDisconnectedEventSchema = z.object({
-  type: z.literal("platform_disconnected"),
-});
-
-export type PlatformDisconnectedEvent = z.infer<
-  typeof PlatformDisconnectedEventSchema
->;