@runuai/host 0.9.13 → 0.9.42

package/lib/tunnel-registry.ts

@@ -31,11 +31,26 @@ export interface TunnelUpstream {
 }
 
 type TunnelOp = (upstream: TunnelUpstream) => void;
+type TunnelRelease = () => Promise<void>;
+
+interface OpenTunnel {
+  readonly upstream: TunnelUpstream;
+  readonly release: TunnelRelease;
+}
+
+interface OpeningTunnel {
+  readonly ops: TunnelOp[];
+  readonly settled: Promise<void>;
+  finish(): void;
+  aborted: boolean;
+}
 
 export class TunnelRegistry {
-  private readonly open = new Map<string, TunnelUpstream>();
+  private readonly open = new Map<string, OpenTunnel>();
   /** tunnelId -> ops that arrived while its `tunnel.open` was still resolving. */
-  private readonly opening = new Map<string, TunnelOp[]>();
+  private readonly opening = new Map<string, OpeningTunnel>();
+  /** Async provider teardown is joined by connection replacement/shutdown. */
+  private readonly pendingReleases = new Set<Promise<void>>();
 
   /**
    * Mark a tunnel as opening. MUST be called synchronously when `tunnel.open`
@@ -44,29 +59,61 @@ export class TunnelRegistry {
    * whole bug this class exists for.
    */
   markOpening(tunnelId: string): void {
-    this.opening.set(tunnelId, []);
+    const previous = this.opening.get(tunnelId);
+    if (previous) {
+      previous.aborted = true;
+      previous.finish();
+    }
+    let finish!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    this.opening.set(tunnelId, {
+      ops: [],
+      settled,
+      finish,
+      aborted: false,
+    });
   }
 
-  /** Target resolved: publish the upstream and replay what arrived meanwhile. */
-  register(tunnelId: string, upstream: TunnelUpstream): void {
-    this.open.set(tunnelId, upstream);
-    const queued = this.opening.get(tunnelId);
+  /** Target resolved: publish the upstream and replay what arrived meanwhile.
+   * Returns whether this upstream now owns the tunnel — false means the open
+   * was canceled during resolution and the upstream was destroyed, so the
+   * caller must not write to it (a stale generation must never emit bytes). */
+  register(
+    tunnelId: string,
+    upstream: TunnelUpstream,
+    release: TunnelRelease = async () => {},
+  ): boolean {
+    const pending = this.opening.get(tunnelId);
     this.opening.delete(tunnelId);
-    if (!queued) return;
-    for (const op of queued) op(upstream);
+    pending?.finish();
+    const releaseOnce = onceAsync(release);
+    if (pending?.aborted) {
+      upstream.destroy();
+      this.trackRelease(releaseOnce());
+      return false;
+    }
+    this.open.set(tunnelId, { upstream, release: releaseOnce });
+    if (!pending) return true;
+    for (const op of pending.ops) op(upstream);
+    return true;
   }
 
   /** Open failed (no target, or it errored) — nothing will ever service these. */
   abandon(tunnelId: string): void {
+    this.opening.get(tunnelId)?.finish();
     this.opening.delete(tunnelId);
   }
 
   get(tunnelId: string): TunnelUpstream | undefined {
-    return this.open.get(tunnelId);
+    return this.open.get(tunnelId)?.upstream;
   }
 
   delete(tunnelId: string): void {
+    const current = this.open.get(tunnelId);
     this.open.delete(tunnelId);
+    if (current) this.trackRelease(current.release());
   }
 
   /**
@@ -76,12 +123,13 @@ export class TunnelRegistry {
    * race.
    */
   apply(tunnelId: string, op: TunnelOp): void {
-    const upstream = this.open.get(tunnelId);
-    if (upstream) {
-      op(upstream);
+    const current = this.open.get(tunnelId);
+    if (current) {
+      op(current.upstream);
       return;
     }
-    this.opening.get(tunnelId)?.push(op);
+    const pending = this.opening.get(tunnelId);
+    if (pending && !pending.aborted) pending.ops.push(op);
   }
 
   /**
@@ -91,14 +139,82 @@ export class TunnelRegistry {
    * at worst an unhandled error on a socket nobody is listening to any more.
    */
   abort(tunnelId: string): void {
-    const upstream = this.open.get(tunnelId);
+    const current = this.open.get(tunnelId);
     this.open.delete(tunnelId);
-    if (upstream) {
-      upstream.destroy();
+    if (current) {
+      current.upstream.destroy();
+      this.trackRelease(current.release());
       return;
     }
-    if (this.opening.has(tunnelId)) {
-      this.opening.set(tunnelId, [(u) => u.destroy()]);
+    const pending = this.opening.get(tunnelId);
+    if (pending) {
+      pending.ops.length = 0;
+      pending.aborted = true;
     }
   }
+
+  /** Destroy every upstream from one bridge generation and wait until opening
+   * targets have either failed or registered and their provider resources are
+   * released. No SSH forward may outlive the WebSocket generation that owns
+   * it — but reconnect must not be hostage to one wedged open, so the join is
+   * bounded: entries are already marked aborted, their eventual register()
+   * destroys the upstream and releases provider resources, and the releases
+   * stay tracked for the next generation's join. */
+  async abortAll(timeoutMs = 15_000): Promise<void> {
+    for (const pending of this.opening.values()) {
+      pending.ops.length = 0;
+      pending.aborted = true;
+    }
+    for (const [tunnelId, current] of this.open) {
+      this.open.delete(tunnelId);
+      current.upstream.destroy();
+      this.trackRelease(current.release());
+    }
+    let timer: NodeJS.Timeout | undefined;
+    const expired = new Promise<"timeout">((resolve) => {
+      timer = setTimeout(() => resolve("timeout"), timeoutMs);
+      timer.unref?.();
+    });
+    try {
+      while (this.opening.size > 0 || this.pendingReleases.size > 0) {
+        const opening = [...this.opening.values()].map((entry) => entry.settled);
+        const outcome = await Promise.race([
+          Promise.all([...opening, ...this.pendingReleases]).then(
+            () => "settled" as const,
+          ),
+          expired,
+        ]);
+        if (outcome === "timeout") {
+          console.warn(
+            `[tunnel] abortAll: ${this.opening.size} opening and ` +
+              `${this.pendingReleases.size} releasing tunnels did not settle ` +
+              `within ${timeoutMs}ms; continuing while they drain`,
+          );
+          return;
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private trackRelease(release: Promise<void>): void {
+    // A rejected provider release must neither crash the process (a bare
+    // `.finally()` chain rethrows with no handler attached) nor poison the
+    // abortAll() join above — cleanup failure is logged, never fatal.
+    const settled = release.catch((error: unknown) => {
+      console.warn(
+        `[tunnel] upstream release failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    });
+    this.pendingReleases.add(settled);
+    void settled.finally(() => this.pendingReleases.delete(settled));
+  }
+}
+
+function onceAsync(operation: TunnelRelease): TunnelRelease {
+  let result: Promise<void> | null = null;
+  return () => (result ??= operation());
 }

package/lib/tunnel-runtime.ts

@@ -0,0 +1,235 @@
+import { isIP } from "node:net";
+
+import { dockerCli, type DockerResult } from "./docker-exec";
+import { reprobeContainerRuntimeMachineIdentity } from "./container-runtime";
+
+type DockerRunner = (
+  args: string[],
+  options?: { timeoutMs?: number },
+) => Promise<DockerResult>;
+
+export type TunnelContainerProof =
+  | {
+      kind: "running";
+      containerId: string;
+      published: { host: string; port: number } | null;
+      containerIp: string | null;
+      network: string | null;
+      labels: Record<string, string>;
+    }
+  | { kind: "unavailable" }
+  | { kind: "daemon-unavailable"; detail: string };
+
+interface DockerContainerInspection {
+  Id?: unknown;
+  Name?: unknown;
+  Config?: { Labels?: Record<string, unknown> | null };
+  State?: { Running?: unknown };
+  NetworkSettings?: {
+    Ports?: Record<
+      string,
+      Array<{ HostIp?: unknown; HostPort?: unknown }> | null
+    >;
+    Networks?: Record<string, { IPAddress?: unknown }>;
+  };
+}
+
+const COMPOSE_PROJECT_LABEL = "com.docker.compose.project";
+const COMPOSE_SERVICE_LABEL = "com.docker.compose.service";
+const CONTAINER_ID = /^[a-f0-9]{64}$/;
+
+/**
+ * Prove that an exact container is running and resolve its current routes.
+ *
+ * Persisted host ports and cached container IPs are unsafe after an unnoticed
+ * daemon restart: Docker may remap the app, and an unrelated local process (or
+ * another container) can inherit the old address. Every tunnel open crosses
+ * this proof before bytes are forwarded.
+ */
+export async function inspectTunnelContainer(
+  container: string,
+  containerPort: number,
+  deps: { docker?: DockerRunner } = {},
+): Promise<TunnelContainerProof> {
+  const run = deps.docker ?? dockerCli;
+  const inspected = await run(
+    ["inspect", "--format", "{{json .}}", container],
+    { timeoutMs: 5_000 },
+  );
+  if (inspected.status !== 0) {
+    if (!deps.docker) {
+      return (await reprobeContainerRuntimeMachineIdentity()) === null
+        ? { kind: "daemon-unavailable", detail: "docker did not answer" }
+        : { kind: "unavailable" };
+    }
+    const daemon = await run(
+      ["info", "--format", "{{.ServerVersion}}"],
+      { timeoutMs: 5_000 },
+    );
+    if (daemon.status !== 0 || !daemon.stdout.trim()) {
+      return {
+        kind: "daemon-unavailable",
+        // This reaches cloud-visible command errors. Docker's own diagnostic
+        // can contain the pinned unix socket (and therefore a host username),
+        // so keep endpoint details in Docker's local logs rather than the wire.
+        detail: "docker did not answer",
+      };
+    }
+    return { kind: "unavailable" };
+  }
+
+  let value: DockerContainerInspection;
+  try {
+    value = JSON.parse(inspected.stdout.trim()) as DockerContainerInspection;
+  } catch {
+    return { kind: "unavailable" };
+  }
+  if (value.State?.Running !== true) return { kind: "unavailable" };
+
+  const containerId = exactContainerId(value.Id);
+  if (!containerId) return { kind: "unavailable" };
+  const address = firstContainerAddress(value);
+
+  return {
+    kind: "running",
+    containerId,
+    published: publishedAddress(value, containerPort),
+    containerIp: address?.ip ?? null,
+    network: address?.network ?? null,
+    labels: stringLabels(value.Config?.Labels),
+  };
+}
+
+/**
+ * Stronger proof for editor/preview routing into a task's app. Docker's exact
+ * name lookup is necessary but not sufficient: a recreated or foreign
+ * container can reuse it. Bind the route to Compose's project/service labels,
+ * the full container ID, and only the expected project default network.
+ */
+export async function inspectTaskAppTunnelContainer(
+  request: {
+    readonly container: string;
+    readonly composeProject: string;
+    readonly containerPort: number;
+  },
+  deps: { docker?: DockerRunner } = {},
+): Promise<TunnelContainerProof> {
+  const run = deps.docker ?? dockerCli;
+  const inspected = await run(
+    ["inspect", "--format", "{{json .}}", request.container],
+    { timeoutMs: 5_000 },
+  );
+  if (inspected.status !== 0) {
+    if (!deps.docker) {
+      return (await reprobeContainerRuntimeMachineIdentity()) === null
+        ? { kind: "daemon-unavailable", detail: "docker did not answer" }
+        : { kind: "unavailable" };
+    }
+    const daemon = await run(
+      ["info", "--format", "{{.ServerVersion}}"],
+      { timeoutMs: 5_000 },
+    );
+    if (daemon.status !== 0 || !daemon.stdout.trim()) {
+      return { kind: "daemon-unavailable", detail: "docker did not answer" };
+    }
+    return { kind: "unavailable" };
+  }
+
+  let value: DockerContainerInspection;
+  try {
+    value = JSON.parse(inspected.stdout.trim()) as DockerContainerInspection;
+  } catch {
+    return { kind: "unavailable" };
+  }
+  const labels = stringLabels(value.Config?.Labels);
+  const containerId = exactContainerId(value.Id);
+  const network = `${request.composeProject}_default`;
+  const ip = exactNetworkAddress(value, network);
+  if (
+    value.State?.Running !== true ||
+    value.Name !== `/${request.container}` ||
+    !containerId ||
+    labels[COMPOSE_PROJECT_LABEL] !== request.composeProject ||
+    labels[COMPOSE_SERVICE_LABEL] !== "app" ||
+    !ip
+  ) {
+    return { kind: "unavailable" };
+  }
+  return {
+    kind: "running",
+    containerId,
+    published: publishedAddress(value, request.containerPort),
+    containerIp: ip,
+    network,
+    labels,
+  };
+}
+
+function exactContainerId(value: unknown): string | null {
+  return typeof value === "string" && CONTAINER_ID.test(value) ? value : null;
+}
+
+function stringLabels(
+  labels: Record<string, unknown> | null | undefined,
+): Record<string, string> {
+  if (!labels) return {};
+  return Object.fromEntries(
+    Object.entries(labels).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+}
+
+function publishedAddress(
+  value: DockerContainerInspection,
+  containerPort: number,
+): { host: string; port: number } | null {
+  const bindings = value.NetworkSettings?.Ports?.[`${containerPort}/tcp`];
+  if (!Array.isArray(bindings)) return null;
+  const candidates = bindings.flatMap((binding) => {
+    const port = parsePort(binding.HostPort);
+    const host = loopbackForBinding(binding.HostIp);
+    return port && host ? [{ host, port }] : [];
+  });
+  return (
+    candidates.find((candidate) => candidate.host === "127.0.0.1") ??
+    candidates[0] ??
+    null
+  );
+}
+
+function loopbackForBinding(value: unknown): string | null {
+  if (value === "127.0.0.1" || value === "0.0.0.0" || value === "") {
+    return "127.0.0.1";
+  }
+  if (value === "::1" || value === "::") return "::1";
+  return null;
+}
+
+function parsePort(value: unknown): number | null {
+  if (typeof value !== "string" || !/^\d{1,5}$/.test(value)) return null;
+  const port = Number(value);
+  return Number.isInteger(port) && port >= 1 && port <= 65_535 ? port : null;
+}
+
+function firstContainerAddress(
+  value: DockerContainerInspection,
+): { network: string; ip: string } | null {
+  const networks = value.NetworkSettings?.Networks;
+  if (!networks || typeof networks !== "object") return null;
+  for (const [name, network] of Object.entries(networks)) {
+    const address = network?.IPAddress;
+    if (typeof address === "string" && isIP(address) !== 0) {
+      return { network: name, ip: address };
+    }
+  }
+  return null;
+}
+
+function exactNetworkAddress(
+  value: DockerContainerInspection,
+  network: string,
+): string | null {
+  const address = value.NetworkSettings?.Networks?.[network]?.IPAddress;
+  return typeof address === "string" && isIP(address) !== 0 ? address : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.13",
+  "version": "0.9.42",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/_common.sh

@@ -36,7 +36,14 @@ UAI_LOG_DIR="${UAI_LOG_DIR:-$UAI_DATA_DIR/logs}"
 mkdir -p "$UAI_LOG_DIR"
 
 # Optional dependencies — fail fast with a structured error if missing.
-for bin in sqlite3 jq docker git; do
+# docker is only a dependency of the docker runtime mode: the Apple runtime
+# path must work on a Docker-free Mac (ADR-106), and its own CLI is validated
+# by validate_task_runtime_selection instead.
+agent_required_bins="sqlite3 jq git"
+if [ "${UAI_TASK_RUNTIME:-docker}" != "apple-container" ]; then
+  agent_required_bins="$agent_required_bins docker"
+fi
+for bin in $agent_required_bins; do
   if ! command -v "$bin" >/dev/null 2>&1; then
     printf '{"ok":false,"error":{"code":"MISSING_DEPENDENCY","message":"%s not found on PATH"}}\n' "$bin" >&2
     exit 127
@@ -72,7 +79,7 @@ emit_ok() {
 # logs an `error` event, prints structured JSON to stderr, and exits 1.
 emit_err() {
   local code="$1" msg="$2" step="${3:-${UAI_CURRENT_STEP:-}}"
-  _uai_mark_error "$code" "$step"
+  _uai_record_failure "$code" "$step"
   local json
   if [ -n "$step" ]; then
     json=$(jq -nc --arg c "$code" --arg m "$msg" --arg s "$step" \
@@ -85,6 +92,42 @@ emit_err() {
   exit 1
 }
 
+# Docker can disappear after the TypeScript admission check but before a
+# minutes-long compose/init command finishes. These codes describe steps whose
+# failure may be a daemon outage. Keep the command snapshot retryable here; the
+# host process re-probes `docker info` and records a terminal error only when
+# the daemon is positively reachable and the operation itself really failed.
+_uai_is_runtime_sensitive_error() {
+  case "$1" in
+    STANDARD_IMAGE_MISSING|COMPOSE_UP_FAILED|COMPOSE_DOWN_FAILED|CONTAINER_INIT_FAILED|DOCKER_PS_FAILED)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+_uai_mark_retryable() {
+  if [ -n "${UAI_TASK_ID:-}" ] && [ -n "${UAI_DB_PATH:-}" ]; then
+    local restore=""
+    if [ -n "${UAI_RETRY_STATUS:-}" ]; then
+      restore=", status='$(sql_escape "$UAI_RETRY_STATUS")'"
+    fi
+    sqlite_exec "UPDATE uai_tasks SET locked_at=NULL${restore}, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$UAI_TASK_ID")'" 2>/dev/null || true
+  fi
+  UAI_LOCK_HELD=""
+}
+
+_uai_record_failure() {
+  local code="$1" step="$2"
+  if _uai_is_runtime_sensitive_error "$code"; then
+    _uai_mark_retryable
+  else
+    _uai_mark_error "$code" "$step"
+  fi
+}
+
 # _uai_mark_error <code> <step>  — best-effort persist of status=error.
 # Shared between emit_err (explicit) and the ERR trap (set -e).
 _uai_mark_error() {
@@ -204,6 +247,7 @@ UAI_CURRENT_STEP=""
 UAI_ERROR_CODE="UNKNOWN"
 UAI_TASK_ID=""
 UAI_LOCK_HELD=""
+UAI_RETRY_STATUS=""
 UAI_PROJECT_LOCK_PATH=""
 UAI_PROJECT_LOCK_TOKEN=""
 
@@ -282,7 +326,7 @@ _uai_on_err() {
   local code="$UAI_ERROR_CODE"
   local stepname="$UAI_CURRENT_STEP"
 
-  _uai_mark_error "$code" "$stepname"
+  _uai_record_failure "$code" "$stepname"
 
   local out
   out=$(jq -nc --arg c "$code" --arg m "agent step failed" --arg s "$stepname" --argjson rc "$rc" \
@@ -310,6 +354,82 @@ compose_project_for_task()    { printf 'task-%s' "$(_uai_lower "$1")"; }
 # ever do scale, swap to discovering the container name via the
 # `com.docker.compose.project` + `com.docker.compose.service` labels.
 app_container_for_task()      { printf 'task-%s-app-1' "$(_uai_lower "$1")"; }
+# ADR-106: the Apple runtime has no Compose, so its app container drops the
+# replica suffix. Must match appleTaskContainerName in
+# lib/task-environment/apple-container.ts.
+apple_app_container_for_task() { printf 'task-%s-app' "$(_uai_lower "$1")"; }
+
+# -----------------------------------------------------------------------------
+# ADR-106 container runtime selection. The host publishes the selected backend
+# in UAI_TASK_RUNTIME (+ UAI_CONTAINER_CLI for the bundled Apple toolchain);
+# `docker` keeps every historical path byte-for-byte.
+# -----------------------------------------------------------------------------
+TASK_RUNTIME_MODE="${UAI_TASK_RUNTIME:-docker}"
+CONTAINER_CLI="${UAI_CONTAINER_CLI:-}"
+
+validate_task_runtime_selection() {
+  case "$TASK_RUNTIME_MODE" in
+    docker|apple-container) ;;
+    *)
+      emit_err "BAD_ARGS" \
+        "unsupported UAI_TASK_RUNTIME '$TASK_RUNTIME_MODE'" \
+        "select container runtime"
+      ;;
+  esac
+  if [ "$TASK_RUNTIME_MODE" = "apple-container" ]; then
+    case "$CONTAINER_CLI" in
+      /*) ;;
+      *)
+        emit_err "BAD_ARGS" \
+          "UAI_CONTAINER_CLI must be an absolute path to the bundled container CLI" \
+          "select container runtime"
+        ;;
+    esac
+    if [ -L "$CONTAINER_CLI" ] || [ ! -f "$CONTAINER_CLI" ] \
+       || [ ! -x "$CONTAINER_CLI" ]; then
+      emit_err "BAD_ARGS" \
+        "the bundled container CLI at $CONTAINER_CLI is missing or not executable" \
+        "select container runtime"
+    fi
+  fi
+}
+
+# Single dispatcher for the verbs whose flags are identical across Docker and
+# the Apple CLI (exec/cp/stop/inspect/image inspect/volume create). Verbs that
+# differ (compose, run, build, port) branch explicitly at their call sites.
+crt() {
+  if [ "$TASK_RUNTIME_MODE" = "apple-container" ]; then
+    "$CONTAINER_CLI" "$@"
+  else
+    docker "$@"
+  fi
+}
+
+# Absence proof for the Apple runtime. The CLI exits nonzero for BOTH a
+# missing container and a broken apiserver; only the not-found error that
+# names this exact container proves absence. Everything else proves nothing
+# and must never authorize destructive work.
+apple_container_proven_absent() {
+  apple_absent_name="$1"
+  # One CLI response supplies the whole proof: nonzero exit, empty stdout,
+  # and the complete not-found error line naming this exact container (never
+  # a substring — a not-found answer for "$name-shadow" must not prove the
+  # absence of "$name"). Two separate invocations could each satisfy half
+  # while no single response satisfies both.
+  apple_absent_dir=$(mktemp -d "${TMPDIR:-/tmp}/uai-absent.XXXXXX") \
+    || return 1
+  apple_absent_rc=0
+  "$CONTAINER_CLI" inspect "$apple_absent_name" \
+    >"$apple_absent_dir/out" 2>"$apple_absent_dir/err" \
+    || apple_absent_rc=$?
+  apple_absent_proven=1
+  [ "$apple_absent_rc" -ne 0 ] || apple_absent_proven=0
+  [ ! -s "$apple_absent_dir/out" ] || apple_absent_proven=0
+  grep -Fqx "Error: container not found: $apple_absent_name" \
+    "$apple_absent_dir/err" 2>/dev/null || apple_absent_proven=0
+  rm -rf "$apple_absent_dir"
+  [ "$apple_absent_proven" -eq 1 ]
+}
 
 # Canonicalise every GitHub URL shape to credential-free HTTPS. task-up selects
 # the credential per task: the creator's connected GitHub token is primary;