@runuai/host 0.9.13 → 0.9.42

package/src/runtime-bootstrap.ts

@@ -0,0 +1,165 @@
+/** ADR-106 boot wiring kept side-effect free and directly testable. */
+
+import {
+  appleContainerRuntimeBinding,
+  containerRuntimeMachineIdentity,
+  rejectContainerRuntimeSelection,
+  reprobeContainerRuntimeMachineIdentity,
+  setAppleContainerRuntime,
+  setAppleContainerSelectionGuard,
+  type AppleRuntimeBinding,
+} from "../lib/container-runtime";
+import {
+  resolveBundledRuntimeFromEnvironment,
+  type ResolvedBundledRuntime,
+} from "../lib/managed-runtime";
+import {
+  adoptLegacyTaskEnvironments,
+  hostTaskEnvironmentsAllowMachineSelection,
+  hostTaskEnvironmentsMatchMachine,
+  setAppleContainerBinding,
+  type HostMachineIdentity,
+  type LegacyTaskEnvironmentAdoptionVerdict,
+  type TaskEnvironmentBackendVerdict,
+} from "../lib/task-environment";
+
+export interface RuntimeBootstrapDeps {
+  readonly resolveRuntime?: () => Promise<ResolvedBundledRuntime | null>;
+  readonly registerRuntime?: (binding: AppleRuntimeBinding | null) => void;
+  readonly registerSelectionGuard?: (
+    guard: ((endpoint: string) => boolean | Promise<boolean>) | null,
+  ) => void;
+  readonly allowMachineSelection?: (machine: {
+    backend: "apple-container";
+    endpoint: string;
+  }) => TaskEnvironmentBackendVerdict;
+}
+
+/**
+ * Register the bundled Apple container toolchain from the active signed
+ * generation, if one exists (ADR-106). Registration is fail-closed: seams are
+ * cleared first so a thrown validation cannot leave a stale binding, and the
+ * selection guard keeps `auto` off the bundled runtime while durable task
+ * rows still belong to another backend. An unmanaged checkout, Linux archive,
+ * or rolling v1 generation registers nothing; there is deliberately no PATH
+ * or inferred-layout fallback.
+ */
+export async function configureBundledContainerRuntime(
+  deps: RuntimeBootstrapDeps = {},
+): Promise<ResolvedBundledRuntime | null> {
+  const registerRuntime = deps.registerRuntime ?? setAppleContainerRuntime;
+  const registerGuard =
+    deps.registerSelectionGuard ?? setAppleContainerSelectionGuard;
+  registerRuntime(null);
+  registerGuard(null);
+
+  const bundled = await (
+    deps.resolveRuntime ?? resolveBundledRuntimeFromEnvironment
+  )();
+  if (bundled === null) return null;
+
+  const allowSelection =
+    deps.allowMachineSelection ?? hostTaskEnvironmentsAllowMachineSelection;
+  registerGuard(
+    (endpoint) =>
+      allowSelection({ backend: "apple-container", endpoint }).ok,
+  );
+  registerRuntime({
+    containerCliPath: bundled.containerCliPath,
+    kernelPath: bundled.kernelPath,
+  });
+  return bundled;
+}
+
+export interface RuntimeCompatibilityDeps {
+  readonly machineIdentity?: () => HostMachineIdentity | null;
+  readonly matchMachine?: (
+    machine: HostMachineIdentity,
+  ) => TaskEnvironmentBackendVerdict;
+  readonly adoptLegacy?: (
+    machine: HostMachineIdentity,
+  ) => Promise<LegacyTaskEnvironmentAdoptionVerdict>;
+  readonly reprobeRuntime?: () => Promise<HostMachineIdentity | null>;
+  readonly rejectSelection?: (message: string, action?: string) => void;
+}
+
+/**
+ * Final database-backed fence before maintenance/recovery touches a selected
+ * daemon. A missing exact endpoint and every malformed/newer/mismatched task
+ * locator are quarantines, never retry hints against the current machine.
+ */
+export async function selectedRuntimeMatchesPersistedTaskEnvironments(
+  deps: RuntimeCompatibilityDeps = {},
+): Promise<boolean> {
+  const reject = deps.rejectSelection ?? rejectContainerRuntimeSelection;
+  const machine = (
+    deps.machineIdentity ?? containerRuntimeMachineIdentity
+  )();
+  if (machine === null) {
+    reject(
+      "The selected container runtime has no durable local machine identity.",
+    );
+    return false;
+  }
+  const reprobe =
+    deps.reprobeRuntime ?? reprobeContainerRuntimeMachineIdentity;
+  const liveMachine = await reprobe();
+  if (
+    liveMachine === null ||
+    liveMachine.backend !== machine.backend ||
+    liveMachine.endpoint !== machine.endpoint ||
+    liveMachine.engineId !== machine.engineId
+  ) {
+    reject(
+      "The selected container runtime daemon identity changed during validation.",
+    );
+    return false;
+  }
+  // Legacy compose rows can only ever be adopted by a Docker daemon; any
+  // other active backend makes the candidate check inside adoption fail
+  // closed with its repair guidance, so the machine is narrowed lazily.
+  // Bind (or unbind) the Apple provider to the proven identity before any
+  // maintenance can reconstruct a task environment. The binding carries the
+  // exact machine the fence just re-probed, so provider reconstruction and
+  // this admission decision can never disagree about identity.
+  if (deps.machineIdentity === undefined) {
+    const binding = appleContainerRuntimeBinding();
+    if (machine.backend === "apple-container" && binding !== null) {
+      const appleMachine = {
+        backend: "apple-container" as const,
+        endpoint: machine.endpoint,
+        engineId: machine.engineId,
+      };
+      setAppleContainerBinding({
+        containerCliPath: () => binding.containerCliPath,
+        machineIdentity: () => appleMachine,
+      });
+    } else {
+      setAppleContainerBinding(null);
+    }
+  }
+
+  const adoption = await (
+    deps.adoptLegacy ??
+    ((selected: HostMachineIdentity) =>
+      adoptLegacyTaskEnvironments(selected, {
+        reprobeMachine: reprobe,
+      }))
+  )(machine);
+  if (!adoption.ok) {
+    reject(
+      "Uai Host could not safely adopt persisted legacy task resources" +
+        (adoption.detail ? `: ${adoption.detail}` : "."),
+    );
+    return false;
+  }
+  const verdict = (
+    deps.matchMachine ?? hostTaskEnvironmentsMatchMachine
+  )(machine);
+  if (verdict.ok) return true;
+  reject(
+    "The selected container runtime does not match persisted task environments" +
+      (verdict.detail ? `: ${verdict.detail}` : "."),
+  );
+  return false;
+}

