@runuai/host 0.9.77 → 0.9.78

package/lib/machine-gateway-tunnel.ts

@@ -0,0 +1,166 @@
+/**
+ * ADR-121: the MCP gateway reverse tunnel for machine tasks.
+ *
+ * Containers reach the host's MCP gateway via container topology
+ * (host.docker.internal, the vmnet gateway IP). A machine — an EC2
+ * instance behind its own network — can never route to the host, so the
+ * host pushes the gateway TO the machine instead: one persistent
+ * `ssh -N -R 127.0.0.1:<port>:127.0.0.1:<port>` per machine task, using
+ * the same per-task key every other machine operation rides. Task configs
+ * then point MCP servers at the machine's own loopback
+ * (setupMcpTaskConfig's machine branch).
+ *
+ * Supervision: the tunnel respawns with a short backoff while ensured —
+ * re-resolving the machine address each spawn, since it changes across
+ * stop/start — and stops when the task stops, tears down, or the process
+ * exits. Failure is quiet-but-logged: MCP servers failing to connect is
+ * the visible symptom, and the agent-facing degradation is already
+ * per-server.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+
+import { MCP_GATEWAY_PORT } from "./mcp-gateway";
+
+const RESPAWN_DELAY_MS = 3_000;
+/** After this many consecutive sub-5s deaths, slow the respawn cadence so a
+ * permanently unreachable machine does not spin ssh forever. */
+const FAST_DEATH_THRESHOLD = 5;
+const SLOW_RESPAWN_DELAY_MS = 60_000;
+
+export interface MachineTunnelSource {
+  gatewayTunnelSshArgs(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]>;
+}
+
+interface TunnelState {
+  generation: number;
+  child: ChildProcess | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  fastDeaths: number;
+  spawnedAt: number;
+}
+
+const tunnels = new Map<string, TunnelState>();
+
+/** Idempotently keep a gateway tunnel alive for this machine task. */
+export function ensureMachineGatewayTunnel(
+  taskId: string,
+  source: MachineTunnelSource,
+): void {
+  const existing = tunnels.get(taskId);
+  if (existing && (existing.child !== null || existing.timer !== null)) {
+    return; // live or already scheduled
+  }
+  const state: TunnelState = existing ?? {
+    generation: 0,
+    child: null,
+    timer: null,
+    fastDeaths: 0,
+    spawnedAt: 0,
+  };
+  state.generation += 1;
+  tunnels.set(taskId, state);
+  if (existing === undefined) {
+    console.log(`[machine-tunnel] ${taskId}: ensuring gateway tunnel`);
+  }
+  void spawnTunnel(taskId, source, state, state.generation);
+}
+
+async function spawnTunnel(
+  taskId: string,
+  source: MachineTunnelSource,
+  state: TunnelState,
+  generation: number,
+): Promise<void> {
+  if (tunnels.get(taskId) !== state || state.generation !== generation) return;
+  let args: string[];
+  try {
+    args = await source.gatewayTunnelSshArgs(
+      MCP_GATEWAY_PORT,
+      MCP_GATEWAY_PORT,
+    );
+  } catch (err) {
+    // Machine not reachable right now (stopped, address settling) — retry
+    // on the slow cadence; a stop/teardown clears us before it matters.
+    scheduleRespawn(taskId, source, state, generation, SLOW_RESPAWN_DELAY_MS);
+    if (state.fastDeaths === 0) {
+      console.warn(
+        `[machine-tunnel] ${taskId}: target unavailable (${err instanceof Error ? err.message : err}) — retrying`,
+      );
+    }
+    state.fastDeaths += 1;
+    return;
+  }
+  state.spawnedAt = Date.now();
+  const child = spawn("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
+  state.child = child;
+  let stderrTail = "";
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-2048);
+  });
+  child.once("exit", (code) => {
+    if (tunnels.get(taskId) !== state || state.generation !== generation) {
+      return;
+    }
+    state.child = null;
+    const lifetimeMs = Date.now() - state.spawnedAt;
+    if (lifetimeMs < 5_000) state.fastDeaths += 1;
+    else state.fastDeaths = 0;
+    const slow = state.fastDeaths >= FAST_DEATH_THRESHOLD;
+    if (state.fastDeaths === FAST_DEATH_THRESHOLD) {
+      console.warn(
+        `[machine-tunnel] ${taskId}: tunnel keeps dying (exit ${code ?? "signal"}${
+          stderrTail.trim() ? `: ${stderrTail.trim().slice(0, 200)}` : ""
+        }) — slowing retries`,
+      );
+    }
+    scheduleRespawn(
+      taskId,
+      source,
+      state,
+      generation,
+      slow ? SLOW_RESPAWN_DELAY_MS : RESPAWN_DELAY_MS,
+    );
+  });
+  child.once("error", () => {
+    // exit fires too; the handler above owns respawn.
+  });
+}
+
+function scheduleRespawn(
+  taskId: string,
+  source: MachineTunnelSource,
+  state: TunnelState,
+  generation: number,
+  delayMs: number,
+): void {
+  if (tunnels.get(taskId) !== state || state.generation !== generation) return;
+  state.timer = setTimeout(() => {
+    state.timer = null;
+    void spawnTunnel(taskId, source, state, generation);
+  }, delayMs);
+  state.timer.unref?.();
+}
+
+/** Tear the tunnel down (task stop/teardown/GC). Idempotent. */
+export function stopMachineGatewayTunnel(taskId: string): void {
+  const state = tunnels.get(taskId);
+  if (!state) return;
+  tunnels.delete(taskId);
+  state.generation += 1; // invalidate in-flight spawns
+  if (state.timer) clearTimeout(state.timer);
+  if (state.child) {
+    state.child.kill("SIGTERM");
+    state.child = null;
+  }
+}
+
+/** Test-only view. */
+export function machineGatewayTunnelActive(taskId: string): boolean {
+  const state = tunnels.get(taskId);
+  return Boolean(state && (state.child !== null || state.timer !== null));
+}

