@runuai/host 0.9.68 → 0.9.70

package/lib/env-schema.ts

@@ -0,0 +1,101 @@
+/**
+ * ADR-122 phase 1: a minimal, OWNED parser for the env-spec subset Uai
+ * reads — key names and the @required / @sensitive / @type decorators from
+ * comment lines above each declaration in a committed `.env.schema`.
+ *
+ * Deliberately dependency-free: this phase must stand alone even if the
+ * upstream tooling vanishes (the graduated-adoption ladder in ADR-122).
+ * Unknown decorators are preserved verbatim but unused; values in the
+ * schema file are IGNORED — a schema declares, it never supplies.
+ *
+ * First consumer: the post-task-up validation note. A project that
+ * declares `@required DATABASE_URL` with no value stored on this host gets
+ * one visible system note instead of a blank 500 hours later (the
+ * 2026-08-25 incident this phase exists to retire).
+ */
+
+export interface EnvSchemaEntry {
+  name: string;
+  required: boolean;
+  sensitive: boolean;
+  type?: string;
+  /** Decorators Uai does not interpret, kept for diagnostics. */
+  otherDecorators: string[];
+}
+
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+const DECORATOR = /@([A-Za-z][A-Za-z0-9]*)(?:=((?:[^\s(]+)?(?:\([^)]*\))?))?/g;
+
+export function parseEnvSchema(content: string): EnvSchemaEntry[] {
+  const entries: EnvSchemaEntry[] = [];
+  let pending: {
+    required: boolean;
+    sensitive: boolean;
+    type?: string;
+    other: string[];
+  } = { required: false, sensitive: false, other: [] };
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("#")) {
+      for (const match of line.matchAll(DECORATOR)) {
+        const name = match[1]!;
+        const value = match[2];
+        if (name === "required") pending.required = true;
+        else if (name === "sensitive") pending.sensitive = true;
+        else if (name === "type" && value) pending.type = value;
+        else pending.other.push(value ? `${name}=${value}` : name);
+      }
+      continue;
+    }
+    if (line === "") {
+      // A blank line ends a decorator block that never reached a key —
+      // env-spec decorators attach to the declaration directly below them.
+      pending = { required: false, sensitive: false, other: [] };
+      continue;
+    }
+    const key = KEY_LINE.exec(line);
+    if (key) {
+      entries.push({
+        name: key[1]!,
+        required: pending.required,
+        sensitive: pending.sensitive,
+        ...(pending.type !== undefined ? { type: pending.type } : {}),
+        otherDecorators: pending.other,
+      });
+    }
+    pending = { required: false, sensitive: false, other: [] };
+  }
+  return entries;
+}
+
+/** Required keys the provided value set does not cover. Presence is a
+ * KEY-level fact — an empty string is still a provided value; deciding
+ * emptiness policy belongs to later phases, not this one. */
+export function missingRequiredKeys(
+  entries: EnvSchemaEntry[],
+  providedKeys: ReadonlySet<string>,
+): string[] {
+  return entries
+    .filter((entry) => entry.required && !providedKeys.has(entry.name))
+    .map((entry) => entry.name);
+}
+
+/** Compose the one visible note for a task whose projects declare required
+ * keys this host has no values for. Null when everything is satisfied. */
+export function envSchemaNote(
+  perProject: Array<{ slug: string; missing: string[] }>,
+): string | null {
+  const affected = perProject.filter((project) => project.missing.length > 0);
+  if (affected.length === 0) return null;
+  const lines = affected.map(
+    (project) =>
+      `${project.slug}: ${project.missing.join(", ")}`,
+  );
+  return (
+    `This task's project${affected.length > 1 ? "s" : ""} declare required ` +
+    `env keys with no value set on this host — ` +
+    lines.join("; ") +
+    `. The app may fail until they are set on the project page; ` +
+    `Resume the task after setting them.`
+  );
+}

package/lib/machine-exec.ts