package/src/ui/server.ts

@@ -29,6 +29,7 @@ import { getOrchestrator } from "../../lib/orchestrator";
 import { parsePreviewPortRuntimes } from "../../lib/preview-ports";
 import { getCloudState } from "../../lib/cloud-state";
 import { dockerCli } from "../../lib/docker-exec";
+import type { ContainerRuntimeState } from "../../lib/container-runtime";
 import {
   connectEngine,
   disconnectEngine,
@@ -47,6 +48,7 @@ import {
 import { ensureStandardImage } from "../../lib/standard-image";
 import {
   CloudResponse,
+  ContainerRuntimeResponse,
   EngineOpResponse,
   EnginesResponse,
   EventsResponse,
@@ -58,6 +60,7 @@ import {
 
 const HOST = "127.0.0.1";
 const MAX_PORT_ATTEMPTS = 10;
+export const RUNTIME_RECHECK_CONTROL_HEADER = "runtime-recheck-v1";
 
 export interface UiServerOptions {
   /** Host runtime DB (read-only here). */
@@ -93,6 +96,12 @@ export interface UiServerOptions {
    * endpoint never spawns a login shell (which is bounded, but real, I/O).
    */
   engineSeams?: Partial<EngineSeams>;
+  /** ADR-101 local control/read surface. Optional for embedding/tests. */
+  runtimeState?: () => ContainerRuntimeState;
+  recheckRuntime?: () => Promise<ContainerRuntimeState>;
+  /** False while the selected backend is unavailable or still recovering.
+   * Credential edits remain usable, but must not kick Docker maintenance. */
+  containersOperational?: () => boolean;
 }
 
 export interface UiServerHandle {
@@ -179,6 +188,26 @@ async function handle(
           return await handleEngineAccountRemove(req, res, opts);
         case "/api/tasks/stop":
           return await handleTaskStop(req, res, opts);
+        case "/api/runtime/recheck": {
+          // Loopback is not a browser CSRF boundary. Requiring a non-simple
+          // header is deliberate even though its value is not a secret:
+          // hostile pages cannot attach it without a CORS preflight, and this
+          // server grants no CORS permission. The local CLI is the caller.
+          if (
+            req.headers["x-uai-local-control"] !==
+            RUNTIME_RECHECK_CONTROL_HEADER
+          ) {
+            return sendError(res, 403, "local control header required");
+          }
+          if (!opts.recheckRuntime) {
+            return sendError(res, 501, "runtime recheck is unavailable");
+          }
+          return sendJson(
+            res,
+            ContainerRuntimeResponse,
+            await opts.recheckRuntime(),
+          );
+        }
       }
       return sendError(res, 404, `no such endpoint: ${path}`);
     }
@@ -196,6 +225,7 @@ async function handle(
           hostName: hostname(),
           hostId: opts.hostId,
           agentMode: agentMode(),
+          containerRuntime: opts.runtimeState?.(),
         });
       case "/api/cloud":
         return sendJson(res, CloudResponse, getCloudState());
@@ -320,14 +350,16 @@ async function handleEngineConnect(
     // Re-advertise so the cloud picker offers the engine; rebuild the image so
     // an optional engine's CLI (kimi/grok/cursor) is installed. Best-effort.
     opts.readvertise?.();
-    void ensureStandardImage();
-    // A re-login only reaches a RUNNING task once its agents re-spawn — the
-    // credential is injected at spawn (Claude's token via `docker exec -e`).
-    // Refresh running agents of this kind so a reconnect self-heals tasks stuck
-    // on a revoked/expired token, instead of needing a manual Stop/Resume.
-    void getOrchestrator()
-      .refreshEngineAccountAgents(kind)
-      .catch(() => {});
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+      // A re-login only reaches a RUNNING task once its agents re-spawn — the
+      // credential is injected at spawn (Claude's token via `docker exec -e`).
+      // Refresh running agents of this kind so a reconnect self-heals tasks
+      // stuck on a revoked/expired token, instead of needing Stop/Resume.
+      void getOrchestrator()
+        .refreshEngineAccountAgents(kind)
+        .catch(() => {});
+    }
   }
   emit({ done: true, ok: result.ok, message: result.message });
   res.end();
@@ -370,7 +402,9 @@ async function handleEngineAccountAdd(
   const result = addEngineAccount(kind, label, { apiKey, token });
   if (result.ok) {
     opts.readvertise?.();
-    void ensureStandardImage();
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+    }
   }
   return sendJson(res, EngineOpResponse, {
     ok: result.ok,
@@ -424,7 +458,9 @@ async function handleEngineAccountConnect(
   }
   if (result.ok) {
     opts.readvertise?.();
-    void ensureStandardImage();
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+    }
   }
   emit({ done: true, ok: result.ok, message: result.message });
   res.end();

package/src/ui/types.ts

@@ -8,6 +8,42 @@
 
 import { z } from "zod";
 
+const RuntimePreference = z.enum(["auto", "docker", "apple-container"]);
+export const ContainerRuntimeResponse = z.union([
+  z
+    .object({
+      status: z.literal("checking"),
+      preference: RuntimePreference,
+      detail: z.string().trim().min(1).max(300).optional(),
+    })
+    .strict(),
+  z.union([
+    z
+      .object({
+        status: z.literal("ready"),
+        preference: z.enum(["auto", "docker"]),
+        provider: z.literal("docker"),
+      })
+      .strict(),
+    z
+      .object({
+        status: z.literal("ready"),
+        preference: z.enum(["auto", "apple-container"]),
+        provider: z.literal("apple-container"),
+      })
+      .strict(),
+  ]),
+  z
+    .object({
+      status: z.literal("no-runtime"),
+      preference: RuntimePreference,
+      message: z.string().trim().min(1).max(1_000),
+      action: z.string().trim().min(1).max(200),
+    })
+    .strict(),
+]);
+export type ContainerRuntimeResponse = z.infer<typeof ContainerRuntimeResponse>;
+
 // GET /api/status — process + config facts.
 export const StatusResponse = z.object({
   pid: z.number().int(),
@@ -22,6 +58,7 @@ export const StatusResponse = z.object({
   // such field — `npm i -g` swaps the CLI before `uai-host restart` swaps the
   // service, so that window is normal, not exotic.
   agentMode: z.enum(["real", "mock"]).optional(),
+  containerRuntime: ContainerRuntimeResponse.optional(),
 });
 export type StatusResponse = z.infer<typeof StatusResponse>;