@runuai/host 0.9.68 → 0.9.69

package/lib/machine-exec.ts

@@ -0,0 +1,130 @@
+/**
+ * ADR-121: command transport to a task machine — SSH within the private
+ * network (VPC for cloud backends, the daemon bridge on the Linux guinea
+ * pig). The recommended-and-recorded pick over SSM: it matches the exec
+ * plumbing every consumer already speaks, and nothing in it is
+ * cloud-specific.
+ *
+ * Mirrors `dockerCli`'s contract exactly — never rejects, resolves
+ * `{status, stdout, stderr}` with `status: null` on spawn error/timeout —
+ * so machine-backed call sites read like container-backed ones.
+ *
+ * Host-key policy is `accept-new`, the same posture task containers get for
+ * git (`core.sshCommand` in git-identity.ts): machines are freshly minted
+ * by US moments before first contact, so TOFU is sound — but a CHANGED key
+ * for a known address must fail loudly, never be silently re-accepted.
+ * BatchMode forbids prompts: an unreachable or unauthenticated machine is
+ * an error result, not a hang.
+ */
+
+import { spawn } from "node:child_process";
+
+import type { DockerResult } from "./docker-exec";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** SIGKILLed ssh normally closes at once; an unreapable child must not hold
+ * the promise open past the caller's own deadline. */
+const KILL_SETTLE_MS = 2_000;
+
+export interface MachineExecTarget {
+  /** Reachable address from MachineInfo — VPC-private or bridge IP. */
+  address: string;
+  /** Path to the private key the machine's image authorizes. */
+  keyPath: string;
+  user?: string;
+  port?: number;
+}
+
+export interface MachineExecOptions {
+  input?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+}
+
+export function machineSshArgs(
+  target: MachineExecTarget,
+  argv: string[],
+): string[] {
+  return [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-o",
+    "ConnectTimeout=10",
+    "-i",
+    target.keyPath,
+    "-p",
+    String(target.port ?? 22),
+    `${target.user ?? "node"}@${target.address}`,
+    "--",
+    ...argv,
+  ];
+}
+
+export function machineExec(
+  target: MachineExecTarget,
+  argv: string[],
+  opts: MachineExecOptions = {},
+): Promise<DockerResult> {
+  return runSsh(machineSshArgs(target, argv), opts);
+}
+
+function runSsh(
+  args: string[],
+  opts: MachineExecOptions,
+): Promise<DockerResult> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  return new Promise<DockerResult>((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let killedForCause = false;
+    const child = spawn("ssh", args, { stdio: ["pipe", "pipe", "pipe"] });
+    const settle = (result: DockerResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const killAndSettle = (): void => {
+      killedForCause = true;
+      child.kill("SIGKILL");
+      setTimeout(() => {
+        settle({ status: null, stdout, stderr, outputTruncated: true });
+      }, KILL_SETTLE_MS).unref?.();
+    };
+    const timer = setTimeout(killAndSettle, timeoutMs);
+    timer.unref?.();
+    const capOutput = (): void => {
+      if (stdout.length + stderr.length > maxOutputBytes) killAndSettle();
+    };
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+      capOutput();
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+      capOutput();
+    });
+    child.once("error", () => {
+      settle({ status: null, stdout, stderr });
+    });
+    child.once("close", (code) => {
+      settle({
+        status: killedForCause ? null : code,
+        stdout,
+        stderr,
+        ...(killedForCause ? { outputTruncated: true } : {}),
+      });
+    });
+    if (opts.input !== undefined) {
+      child.stdin.write(opts.input);
+    }
+    child.stdin.end();
+  });
+}

package/lib/machine-provider-local.ts

