@moondeck/station 0.0.0-stage → 1.0.0

package/src/load-env.ts

@@ -0,0 +1,97 @@
+/**
+ * Side-effect module: load `.env.local` then `.env` before host-agent modules
+ * read environment variables.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { config as dotenvConfig } from "dotenv";
+
+import { STATION } from "./station-identity";
+
+const proc = process as unknown as {
+  loadEnvFile?: (path: string) => void;
+};
+
+// Real path, not the import path: pnpm workspace links reach this file via
+// symlinks — a repo checkout must resolve to the checkout, and an installed
+// tarball to its true node_modules location.
+const here = (() => {
+  const raw = dirname(fileURLToPath(import.meta.url)); // <pkg>/src
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+})();
+
+// An INSTALLED copy always lives under a node_modules directory. Without
+// this guard, a tarball installed beneath some user's pnpm workspace that
+// happens to contain a sibling host-agent/ dir was mistaken for this source
+// checkout — suppressing telemetry AND selecting the wrong UAI_HOME
+// (review finding). Packaged desktop resources contain no node_modules
+// segment and no workspace above them; the repo checkout contains neither
+// problem.
+const installedCopy = here.split(sep).includes("node_modules");
+
+// Resolve the same UAI_HOME as lib/env.ts, but independently: this module runs
+// FIRST (before lib/env is imported) so it can't depend on it. .env.local is
+// what *sets* UAI_DATA_DIR, so we can't key off that here — only an explicit
+// UAI_HOME env, then repo detection, then ~/.uai (installed via npm).
+function findUp(start: string, pred: (dir: string) => boolean): string | null {
+  let dir = start;
+  for (;;) {
+    if (pred(dir)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const repoRoot = installedCopy
+  ? null
+  : findUp(
+      here,
+      (d) =>
+        existsSync(resolve(d, "pnpm-workspace.yaml")) &&
+        existsSync(resolve(d, "host-agent")),
+    );
+
+const uaiHome = process.env.UAI_HOME
+  ? resolve(process.env.UAI_HOME.replace(/^~(?=\/|$)/, homedir()))
+  : (repoRoot ?? resolve(homedir(), STATION.homeDirName));
+
+// ADR-071: expose the repo-checkout detection computed above to the
+// telemetry gate (lib/obs resolveHostDsn). `pnpm host-agent` from a fresh
+// checkout (and the deleted desktop host app's dev launch) set neither NODE_ENV
+// nor UAI_AGENT_FROM_REPO — this marker is the signal tied to the REAL
+// launch path, so dev runs never default-activate crash reporting. Packaged
+// installs (npm tarball, desktop resources) have no workspace file above
+// them and stay unmarked.
+if (repoRoot && !process.env.UAI_LAUNCHED_FROM_REPO) {
+  process.env.UAI_LAUNCHED_FROM_REPO = "1";
+}
+
+for (const file of [".env.local", ".env"]) {
+  const path = join(uaiHome, file);
+  if (!existsSync(path)) continue;
+  try {
+    if (proc.loadEnvFile) {
+      proc.loadEnvFile(path);
+    } else {
+      // process.loadEnvFile landed in Node 20.12; the package supports
+      // >=20. Silently skipping .env.local on 20.0–20.11 would ignore
+      // UAI_TELEMETRY_DISABLED — the telemetry kill switch MUST load on
+      // every supported Node, so fall back to dotenv (already a dep).
+      // Neither loader overrides pre-set process.env — same semantics.
+      dotenvConfig({ path });
+    }
+  } catch (err) {
+    console.warn(
+      `[host-agent] could not load ${file}: ${(err as Error).message}`,
+    );
+  }
+}

package/src/machine-tunnel-route.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-121 machine tunnel routing, extracted from main.ts so its one expensive
+ * step is bounded and testable. Resolving a machine's address is a cloud API
+ * call — `aws ec2 describe-instances` through a spawned CLI, 0.5–1.5 s on the
+ * default t4g.medium host — and the cloud opens one tunnel per HTTP request,
+ * so a browser pane (noVNC ships dozens of unbundled modules) or the editor
+ * (code-server, more) paid that call dozens of times per load. Live
+ * 2026-09-06: "connecting, but very slow" on every AWS machine task, while
+ * Docker and apple-container hosts, whose routes are a local inspect, felt
+ * instant.
+ *
+ * The memo is per task, short (MACHINE_ROUTE_TTL_MS), and holds only a proven
+ * `running` route: a stopped or unknown machine is asked again on every open
+ * so a wake is seen promptly; a dial failure drops the entry so a machine that
+ * moved (a fresh public IP after stop/start) is re-described on the next open;
+ * a stop/down command drops it too — and bumps a per-task generation, so a
+ * description that was already in flight when the stop landed cannot
+ * re-memoise the pre-stop address. Concurrent cold opens share one resolution
+ * (the pane's first burst is half a dozen parallel requests), and a machine
+ * seen not running is not asked again for a few seconds (noVNC retries every
+ * couple of seconds against a stopped machine; without that, each retry was
+ * a CLI spawn). A refused dial invalidates at once. An address that
+ * black-holes (an instance stopped while memoised) answers nothing, so the
+ * route carries its own connect bound, MACHINE_DIAL_CONNECT_TIMEOUT_MS: both
+ * dial paths in main.ts arm it (`tunnel-dial.ts`) and the timeout surfaces as
+ * an ordinary dial error, which invalidates the entry exactly like a refusal.
+ * Before host 0.9.99 machine dials had no timeout of their own and a
+ * black-holed address hung on the kernel's SYN budget (~75 s macOS, ~127 s
+ * Linux) — longer than the memo TTL, so the TTL was never the real bound.
+ */
+
+export type MachineTunnelRoute =
+  | { kind: "running"; ipv4Address: string }
+  | { kind: "unavailable" }
+  | { kind: "unknown"; detail: string };
+
+export interface MachineTunnelRouteDeps<Task> {
+  reconstruct(task: Task): Promise<{
+    inspectRoute?: () => Promise<MachineTunnelRoute>;
+  } | null>;
+  now(): number;
+  ttlMs?: number;
+}
+
+export interface MachineTunnelRouteRequest {
+  taskId: string;
+  target: string;
+  containerPort?: number;
+}
+
+/** Long enough to cover a pane or editor load (dozens of opens inside a few
+ * seconds), short enough that a machine's address is never trusted past the
+ * next stop/start cycle by much; a failed dial drops it sooner. */
+export const MACHINE_ROUTE_TTL_MS = 45_000;
+/** How long a not-running answer is trusted before the machine is asked
+ * again — long enough to absorb a reconnecting pane, short enough that a wake
+ * is seen within seconds. */
+export const MACHINE_ROUTE_NEGATIVE_TTL_MS = 5_000;
+/** Connect-phase bound for a dial to a memoised machine address. An
+ * in-region machine answers a SYN in milliseconds; the cloud waits 30 s for
+ * the tunnel ack and the forward hop 45 s for the head, so 10 s is generous
+ * to a live machine and still leaves the caller a real answer (a 502 and a
+ * dropped memo) instead of the kernel's SYN retry budget. */
+export const MACHINE_DIAL_CONNECT_TIMEOUT_MS = 10_000;
+
+/** A resolved machine route: where to dial, and the connect bound the dial
+ * must carry because the address is memoised. */
+export interface MachineTunnelRouteTarget {
+  host: string;
+  port: number;
+  connectTimeoutMs: number;
+}
+
+const memo = new Map<string, { ipv4Address: string; expiresAt: number }>();
+const negative = new Map<string, number>();
+const inFlight = new Map<string, Promise<string | null>>();
+/** Bumped by every invalidation; a resolution only writes the memo if the
+ * generation it started under is still current. */
+const generation = new Map<string, number>();
+
+export async function resolveMachineTunnelRoute<
+  Task extends { codeServerPort?: number | null },
+>(
+  request: MachineTunnelRouteRequest,
+  task: Task,
+  deps: MachineTunnelRouteDeps<Task>,
+): Promise<MachineTunnelRouteTarget | null> {
+  // The cheap refusal first: an unroutable request never costs an API call.
+  const port =
+    request.target === "editor"
+      ? (task.codeServerPort ?? null)
+      : (request.containerPort ?? null);
+  if (!port) return null;
+  const host = await machineAddress(request.taskId, task, deps);
+  return host === null
+    ? null
+    : { host, port, connectTimeoutMs: MACHINE_DIAL_CONNECT_TIMEOUT_MS };
+}
+
+async function machineAddress<Task>(
+  taskId: string,
+  task: Task,
+  deps: MachineTunnelRouteDeps<Task>,
+): Promise<string | null> {
+  const now = deps.now();
+  const hit = memo.get(taskId);
+  if (hit && hit.expiresAt > now) return hit.ipv4Address;
+  memo.delete(taskId);
+  const notRunningUntil = negative.get(taskId);
+  if (notRunningUntil !== undefined && notRunningUntil > now) return null;
+  negative.delete(taskId);
+  const pending = inFlight.get(taskId);
+  if (pending) return pending;
+  const startedUnder = generation.get(taskId) ?? 0;
+  const resolution = (async (): Promise<string | null> => {
+    const environment = await deps.reconstruct(task);
+    const route = environment?.inspectRoute
+      ? await environment.inspectRoute()
+      : null;
+    const settledAt = deps.now();
+    const stillCurrent = (generation.get(taskId) ?? 0) === startedUnder;
+    if (!route || route.kind !== "running") {
+      if (stillCurrent) {
+        negative.set(taskId, settledAt + MACHINE_ROUTE_NEGATIVE_TTL_MS);
+      }
+      return null;
+    }
+    if (stillCurrent) {
+      memo.set(taskId, {
+        ipv4Address: route.ipv4Address,
+        expiresAt: settledAt + (deps.ttlMs ?? MACHINE_ROUTE_TTL_MS),
+      });
+    }
+    return route.ipv4Address;
+  })().finally(() => {
+    inFlight.delete(taskId);
+  });
+  inFlight.set(taskId, resolution);
+  return resolution;
+}
+
+/** A dial to the memoised address failed, or the task was stopped, started or
+ * torn down: the next open must describe the machine again, and a description
+ * already in flight must not write what it learned before this point. */
+export function invalidateMachineTunnelRoute(taskId: string): void {
+  memo.delete(taskId);
+  negative.delete(taskId);
+  generation.set(taskId, (generation.get(taskId) ?? 0) + 1);
+}
+
+export function resetMachineTunnelRoutesForTesting(): void {
+  memo.clear();
+  negative.clear();
+  inFlight.clear();
+  generation.clear();
+}