@runuai/host 0.9.97 → 0.9.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.97",
+  "version": "0.9.98",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/machine-tunnel-route.ts

@@ -0,0 +1,136 @@
+/**
+ * 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) hangs on the OS connect
+ * timeout instead — machine dials carry no connect timeout of their own,
+ * which predates this module — so the TTL is the real bound there.
+ */
+
+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;
+
+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<{ host: string; port: number } | 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 };
+}
+
+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();
+}

package/src/main.ts

@@ -112,6 +112,10 @@ import {
 import { reconstructPersistedTaskEnvironment } from "../lib/task-environment";
 import { logVnodePressure } from "../lib/vnode-pressure";
 import { resolveAppleTunnelRoute } from "./apple-tunnel-route";
+import {
+  invalidateMachineTunnelRoute,
+  resolveMachineTunnelRoute,
+} from "./machine-tunnel-route";
 import {
   configureBundledContainerRuntime,
   selectedRuntimeMatchesPersistedTaskEnvironments,
@@ -554,9 +558,16 @@ async function startLocalUi(): Promise<void> {
       stopTask: async (taskId) => {
         const runtimeProblem = containerRuntimeProblem();
         if (runtimeProblem) return { ok: false, error: runtimeProblem };
-        const result = await getOrchestrator().stopTask(taskId);
-        if (result.ok) queueStoppedTaskStatus(taskId);
-        return result;
+        // ADR-121: a stopped machine loses its memoised address (same
+        // before-and-after discipline as the cloud's taskStop command).
+        invalidateMachineTunnelRoute(taskId);
+        try {
+          const result = await getOrchestrator().stopTask(taskId);
+          if (result.ok) queueStoppedTaskStatus(taskId);
+          return result;
+        } finally {
+          invalidateMachineTunnelRoute(taskId);
+        }
       },
     });
     console.log(`[host-agent] local UI on http://127.0.0.1:${handle.port}`);
@@ -1861,6 +1872,8 @@ function handleHttpTunnelOpen(
     // ADR-043: if this was an ad-hoc preview sidecar, drop its cached port so
     // the next request recreates it (no-op for published / container-IP targets).
     invalidatePreviewSidecar(target.port);
+    // ADR-121: a memoised machine address that no longer answers is stale.
+    invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -1927,6 +1940,8 @@ function handleRawTunnelOpen(
     // ADR-043: if this was an ad-hoc preview sidecar, drop its cached port so
     // the next request recreates it (no-op for published / container-IP targets).
     invalidatePreviewSidecar(target.port);
+    // ADR-121: a memoised machine address that no longer answers is stale.
+    invalidateMachineTunnelRoute(frame.taskId);
     if (!acked) {
       send(wsSocket, {
         kind: "tunnel.ack",
@@ -2004,17 +2019,23 @@ async function resolveTunnelTarget(
     // the container runtime's health. macOS-local machines need a published
     // fallback (bridge IPs are not host-routable there) — recorded ADR-121
     // follow-up, not silently misrouted: the connect simply fails.
-    const environment = await reconstructPersistedTaskEnvironment(machineTask);
-    const route = environment?.inspectRoute
-      ? await environment.inspectRoute()
-      : null;
-    if (!route || route.kind !== "running") return null;
-    const port =
-      frame.target === "editor"
-        ? (machineTask.codeServerPort ?? null)
-        : (frame.containerPort ?? null);
-    if (!port) return null;
-    return { host: route.ipv4Address, port };
+    // The address resolution is a cloud API call and the cloud opens one
+    // tunnel per request, so it is memoised per task for a short TTL and
+    // dropped on a failed dial or a stop — see machine-tunnel-route.ts.
+    return resolveMachineTunnelRoute(
+      {
+        taskId: frame.taskId,
+        target: frame.target,
+        ...(frame.containerPort !== undefined
+          ? { containerPort: frame.containerPort }
+          : {}),
+      },
+      machineTask,
+      {
+        reconstruct: (task) => reconstructPersistedTaskEnvironment(task),
+        now: Date.now,
+      },
+    );
   }
   if (containerRuntimeProblem()) return null;
   const task = getHostTask(frame.taskId);
@@ -2275,18 +2296,36 @@ async function dispatchCommand(
   args: unknown[],
 ): Promise<HostCommandResult<unknown>> {
   switch (command) {
-    case "taskUp":
-      return hostCommands.taskUp(ctx, expectTaskLaunchInput(args, 0));
+    case "taskUp": {
+      const launchInput = expectTaskLaunchInput(args, 0);
+      // A (re)started machine may come back on a new address, and one just
+      // seen as not-running is about to run: forget both, before and after.
+      invalidateMachineTunnelRoute(launchInput.task.id);
+      return hostCommands
+        .taskUp(ctx, launchInput)
+        .finally(() => invalidateMachineTunnelRoute(launchInput.task.id));
+    }
     case "taskDown": {
       const downInput = expectTaskDownInput(args, 0);
-      return hostCommands.taskDown(ctx, downInput);
+      // A torn-down machine loses its address: drop the memo before (opens in
+      // flight must not re-memoise) and after (opens that raced the command).
+      invalidateMachineTunnelRoute(downInput.taskId);
+      return hostCommands
+        .taskDown(ctx, downInput)
+        .finally(() => invalidateMachineTunnelRoute(downInput.taskId));
+    }
+    case "taskStop": {
+      const stopTaskId = typeof args[0] === "string" ? args[0] : "";
+      // A stopped machine loses its address; same before-and-after discipline.
+      invalidateMachineTunnelRoute(stopTaskId);
+      return hostCommands
+        .taskStop(
+          ctx,
+          stopTaskId,
+          (args[1] ?? { reason: "manual" }) as { reason: "idle" | "manual" },
+        )
+        .finally(() => invalidateMachineTunnelRoute(stopTaskId));
     }
-    case "taskStop":
-      return hostCommands.taskStop(
-        ctx,
-        typeof args[0] === "string" ? args[0] : "",
-        (args[1] ?? { reason: "manual" }) as { reason: "idle" | "manual" },
-      );
     case "taskStatus":
       return hostCommands.taskStatus(ctx, expectString(args, 0));
     case "channelEnsure":