@@ -0,0 +1,283 @@
+/**
+ * ADR-121: the `local` MachineProvider — task "machines" as containers on
+ * the local Docker daemon, so the whole machine-backed path (launch, in-env
+ * clone, SSH exec, tunnels, recovery-by-describe) is exercised on the
+ * uai-linux guinea pig VM with zero cloud spend.
+ *
+ * Machines are containers named `uai-machine-<taskId>` carrying the label
+ * `com.uai.machine=<taskId>`. The label is deliberately NOT `com.uai.task`:
+ * task-app containers own that label and every existing sweep/proof keys on
+ * it — a machine must never be mistaken for an app container by GC that
+ * predates machines.
+ *
+ * Absence grammar: `docker inspect` answers a missing object with exit 1,
+ * empty stdout, and an "Error: No such object: <id>" line naming the EXACT
+ * id. Only that whole answer proves absence (a not-found for "<id>-shadow"
+ * proves nothing about "<id>"); anything else is `unknown`.
+ */
+
+import { dockerCli, type DockerResult } from "./docker-exec";
+import type {
+  MachineInfo,
+  MachineProvider,
+  MachineSpec,
+  MachineState,
+} from "./machine-provider";
+
+export const MACHINE_LABEL = "com.uai.machine";
+
+export function localMachineName(taskId: string): string {
+  return `uai-machine-${taskId.toLowerCase()}`;
+}
+
+type Runner = (args: string[]) => Promise<DockerResult>;
+
+const defaultRunner: Runner = (args) => dockerCli(args, { timeoutMs: 60_000 });
+
+function machineAbsent(id: string, res: DockerResult): boolean {
+  return (
+    typeof res.status === "number" &&
+    res.status !== 0 &&
+    res.stdout.trim() === "" &&
+    res.stderr
+      .split("\n")
+      .some((line) => line.trim() === `Error: No such object: ${id}`)
+  );
+}
+
+function stateFromDocker(status: unknown): MachineState {
+  switch (status) {
+    case "running":
+      return "running";
+    case "created":
+    case "restarting":
+      return "pending";
+    case "paused":
+    case "exited":
+    case "dead":
+      return "stopped";
+    default:
+      return "unknown";
+  }
+}
+
+interface InspectShape {
+  name: string;
+  taskLabel: string | null;
+  state: MachineState;
+  address: string | null;
+}
+
+/** Strict single-record parse. Exactly one record whose Name is the
+ * requested id — a confused or multi-record answer proves nothing and maps
+ * to null (the caller reports `unknown`). */
+function parseInspect(id: string, stdout: string): InspectShape | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed) || parsed.length !== 1) return null;
+  const record = parsed[0];
+  if (typeof record !== "object" || record === null) return null;
+  const rawName = (record as { Name?: unknown }).Name;
+  if (typeof rawName !== "string") return null;
+  const name = rawName.replace(/^\//, "");
+  if (name !== id) return null;
+  const stateObj = (record as { State?: { Status?: unknown } }).State;
+  const labels = (record as { Config?: { Labels?: unknown } }).Config?.Labels;
+  let taskLabel: string | null = null;
+  if (labels !== undefined && labels !== null) {
+    if (typeof labels !== "object" || Array.isArray(labels)) return null;
+    const value = (labels as Record<string, unknown>)[MACHINE_LABEL];
+    if (value !== undefined && typeof value !== "string") return null;
+    taskLabel = typeof value === "string" ? value : null;
+  }
+  const networks = (
+    record as {
+      NetworkSettings?: { Networks?: Record<string, { IPAddress?: unknown }> };
+    }
+  ).NetworkSettings?.Networks;
+  let address: string | null = null;
+  if (networks && typeof networks === "object") {
+    for (const net of Object.values(networks)) {
+      const ip = net?.IPAddress;
+      if (typeof ip === "string" && ip.length > 0) {
+        address = ip;
+        break;
+      }
+    }
+  }
+  return {
+    name,
+    taskLabel,
+    state: stateFromDocker(stateObj?.Status),
+    address,
+  };
+}
+
+function unknown(id: string, detail: string): MachineInfo {
+  return { id, taskLabel: null, state: "unknown", address: null, detail };
+}
+
+export function createLocalMachineProvider(
+  runner: Runner = defaultRunner,
+): MachineProvider {
+  async function describe(id: string): Promise<MachineInfo> {
+    const res = await runner(["inspect", id]);
+    if (res.status === 0) {
+      const record = parseInspect(id, res.stdout);
+      if (record === null) {
+        return unknown(id, "inspect answered with a confusing record");
+      }
+      return {
+        id,
+        taskLabel: record.taskLabel,
+        state: record.state,
+        address: record.state === "running" ? record.address : null,
+      };
+    }
+    if (machineAbsent(id, res)) {
+      return { id, taskLabel: null, state: "absent", address: null };
+    }
+    return unknown(
+      id,
+      res.stderr.trim() || `inspect exited ${res.status ?? "killed"}`,
+    );
+  }
+
+  return {
+    kind: "local",
+
+    async launch(spec: MachineSpec): Promise<MachineInfo> {
+      const name = localMachineName(spec.taskId);
+      const args = [
+        "run",
+        "-d",
+        "--name",
+        name,
+        "--label",
+        `${MACHINE_LABEL}=${spec.taskId}`,
+        "--cpus",
+        String(spec.cpus),
+        "--memory",
+        `${spec.memoryMiB}m`,
+        spec.image,
+        ...(spec.command ?? []),
+      ];
+      const res = await runner(args);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine launch failed for ${name}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+      const info = await describe(name);
+      if (info.state === "absent" || info.state === "unknown") {
+        throw new Error(
+          `machine ${name} launched but could not be described (${info.state})`,
+        );
+      }
+      return info;
+    },
+
+    async stop(id: string): Promise<void> {
+      const res = await runner(["stop", "--time", "10", id]);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine stop failed for ${id}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+    },
+
+    async start(id: string): Promise<MachineInfo> {
+      const res = await runner(["start", id]);
+      if (res.status !== 0) {
+        throw new Error(
+          `machine start failed for ${id}: ${
+            res.stderr.trim() || `exit ${res.status ?? "killed"}`
+          }`,
+        );
+      }
+      return describe(id);
+    },
+
+    async terminate(id: string): Promise<void> {
+      // Removal is allowed to fail (already gone, races) — absence is not.
+      await runner(["rm", "-f", id]);
+      const after = await describe(id);
+      if (after.state !== "absent") {
+        throw new Error(
+          `machine ${id} could not be proven absent after terminate (${after.state}${
+            after.detail ? `: ${after.detail}` : ""
+          })`,
+        );
+      }
+    },
+
+    describe,
+
+    async list(): Promise<MachineInfo[]> {
+      const ids = await runner([
+        "ps",
+        "-a",
+        "--filter",
+        `label=${MACHINE_LABEL}`,
+        "--format",
+        "{{.Names}}",
+      ]);
+      if (ids.status !== 0) {
+        throw new Error(
+          `machine listing failed: ${
+            ids.stderr.trim() || `exit ${ids.status ?? "killed"}`
+          }`,
+        );
+      }
+      const names = ids.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+      if (names.length === 0) return [];
+      const inspected = await runner(["inspect", ...names]);
+      if (inspected.status !== 0) {
+        throw new Error(
+          `machine inventory inspect failed: ${
+            inspected.stderr.trim() || `exit ${inspected.status ?? "killed"}`
+          }`,
+        );
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(inspected.stdout);
+      } catch {
+        throw new Error("machine inventory was unparseable");
+      }
+      if (!Array.isArray(parsed) || parsed.length !== names.length) {
+        throw new Error("machine inventory was unparseable");
+      }
+      const machines: MachineInfo[] = [];
+      for (let index = 0; index < names.length; index += 1) {
+        const record = parseInspect(
+          names[index]!,
+          JSON.stringify([parsed[index]]),
+        );
+        if (record === null) {
+          // A partially-readable inventory could hide exactly the labeled
+          // machine an orphan proof needs to see — no answer at all.
+          throw new Error("machine inventory was unparseable");
+        }
+        machines.push({
+          id: record.name,
+          taskLabel: record.taskLabel,
+          state: record.state,
+          address: record.state === "running" ? record.address : null,
+        });
+      }
+      return machines;
+    },
+  };
+}

