@runuai/host 0.9.14 → 0.9.42

package/lib/task-environment/index.ts

@@ -0,0 +1,364 @@
+import {
+  agent,
+  type TaskDownResult,
+  type TaskLaunchInput,
+  type TaskUpCredentials,
+  type TaskUpResult,
+} from "../agent";
+import { pinnedContainerRuntimeMachineIdentity } from "../container-runtime";
+import { getDb, schema, type HostTask } from "../db";
+import { taskDir } from "../env";
+import {
+  APPLE_TASK_ENVIRONMENT_PROVIDER,
+  type AppleTaskEnvironmentRecoveryDriver,
+  createAppleContainerTaskEnvironmentProvider,
+  parseAppleTaskEnvironmentLocator,
+  type AppleMachineIdentity,
+} from "./apple-container";
+import {
+  createDockerTaskEnvironmentProvider,
+  DOCKER_TASK_ENVIRONMENT_PROVIDER,
+  parseDockerTaskEnvironmentLocator,
+  type DockerTaskEnvironmentRecoveryDriver,
+  type DockerMachineIdentity,
+} from "./docker";
+import { TaskEnvironmentRegistry } from "./registry";
+import {
+  parseTaskEnvironmentLocator,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentProvisioned,
+} from "./types";
+
+export {
+  adoptLegacyTaskEnvironments,
+  type LegacyTaskEnvironmentAdoptionDeps,
+  type LegacyTaskEnvironmentAdoptionVerdict,
+} from "./legacy-adoption";
+
+const registry = new TaskEnvironmentRegistry<
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult,
+  TaskDownResult
+>();
+
+let dockerRecoveryDriver: DockerTaskEnvironmentRecoveryDriver | null = null;
+
+const dockerProvider = createDockerTaskEnvironmentProvider({
+  machineIdentity: requireDockerMachineIdentity,
+  taskUp: agent.taskUp,
+  taskEnvironmentDown: agent.taskEnvironmentDown,
+  recoveryDriver: () => dockerRecoveryDriver,
+});
+
+registry.register(dockerProvider);
+
+/** Machine identity union across every registered backend. */
+export type HostMachineIdentity = DockerMachineIdentity | AppleMachineIdentity;
+
+export interface AppleContainerBinding {
+  /** Absolute path of the authenticated bundled `container` CLI. */
+  containerCliPath: () => string;
+  machineIdentity: () => AppleMachineIdentity;
+}
+
+let appleBinding: AppleContainerBinding | null = null;
+
+/** Bind the Apple container provider to the authenticated bundle + minted
+ * installation identity. Selection wiring installs this exactly when the
+ * apple-container backend is active; a null binding keeps reconstruction of
+ * apple locators fail-closed. */
+export function setAppleContainerBinding(
+  binding: AppleContainerBinding | null,
+): void {
+  appleBinding = binding;
+}
+
+function requireAppleBinding(): AppleContainerBinding {
+  if (!appleBinding) {
+    throw new Error("the apple-container runtime is not active on this host");
+  }
+  return appleBinding;
+}
+
+let appleRecoveryDriver: AppleTaskEnvironmentRecoveryDriver | null = null;
+
+/** Bind the Apple provider's recovery implementation (orchestrator-owned),
+ * mirroring the Docker seam so HMR reloads cannot strand stale handles. */
+export function setAppleTaskEnvironmentRecoveryDriver(
+  driver: AppleTaskEnvironmentRecoveryDriver,
+): void {
+  appleRecoveryDriver = driver;
+}
+
+const appleProvider = createAppleContainerTaskEnvironmentProvider<
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult
+>({
+  containerCliPath: () => requireAppleBinding().containerCliPath(),
+  machineIdentity: () => requireAppleBinding().machineIdentity(),
+  taskEnvironmentDown: agent.taskEnvironmentDown,
+  recoveryDriver: () => appleRecoveryDriver,
+  provisioning: {
+    // The runtime pin published UAI_TASK_RUNTIME / UAI_CONTAINER_CLI, so the
+    // same task-up entrypoint drives the Apple CLI instead of Compose.
+    taskUp: agent.taskUp,
+    inputTaskId: (input) => input.task.id,
+    hostWorktreePath: (taskId) => taskDir(taskId),
+    resultWorktreePath: (result) => result.worktreePath,
+  },
+});
+
+registry.register(appleProvider);
+
+/**
+ * Bind the Docker provider's private recovery implementation. Kept as a
+ * replaceable module seam so HMR can reload the orchestrator without leaving
+ * handles captured to an obsolete implementation.
+ */
+export function setDockerTaskEnvironmentRecoveryDriver(
+  driver: DockerTaskEnvironmentRecoveryDriver,
+): void {
+  dockerRecoveryDriver = driver;
+}
+
+export function provisionTaskEnvironment(
+  input: TaskLaunchInput,
+  credentials: TaskUpCredentials = {},
+  onPrepared?: (locator: TaskEnvironmentLocator) => Promise<void>,
+): Promise<TaskEnvironmentProvisioned<TaskUpResult, TaskDownResult>> {
+  const provider =
+    requireMachineIdentity().backend === "apple-container"
+      ? appleProvider
+      : dockerProvider;
+  return provider.provision({
+    taskId: input.task.id,
+    input,
+    credentials,
+    onPrepared,
+  });
+}
+
+export function reconstructTaskEnvironment(
+  locator: TaskEnvironmentLocator,
+): Promise<TaskEnvironmentHandle<TaskDownResult>> {
+  return registry.reconstruct(locator);
+}
+
+export async function reconstructPersistedTaskEnvironment(
+  task: HostTask,
+): Promise<TaskEnvironmentHandle<TaskDownResult> | null> {
+  const locator = persistedTaskEnvironmentLocator(task, requireMachineIdentity());
+  if (locator === null) return null;
+  const handle = await registry.reconstruct(locator);
+  if (handle.descriptor.taskId !== task.taskId) {
+    throw new Error("task environment locator belongs to a different task");
+  }
+  return handle;
+}
+
+/**
+ * Provider metadata is authoritative. Legacy resource rows must first cross
+ * the read-only adoption proof; reconstruction never auto-binds them merely
+ * because the currently-selected endpoint happens to answer.
+ */
+export function persistedTaskEnvironmentLocator(
+  task: Pick<
+    HostTask,
+    | "taskId"
+    | "composeProject"
+    | "worktreePath"
+    | "environmentProvider"
+    | "environmentLocator"
+    | "codeServerPort"
+    | "previewPorts"
+  >,
+  machine: HostMachineIdentity,
+): TaskEnvironmentLocator | null {
+  const provider = task.environmentProvider;
+  const raw = task.environmentLocator;
+  if ((provider === null) !== (raw === null)) {
+    throw new Error("task environment persistence is incomplete");
+  }
+  if (provider !== null && raw !== null) {
+    const locator = parseTaskEnvironmentLocator(raw);
+    if (locator.provider !== provider) {
+      throw new Error("task environment provider does not match its locator");
+    }
+    return locator;
+  }
+  if (task.composeProject === null && task.worktreePath === null) return null;
+  if (task.composeProject === null || task.worktreePath === null) {
+    throw new Error("legacy task runtime persistence is incomplete");
+  }
+  throw new Error(
+    machine.backend === "docker"
+      ? "legacy Docker resources have not passed safe adoption"
+      : `legacy task runtime belongs to ambient Docker and cannot move to ${machine.backend}`,
+  );
+}
+
+export interface TaskEnvironmentBackendVerdict {
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Machine/provider switch fence used before provisioning or maintenance. Any
+ * row that still names runtime resources belongs to exactly one backend. An
+ * unknown/newer provider or endpoint mismatch is a stop signal, never a hint
+ * to probe/mutate the currently-selected daemon.
+ */
+/** Extract the (backend, endpoint, engineId) triple a locator was pinned to,
+ * dispatching by provider. An unknown/newer provider throws. */
+export function locatorMachineIdentity(
+  locator: TaskEnvironmentLocator,
+): HostMachineIdentity {
+  if (locator.provider === DOCKER_TASK_ENVIRONMENT_PROVIDER) {
+    return parseDockerTaskEnvironmentLocator(locator).machine;
+  }
+  if (locator.provider === APPLE_TASK_ENVIRONMENT_PROVIDER) {
+    return parseAppleTaskEnvironmentLocator(locator).machine;
+  }
+  throw new Error(
+    `belongs to unavailable environment provider ${locator.provider}`,
+  );
+}
+
+export function persistedTaskEnvironmentsMatchMachine(
+  tasks: ReadonlyArray<
+    Pick<
+      HostTask,
+      | "taskId"
+      | "composeProject"
+      | "worktreePath"
+      | "environmentProvider"
+      | "environmentLocator"
+      | "codeServerPort"
+      | "previewPorts"
+    >
+  >,
+  machine: HostMachineIdentity,
+): TaskEnvironmentBackendVerdict {
+  for (const task of tasks) {
+    let locator: TaskEnvironmentLocator | null;
+    try {
+      locator = persistedTaskEnvironmentLocator(task, machine);
+    } catch (error) {
+      return {
+        ok: false,
+        detail: `task ${task.taskId}: ${boundedMessage(error)}`,
+      };
+    }
+    if (locator === null) continue;
+    try {
+      const persisted = locatorMachineIdentity(locator);
+      if (
+        persisted.backend !== machine.backend ||
+        persisted.endpoint !== machine.endpoint ||
+        persisted.engineId !== machine.engineId
+      ) {
+        return {
+          ok: false,
+          detail: `task ${task.taskId} belongs to a different container backend`,
+        };
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        detail: `task ${task.taskId}: ${boundedMessage(error)}`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
+export function hostTaskEnvironmentsMatchMachine(
+  machine: HostMachineIdentity,
+): TaskEnvironmentBackendVerdict {
+  const rows = getDb().select().from(schema.hostTasks).all();
+  return persistedTaskEnvironmentsMatchMachine(rows, machine);
+}
+
+export interface DockerMachineSelection {
+  backend: HostMachineIdentity["backend"];
+  endpoint: string;
+}
+
+/** Pre-provision provider fence. The engine identity is not knowable until
+ * the backend is activated, so this guard proves only that no durable row
+ * belongs to another provider/endpoint. The exact engine-ID fence runs
+ * immediately after the atomic daemon probe and before maintenance or
+ * recovery. */
+export function hostTaskEnvironmentsAllowMachineSelection(
+  machine: DockerMachineSelection,
+): TaskEnvironmentBackendVerdict {
+  const tasks = getDb().select().from(schema.hostTasks).all();
+  for (const task of tasks) {
+    if (
+      (task.environmentProvider === null) !==
+      (task.environmentLocator === null)
+    ) {
+      return {
+        ok: false,
+        detail: `task ${task.taskId}: task environment persistence is incomplete`,
+      };
+    }
+    if (task.environmentProvider === null) {
+      if (task.composeProject === null && task.worktreePath === null) continue;
+      return {
+        ok: false,
+        detail:
+          `task ${task.taskId} has legacy ambient-Docker resources; ` +
+          "start that Docker daemon and run `uai-host runtime recheck` " +
+          "before selecting another container runtime",
+      };
+    }
+    try {
+      const locator = parseTaskEnvironmentLocator(task.environmentLocator!);
+      if (locator.provider !== task.environmentProvider) {
+        throw new Error("task environment provider does not match its locator");
+      }
+      const persisted = locatorMachineIdentity(locator);
+      if (
+        persisted.backend !== machine.backend ||
+        persisted.endpoint !== machine.endpoint
+      ) {
+        throw new Error("belongs to a different container backend");
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        detail: `task ${task.taskId}: ${boundedMessage(error)}`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
+function requireMachineIdentity(): HostMachineIdentity {
+  // The PIN, not the operational-gated identity: reconstruction must serve
+  // teardown while the runtime is still `checking` (the 2026-08-16 ring).
+  // Locator comparison still demands an exact backend/endpoint/engine match,
+  // so nothing loosens about WHICH machine may own a row.
+  const identity = pinnedContainerRuntimeMachineIdentity();
+  if (identity === null) {
+    throw new Error("container runtime does not have a durable machine identity");
+  }
+  return identity;
+}
+
+/** The Docker provider must never operate on another backend's identity. */
+function requireDockerMachineIdentity(): DockerMachineIdentity {
+  const identity = requireMachineIdentity();
+  if (identity.backend !== "docker") {
+    throw new Error("the Docker task backend is not active on this host");
+  }
+  return identity;
+}
+
+function boundedMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 512);
+}