@@ -0,0 +1,219 @@
+/**
+ * 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;
+}
+
+/** POSIX single-quote escaping. The ONLY safe way to carry an arbitrary
+ * argv element through the remote login shell ssh interposes: everything
+ * between single quotes is literal, and an embedded quote becomes '\''. */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Build the remote command for a TaskEnvironment-style request. SSH has no
+ * --workdir/--env/--user flags — cwd and env must be materialized INTO the
+ * remote command, each element quoted, and the user rides the ssh login
+ * instead (`-l`). Env values therefore appear in the machine-side process
+ * table; the machine is a single-task trust domain, and hardening to sshd
+ * SetEnv acceptlists is recorded ADR-121 follow-up work, not silently
+ * skipped.
+ */
+export function buildRemoteCommand(request: {
+  argv: readonly string[];
+  cwd?: string;
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  detached?: boolean;
+}): string {
+  const parts: string[] = [];
+  if (request.cwd) {
+    parts.push(`cd ${shellQuote(request.cwd)} &&`);
+  }
+  const env: string[] = [];
+  for (const name of request.inheritEnv ?? []) {
+    const value = process.env[name];
+    if (value !== undefined) env.push(`${name}=${value}`);
+  }
+  for (const [name, value] of Object.entries(request.env ?? {}).sort(
+    ([left], [right]) => left.localeCompare(right),
+  )) {
+    env.push(`${name}=${value}`);
+  }
+  const envPrefix =
+    env.length > 0 ? `env ${env.map(shellQuote).join(" ")} ` : "";
+  const command = request.argv.map(shellQuote).join(" ");
+  if (request.detached) {
+    // Detached durable sessions manage their own transcript IO (runner.mjs);
+    // the launch just needs the process to survive this ssh connection:
+    // setsid detaches the controlling terminal, streams are severed, and the
+    // remote shell exits immediately with the launch verdict.
+    parts.push(`${envPrefix}setsid ${command} </dev/null >/dev/null 2>&1 &`);
+    parts.push("exit 0");
+    return parts.join(" ");
+  }
+  parts.push(`exec ${envPrefix}${command}`);
+  return parts.join(" ");
+}
+
+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);
+}
+
+/**
+ * Full ssh argv for a TaskEnvironment-style request: base transport options,
+ * the request's user as the ssh login, and the quoted remote command as the
+ * single trailing argument. Shared by captured, streaming, and detached
+ * paths so quoting can never diverge between them.
+ */
+export function machineEnvironmentSshArgs(
+  target: Omit<MachineExecTarget, "user">,
+  request: {
+    argv: readonly string[];
+    cwd?: string;
+    user?: string;
+    inheritEnv?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+  },
+  mode: "interactive" | "detached",
+): string[] {
+  return [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-o",
+    "ConnectTimeout=10",
+    "-i",
+    target.keyPath,
+    "-p",
+    String(target.port ?? 22),
+    "-l",
+    request.user ?? "node",
+    target.address,
+    "--",
+    buildRemoteCommand({ ...request, detached: mode === "detached" }),
+  ];
+}
+
+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-keys.ts

@@ -0,0 +1,65 @@
+/**
+ * ADR-121: per-machine SSH identity. Minted host-side at provision, the
+ * public half rides the machine spec (user-data / entrypoint env), the
+ * private half lives in the task's control tree — task lifetime, deleted
+ * with the task dir, never shared between tasks. `ssh-keygen` is used
+ * rather than a JS implementation: the host already shells out for every
+ * other crypto-bearing operation, and OpenSSH's own keygen is the one
+ * implementation `ssh` is guaranteed to agree with.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface MachineKeyPair {
+  privateKeyPath: string;
+  publicKey: string;
+}
+
+export function machineKeyDir(taskControlDir: string): string {
+  return resolve(taskControlDir, "machine");
+}
+
+/**
+ * Mint (or reuse) the task's machine keypair. Reuse is deliberate: a
+ * re-provision after a crash must produce the same identity the persisted
+ * locator's machine may already authorize.
+ */
+export async function ensureMachineKeyPair(
+  taskControlDir: string,
+): Promise<MachineKeyPair> {
+  const dir = machineKeyDir(taskControlDir);
+  const privateKeyPath = resolve(dir, "id_ed25519");
+  const publicKeyPath = `${privateKeyPath}.pub`;
+  if (existsSync(privateKeyPath) && existsSync(publicKeyPath)) {
+    return {
+      privateKeyPath,
+      publicKey: readFileSync(publicKeyPath, "utf8").trim(),
+    };
+  }
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  rmSync(privateKeyPath, { force: true });
+  rmSync(publicKeyPath, { force: true });
+  await new Promise<void>((resolveKeygen, reject) => {
+    const child = spawn(
+      "ssh-keygen",
+      ["-t", "ed25519", "-N", "", "-C", "uai-machine", "-f", privateKeyPath],
+      { stdio: ["ignore", "ignore", "pipe"] },
+    );
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.once("error", (error) => reject(error));
+    child.once("close", (code) => {
+      if (code === 0) resolveKeygen();
+      else reject(new Error(`ssh-keygen failed (${code}): ${stderr.trim()}`));
+    });
+  });
+  return {
+    privateKeyPath,
+    publicKey: readFileSync(publicKeyPath, "utf8").trim(),
+  };
+}