@moondeck/station 0.0.1 → 1.0.1

package/lib/task-environment/index.ts

@@ -0,0 +1,466 @@
+import {
+  agent,
+  type TaskDownResult,
+  type TaskLaunchInput,
+  type TaskUpCredentials,
+  type TaskUpResult,
+} from "../agent";
+import { RUNTIME_RECHECK_COMMAND, 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 { createAwsMachineProvider } from "../machine-provider-aws";
+import { createLocalMachineProvider } from "../machine-provider-local";
+import { ensureMachineKeyPair } from "../machine-keys";
+import { requestAccessToken } from "../github-tokens";
+import {
+  createMachineTaskEnvironmentProvider,
+} from "./machine";
+import { createMachineHostTaskEnvironmentProvider } from "./machine-task-up";
+import { TaskEnvironmentRegistry } from "./registry";
+import {
+  parseTaskEnvironmentLocator,
+  type ProjectEnvMode,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentProvisioned,
+  isEnvironmentTransportProvider,
+} from "./types";
+
+export {
+  adoptLegacyTaskEnvironments,
+  type LegacyTaskEnvironmentAdoptionDeps,
+  type LegacyTaskEnvironmentAdoptionVerdict,
+} from "./legacy-adoption";
+import { sidecarMode } from "../sidecar";
+import { mountSharedFilesFromLease } from "../shared-files-s3";
+import { createSelfTaskEnvironmentProvider } from "./self";
+import { hostTaskEnvMode } from "../runtime-state";
+
+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);
+
+// ---------------------------------------------------------------------------
+// ADR-121: machine-backed tasks (ephemeral VM per task). Opt-in via
+// UAI_MACHINE_TASKS=1 — the guinea-pig flag; selection stays coarse (whole
+// host) until machine-backing becomes a per-task property.
+// ---------------------------------------------------------------------------
+
+export function machineTasksEnabled(): boolean {
+  return process.env.UAI_MACHINE_TASKS === "1";
+}
+
+function machineBackend() {
+  if (process.env.UAI_MACHINE_PROVIDER === "aws") {
+    const region = process.env.UAI_AWS_REGION;
+    if (!region) {
+      throw new Error("UAI_MACHINE_PROVIDER=aws requires UAI_AWS_REGION");
+    }
+    const diskGiB = Number(process.env.UAI_MACHINE_DISK_GIB ?? "");
+    return createAwsMachineProvider({
+      region,
+      subnetId: process.env.UAI_AWS_SUBNET_ID,
+      securityGroupId: process.env.UAI_AWS_SECURITY_GROUP_ID,
+      iamInstanceProfileArn: process.env.UAI_AWS_INSTANCE_PROFILE_ARN,
+      ...(Number.isInteger(diskGiB) && diskGiB > 0 ? { diskGiB } : {}),
+    });
+  }
+  return createLocalMachineProvider();
+}
+
+const machineEnvironmentProvider = createMachineTaskEnvironmentProvider({
+  machines: machineBackend(),
+  taskControlDir: (taskId) => taskDir(taskId),
+  mintKeyPair: ensureMachineKeyPair,
+});
+
+const machineProvider = createMachineHostTaskEnvironmentProvider({
+  environment: machineEnvironmentProvider,
+  taskControlDir: (taskId) => taskDir(taskId),
+  machineImage: () => process.env.UAI_MACHINE_IMAGE ?? "uai-machine:dev",
+  machineCpus: () => Number(process.env.UAI_MACHINE_CPUS ?? "2"),
+  machineMemoryMiB: () => Number(process.env.UAI_MACHINE_MEMORY_MIB ?? "4096"),
+  // Local machines on macOS need loopback-published ssh (bridge IPs are not
+  // host-routable there); cloud machines and Linux dial the address directly.
+  publishSsh: () =>
+    process.env.UAI_MACHINE_PROVIDER !== "aws" && process.platform === "darwin",
+  githubToken: (userId) => requestAccessToken(userId),
+});
+
+registry.register(machineProvider);
+
+// ADR-133 sidecar mode: the environment is this machine. Same task-up on top
+// (clone, editor, browser), a local-exec handle underneath; shared files
+// are mounted from S3 rather than copied from a host directory.
+const selfProvider = createMachineHostTaskEnvironmentProvider({
+  environment: createSelfTaskEnvironmentProvider(),
+  taskControlDir: (taskId) => taskDir(taskId),
+  machineImage: () => "self",
+  machineCpus: () => 0,
+  machineMemoryMiB: () => 0,
+  publishSsh: () => false,
+  githubToken: (userId) => requestAccessToken(userId),
+  sharedFiles: mountSharedFilesFromLease,
+});
+
+registry.register(selfProvider);
+
+/**
+ * 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 = sidecarMode()
+    ? selfProvider
+    : machineTasksEnabled()
+      ? machineProvider
+      : requireMachineIdentity().backend === "apple-container"
+      ? appleProvider
+      : dockerProvider;
+  return provider.provision({
+    taskId: input.task.id,
+    envMode: "loader",
+    input,
+    credentials,
+    onPrepared,
+  });
+}
+
+export function reconstructTaskEnvironment(
+  locator: TaskEnvironmentLocator,
+  envMode: ProjectEnvMode,
+): Promise<TaskEnvironmentHandle<TaskDownResult>> {
+  return registry.reconstruct(locator, envMode);
+}
+
+export async function reconstructPersistedTaskEnvironment(
+  task: HostTask,
+): Promise<TaskEnvironmentHandle<TaskDownResult> | null> {
+  // ADR-133: a machine or sidecar row carries its own locator and never
+  // needs the container runtime's identity — on a task machine there is
+  // none, and demanding it here would strand every session after task-up.
+  const locator = persistedTaskEnvironmentLocator(
+    task,
+    isEnvironmentTransportProvider(task.environmentProvider)
+      ? null
+      : requireMachineIdentity(),
+  );
+  if (locator === null) return null;
+  const handle = await registry.reconstruct(locator, hostTaskEnvMode(task));
+  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"
+  >,
+  /** Null only for rows whose provider is reached over the environment
+   *  transport (machine, self): their locator is self-contained. */
+  machine: HostMachineIdentity | null,
+): 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");
+  }
+  if (machine === null) {
+    throw new Error("legacy task runtime cannot be adopted on a task machine");
+  }
+  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;
+    // ADR-121: machine locators name an ephemeral VM, not a container
+    // daemon — no container-runtime identity claim to verify.
+    if (isEnvironmentTransportProvider(locator.provider)) 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 \`${RUNTIME_RECHECK_COMMAND}\` ` +
+          "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");
+      }
+      // ADR-121: machine rows make no container-runtime claim.
+      if (isEnvironmentTransportProvider(locator.provider)) continue;
+      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);
+}