package/lib/mcp-gateway.ts

@@ -854,11 +854,14 @@ function gatewayIdentity(value, slug) {
 }
 
 function sameTaskGateway(oldUrl, desiredUrl, slug) {
+  // Ownership is proven by the /t/<taskId>.<token>/<slug> path, not the
+  // origin: the gateway host is topology-dependent (container gateway IP,
+  // host.docker.internal, machine loopback behind a reverse tunnel) and
+  // migrating a task across topologies is exactly when the rewrite runs.
   const oldIdentity = gatewayIdentity(oldUrl, slug);
   const desiredIdentity = gatewayIdentity(desiredUrl, slug);
   return oldIdentity !== null &&
     desiredIdentity !== null &&
-    oldIdentity.origin === desiredIdentity.origin &&
     oldIdentity.taskId === desiredIdentity.taskId;
 }
 
@@ -1063,7 +1066,8 @@ export async function setupMcpTaskConfig(
   connections: TaskMcpConnection[],
   engineKinds: string[],
   codexHomes: readonly string[] = ["/home/node/.codex"],
-  environment?: Pick<TaskEnvironmentHandle, "exec">,
+  environment?: Pick<TaskEnvironmentHandle, "exec"> &
+    Partial<Pick<TaskEnvironmentHandle, "descriptor">>,
 ): Promise<boolean> {
   // No early return on empty: the claude adapter passes
   // `--mcp-config /workspace/.mcp.json` unconditionally (ADR-057), so the
@@ -1084,7 +1088,14 @@ export async function setupMcpTaskConfig(
       throw new Error("invalid Codex MCP connection slug");
     }
     const acl = ensureTaskGatewayAcl(taskId, connections);
-    const gatewayHost = await taskGatewayHost();
+    // ADR-121: a machine dials the gateway through its ssh REVERSE tunnel —
+    // the host's loopback appears at the machine's own 127.0.0.1:PORT
+    // (machine-gateway-tunnel.ts). host.docker.internal / vmnet addresses
+    // are container topology a machine can never route.
+    const gatewayHost =
+      environment?.descriptor?.locator.provider === "machine"
+        ? "127.0.0.1"
+        : await taskGatewayHost();
     const urlFor = (slug: string): string =>
       `http://${gatewayHost}:${MCP_GATEWAY_PORT}/t/${acl.token}/${slug}`;
 

package/lib/orchestrator.ts

@@ -90,6 +90,7 @@ import {
   type SkillExec,
   writeAgentSkills,
 } from "./skills";
+import { ensureMachineGatewayTunnel } from "./machine-gateway-tunnel";
 import {
   CONTAINER_CLI_PATH,
   agentCliEnv,
@@ -1655,7 +1656,14 @@ export class Orchestrator {
       return environment;
     })();
     const tracked = created.then((environment) => {
-      if (this.isActiveChannel(channel)) channel.agentHandle = environment;
+      if (this.isActiveChannel(channel)) {
+        channel.agentHandle = environment;
+        // Every path that touches a machine workspace settles the handle
+        // here — including durable-session reattach after a host restart,
+        // which spawns no sessions and runs no config writers. Ensuring the
+        // gateway tunnel at the funnel keeps it alive across all of them.
+        ensureMachineGatewayTunnelFor(channel.taskId, environment);
+      }
       return environment;
     });
     channel.agentEnvironment = tracked;
@@ -5641,6 +5649,20 @@ async function quarantineWritableAppleRuntimeContainers(options: {
  * machine tasks (their workspace is not host-reachable). Best-effort like the
  * host-side writer.
  */
+/** Keep the MCP gateway reverse tunnel alive for a machine channel. The
+ * handle exposes tunnel argv only on the machine provider; anything else is
+ * a quiet no-op. */
+function ensureMachineGatewayTunnelFor(
+  taskId: string,
+  handle: TaskEnvironmentHandle<unknown> | null,
+): void {
+  const argv = handle?.gatewayTunnelSshArgs;
+  if (!argv) return;
+  ensureMachineGatewayTunnel(taskId, {
+    gatewayTunnelSshArgs: argv.bind(handle),
+  });
+}
+
 async function materializeAgentCli(
   task: typeof schema.hostTasks.$inferSelect,
   roster: RosterAgent[],

package/lib/task-environment/machine-task-up.ts

@@ -448,6 +448,12 @@ function withTaskDownResult(
     ...(handle.inspectRoute
       ? { inspectRoute: () => handle.inspectRoute!() }
       : {}),
+    ...(handle.gatewayTunnelSshArgs
+      ? {
+          gatewayTunnelSshArgs: (machinePort: number, hostPort: number) =>
+            handle.gatewayTunnelSshArgs!(machinePort, hostPort),
+        }
+      : {}),
   };
 }
 

package/lib/task-environment/machine.ts

@@ -504,6 +504,31 @@ class MachineTaskEnvironmentHandle implements TaskEnvironmentHandle {
     };
   }
 
+  /** Full ssh argv for the persistent REVERSE gateway tunnel: the host's
+   * loopback gateway appears at the machine's own 127.0.0.1:<machinePort>.
+   * Resolved per call — cloud machines change address across stop/start, so
+   * each (re)spawn of the tunnel re-resolves the dial target. */
+  async gatewayTunnelSshArgs(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]> {
+    const target = await this.#target();
+    return [
+      "-o", "BatchMode=yes",
+      "-o", "StrictHostKeyChecking=accept-new",
+      "-o", "ConnectTimeout=10",
+      "-o", "ExitOnForwardFailure=yes",
+      "-o", "ServerAliveInterval=15",
+      "-o", "ServerAliveCountMax=3",
+      "-i", target.keyPath,
+      "-p", String(target.port ?? 22),
+      "-l", this.#value.sshUser,
+      target.address,
+      "-N",
+      "-R", `127.0.0.1:${machinePort}:127.0.0.1:${hostPort}`,
+    ];
+  }
+
   async status(): Promise<TaskEnvironmentStatus> {
     const info = await this.#describeOwn();
     switch (info.state) {

package/lib/task-environment/types.ts

@@ -220,6 +220,14 @@ export interface TaskEnvironmentHandle<TTeardownResult = void>
     | { kind: "unavailable" }
     | { kind: "unknown"; detail: string }
   >;
+  /** ADR-121, machine provider only: full ssh argv for the persistent
+   * REVERSE gateway tunnel that makes the host's MCP gateway answer on the
+   * environment's own loopback. Container providers omit it — their tasks
+   * route to the gateway via container topology instead. */
+  gatewayTunnelSshArgs?(
+    machinePort: number,
+    hostPort: number,
+  ): Promise<string[]>;
 }
 
 export interface TaskEnvironmentProvisionRequest<TInput, TCredentials> {

package/package.json

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

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   removeTaskCliSecretStrict,
   storeTaskCliSecret,
 } from "../lib/agent-cli";
+import { stopMachineGatewayTunnel } from "../lib/machine-gateway-tunnel";
 import {
   clearRefresh,
   injectIntoContainer,
@@ -966,9 +967,13 @@ export const hostCommands: HostCommands = {
           !orphanGc &&
           environment.descriptor.locator.provider === "machine"
         ) {
+          stopMachineGatewayTunnel(input.taskId);
           await environment.stop();
           return taskDownResultForInput(input, { status: "stopped" });
         }
+        if (environment.descriptor.locator.provider === "machine") {
+          stopMachineGatewayTunnel(input.taskId);
+        }
         return taskDownResultForInput(input, await environment.teardown());
       });
       if (result.ok) {