package/lib/machine-provider.ts

@@ -0,0 +1,76 @@
+/**
+ * ADR-121: the per-task MACHINE lifecycle seam.
+ *
+ * A "machine" is the isolated computer a task runs on — an EC2 instance, a
+ * GCP instance, or (for the zero-cloud-spend guinea pig) an SSH-reachable
+ * container on the local daemon. The seam is deliberately small enough that
+ * nothing in it is EC2-specific: launch / stop / start / terminate /
+ * describe / list, with an ownership tag and a reachable address.
+ *
+ * State discipline (this repo's absence rule, applied to machines):
+ * - `absent` means PROVEN absent — the provider observed its backend's exact
+ *   not-found answer for this exact id. Only `absent` authorizes forgetting
+ *   a machine or deleting anything derived from it.
+ * - `unknown` means the query failed or answered confusingly. Unknown is
+ *   never absence; callers defer and retry.
+ * - `terminate` does not return until absence is proven; an unprovable
+ *   termination throws rather than reporting success.
+ */
+
+export type MachineState =
+  | "pending"
+  | "running"
+  | "stopped"
+  | "absent"
+  | "unknown";
+
+export interface MachineSpec {
+  /** Task ownership — recorded on the machine (tag/label) so recovery and
+   * orphan sweeps key on it, mirroring `com.uai.task` on containers. */
+  taskId: string;
+  /** Backend image reference: AMI id, GCP image, or container image. */
+  image: string;
+  cpus: number;
+  memoryMiB: number;
+  /** Optional long-running entrypoint override (the local backend's images
+   * must keep the machine alive themselves — typically sshd). */
+  command?: string[];
+}
+
+export interface MachineInfo {
+  /** Backend-native identifier: instance id or container id/name. */
+  id: string;
+  /** The recorded task ownership label, null when the machine carries none
+   * (a foreign machine occupying a reserved name is never ours to touch). */
+  taskLabel: string | null;
+  state: MachineState;
+  /** Address the orchestrator can dial for SSH/exec/tunnels, when running.
+   * Reachability is a deployment property: VPC-private IPs (cloud) and
+   * bridge IPs (local daemon on the SAME machine as the orchestrator) are
+   * reachable; container bridge IPs are NOT host-routable from macOS —
+   * the local backend is for the Linux guinea pig, not Mac hosts. */
+  address: string | null;
+  /** Present only alongside `unknown` — what the backend actually said. */
+  detail?: string;
+}
+
+export interface MachineProvider {
+  readonly kind: "local" | "aws" | "gcp";
+  /** Create and start a machine. Rejects on a name/identity conflict —
+   * adopting an existing machine is a caller decision, never implicit. */
+  launch(spec: MachineSpec): Promise<MachineInfo>;
+  /** Graceful stop (sleep-when-idle; cloud backends keep the disk). */
+  stop(id: string): Promise<void>;
+  /** Start a stopped machine and report its (possibly new) address. */
+  start(id: string): Promise<MachineInfo>;
+  /** Destroy the machine. Resolves only after absence is PROVEN. */
+  terminate(id: string): Promise<void>;
+  /** One machine's state. `absent` only on the backend's exact not-found
+   * answer for this exact id; anything else unprovable is `unknown`. */
+  describe(id: string): Promise<MachineInfo>;
+  /** Every machine carrying this provider's ownership labels — the orphan
+   * sweep's inventory. A partially-readable answer is no answer: malformed
+   * rows reject the whole listing (they could hide exactly the labeled
+   * machine a proof needs to see). */
+  list(): Promise<MachineInfo[]>;
+}

package/package.json

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