@runuai/host 0.9.148 → 0.9.150

package/lib/task-env-source.ts

@@ -0,0 +1,193 @@
+/**
+ * ADR-153 §4 and §6: where a task's project env comes from, for its /env and
+ * its proxy alike, on an owned runner and on a task machine's sidecar.
+ *
+ * - The store is the runner's own records on an owned runner, and on a task
+ *   machine the sidecar's replica of the cloud's.
+ * - A store never activated gives tasks the stored values, as before
+ *   records existed.
+ * - Once activated, a task's env is the view of one snapshot of the store,
+ *   decided with the task's own schema observations: each key's value as of
+ *   its head, a placeholder the proxy swaps, or nothing. While the store's
+ *   gate is closed, or a read of it fails, the task gets no project env at
+ *   all, never the stored values.
+ *
+ * A task's read of the store is kept until anything it depends on changes:
+ * one of its projects' values or records, a binding or the store's gate
+ * (each bumps a process-local revision, and only this process writes the
+ * store). Its observations are stored once and never change. So a change
+ * reaches the next command and the next request, while a command that
+ * changes nothing reads nothing.
+ */
+
+import { projectEnvAuthorityRevision, projectEnvRevision } from "./host-env";
+import { readProjectEnvAuthoritySnapshot } from "./project-env-authority";
+import { readProjectEnvReplicaSnapshot, readProjectEnvReplicaStatus } from "./project-env-replica";
+import { taskProjectEnvResolver, type TaskEnvSource } from "./project-env-loader";
+import { captureTaskEnvSchemas, taskEnvSchemaObservation } from "./project-env-schema-capture";
+import {
+  sameTaskEnvHead,
+  taskEnvView,
+  taskEnvWithheldNote,
+  type TaskEnvHead,
+  type TaskEnvSnapshot,
+} from "./project-env-task-policy";
+import { getHostTask, hostTaskProjectEnvSpec, type TaskProjectEnvSpec } from "./runtime-state";
+import { sidecarMode } from "./sidecar";
+import { taskProxiedEnv } from "./secrets-proxy/policy";
+import { taskTrustEnv } from "./secrets-proxy/readiness";
+import type { TaskGatewayEnvResolver } from "./task-gateway-state";
+
+/** The task's projects, lead first, as its launch pinned them. */
+function projectIdsOf(spec: TaskProjectEnvSpec): string[] {
+  const ordered = [...spec.projects].sort(
+    (left, right) => left.position - right.position || (left.projectId < right.projectId ? -1 : left.projectId > right.projectId ? 1 : 0),
+  );
+  return [...new Set(ordered.map((project) => project.projectId))];
+}
+
+/**
+ * One snapshot of the task's projects: `legacy` on a store that has never
+ * been activated, null while its gate is closed or it cannot be read, and
+ * otherwise the records, values and observations the task's decisions come
+ * from.
+ */
+export function readTaskEnvSnapshot(taskId: string, spec: TaskProjectEnvSpec): TaskEnvSnapshot | "legacy" | null {
+  const projectIds = projectIdsOf(spec);
+  const key = JSON.stringify([projectEnvAuthorityRevision(), projectIds.map((projectId) => [projectId, projectEnvRevision(projectId)])]);
+  const hit = snapshots.get(taskId);
+  if (hit?.key === key) return hit.snapshot;
+  const snapshot = freshTaskEnvSnapshot(taskId, projectIds);
+  // Kept only when nothing in it can change without a revision moving: a
+  // read that failed, or one with an observation not stored yet (task-up
+  // may still be about to record its base), is read again next time.
+  if (snapshot === "legacy" || (snapshot !== null && projectIds.every((projectId) => taskEnvSchemaObservation(taskId, projectId) !== null))) {
+    snapshots.delete(taskId);
+    if (snapshots.size >= MAX_SNAPSHOTS) snapshots.delete(snapshots.keys().next().value!);
+    snapshots.set(taskId, { key, snapshot });
+  }
+  return snapshot;
+}
+
+/** Tasks' last reads, most recent last. Values stay in memory only here and
+ *  in the rendered /env documents, as before. */
+const snapshots = new Map<string, { key: string; snapshot: TaskEnvSnapshot | "legacy" }>();
+const MAX_SNAPSHOTS = 256;
+
+/** Forget a task's read, when its gateway generation goes. */
+export function forgetTaskEnvSnapshot(taskId: string): void {
+  snapshots.delete(taskId);
+}
+
+function freshTaskEnvSnapshot(taskId: string, projectIds: readonly string[]): TaskEnvSnapshot | "legacy" | null {
+  return sidecarMode() ? replicaTaskEnvSnapshot(taskId, projectIds) : ownedTaskEnvSnapshot(taskId, projectIds);
+}
+
+/** An owned runner is the authority for its own records. */
+function ownedTaskEnvSnapshot(taskId: string, projectIds: readonly string[]): TaskEnvSnapshot | "legacy" | null {
+  const read = readProjectEnvAuthoritySnapshot(projectIds);
+  if (read === null) return null;
+  if (read.mode === "legacy") return "legacy";
+  return snapshotOf(taskId, projectIds, (projectId) => read.projects.find((project) => project.projectId === projectId)?.entries ?? []);
+}
+
+/**
+ * On a task machine the cloud is the authority, and the sidecar keeps a
+ * replica of its task's records (ADR-153 §4, "A machine's replica"): once it
+ * has been activated, the task's view comes from it, and a key whose value
+ * the sidecar has not installed gets none. Before that, the values the
+ * sidecar reads from the store by name, as before.
+ */
+function replicaTaskEnvSnapshot(taskId: string, projectIds: readonly string[]): TaskEnvSnapshot | "legacy" | null {
+  let activated: boolean;
+  try {
+    activated = readProjectEnvReplicaStatus().activated;
+  } catch {
+    return null;
+  }
+  if (!activated) return "legacy";
+  const read = readProjectEnvReplicaSnapshot(projectIds);
+  if (read === null) return null;
+  return snapshotOf(taskId, projectIds, (projectId) =>
+    (read.projects.find((project) => project.projectId === projectId)?.entries ?? []).map((entry) => ({
+      key: entry.state.key,
+      state: entry.state,
+      value: entry.materialization.kind === "installed" ? entry.value : null,
+    })),
+  );
+}
+
+interface StoreEntry {
+  key: string;
+  /** The record; null on a store that predates records. */
+  state: { head: TaskEnvHead; binding: unknown; policyEpoch: unknown } | null;
+  /** Null where the store holds no value for the record. */
+  value: string | null;
+}
+
+/** The task's snapshot of one read of the store, with its observations. */
+function snapshotOf(taskId: string, projectIds: readonly string[], entriesOf: (projectId: string) => readonly StoreEntry[]): TaskEnvSnapshot {
+  const projects = projectIds.map((projectId) => {
+    const entries = entriesOf(projectId);
+    return {
+      projectId,
+      // Captured here on the task's first read, from the base task-up
+      // recorded before the container started; with none recorded yet, a
+      // schema it could not read, so an unbound key is withheld.
+      observation: taskEnvSchemaObservation(taskId, projectId) ?? captureTaskEnvSchemas(taskId, [projectId], { final: false })[0],
+      records: entries.flatMap((entry) =>
+        entry.state === null
+          ? []
+          : [{ key: entry.key, head: entry.state.head, binding: entry.state.binding, policyEpoch: entry.state.policyEpoch }],
+      ),
+      entries,
+    };
+  });
+  return {
+    projects: projects.map(({ projectId, observation, records }) => ({ projectId, observation, records })),
+    valueAt: (projectId: string, key: string, head: TaskEnvHead): string | null => {
+      const entry = projects.find((project) => project.projectId === projectId)?.entries.find((candidate) => candidate.key === key);
+      return entry?.state != null && sameTaskEnvHead(entry.state.head, head) ? entry.value : null;
+    },
+  };
+}
+
+/** Where the task's /env takes its project values from right now. */
+export function taskEnvSource(taskId: string, spec: TaskProjectEnvSpec): TaskEnvSource {
+  const snapshot = readTaskEnvSnapshot(taskId, spec);
+  if (snapshot === "legacy") return { kind: "stored" };
+  if (snapshot === null) return { kind: "none" };
+  return { kind: "view", view: taskEnvView(snapshot) };
+}
+
+/** The task's snapshot for its proxy, by task id alone: what its persisted
+ *  launch spec names. Nothing is proxied from a store never activated. */
+export function proxyTaskEnvSnapshot(taskId: string): TaskEnvSnapshot | null {
+  const task = getHostTask(taskId);
+  let spec: TaskProjectEnvSpec | null = null;
+  try {
+    spec = task === null ? null : hostTaskProjectEnvSpec(task);
+  } catch {
+    return null;
+  }
+  if (spec === null) return null;
+  const snapshot = readTaskEnvSnapshot(taskId, spec);
+  return snapshot === "legacy" ? null : snapshot;
+}
+
+/** The task's note about the keys it does not get, from the store as it is
+ *  now; null when it gets every one, or the store gives no view. */
+export function taskEnvWithheldNoteNow(taskId: string, spec: TaskProjectEnvSpec): string | null {
+  const source = taskEnvSource(taskId, spec);
+  return source.kind === "view" ? taskEnvWithheldNote(source.view.policies) : null;
+}
+
+/** The resolver a loader task's gateway generation renders /env with. */
+export function taskEnvResolver(taskId: string, spec: TaskProjectEnvSpec): TaskGatewayEnvResolver {
+  return taskProjectEnvResolver(
+    spec,
+    () => taskTrustEnv(taskId),
+    () => taskProxiedEnv(taskId),
+    () => taskEnvSource(taskId, spec),
+  );
+}

package/lib/task-environment/apple-container.ts

@@ -27,12 +27,15 @@ import {
   hostWorkspaceWrite,
 } from "./workspace-files";
 import { assertSafeHostTaskId } from "../task-identity";
+import { applyProjectEnvProfile } from "../runtime-authority";
 import {
   capturedCliExec,
   streamingCliExec,
 } from "./docker";
 import {
+  assertTaskEnvironmentExecRequest,
   assertTaskEnvironmentProcessRequest,
+  refusePrivilegedExec,
   assertTaskEnvironmentSessionRequest,
   type TaskEnvironmentCopyRequest,
   type TaskEnvironmentDescriptor,
@@ -43,6 +46,7 @@ import {
   type TaskEnvironmentLocator,
   type TaskEnvironmentPort,
   type TaskEnvironmentProcess,
+  type ProjectEnvMode,
   type TaskEnvironmentProvider,
   type TaskEnvironmentRecoveryContext,
   type TaskEnvironmentRecoveryResult,
@@ -129,7 +133,11 @@ export type AppleTaskEnvironmentRecoveryDriver = (
 export interface AppleContainerProvisioningDeps<TInput, TCredentials, TResult> {
   /** Runs task-up with the selection environment already published by the
    * runtime pin (UAI_TASK_RUNTIME / UAI_CONTAINER_CLI). */
-  taskUp: (input: TInput, credentials?: TCredentials) => Promise<TResult>;
+  taskUp: (
+    input: TInput,
+    credentials?: TCredentials,
+    envMode?: ProjectEnvMode,
+  ) => Promise<TResult>;
   inputTaskId: (input: TInput) => string;
   /** The host worktree path this task will occupy, derivable before task-up
    * runs so a crash mid-provision still leaves a recoverable locator. */
@@ -184,6 +192,7 @@ export function createAppleContainerTaskEnvironmentProvider<
       const result = await provisioning.taskUp(
         request.input,
         request.credentials,
+        request.envMode ?? "loader",
       );
       const prepared = parseAppleTaskEnvironmentLocator(preparedLocator);
       // task-up composes its worktree path in shell from the operator's
@@ -202,11 +211,12 @@ export function createAppleContainerTaskEnvironmentProvider<
         handle: new AppleContainerTaskEnvironmentHandle(
           preparedLocator,
           resolved,
+          request.envMode ?? "loader",
         ),
         result,
       };
     },
-    async reconstruct(locator) {
+    async reconstruct(locator, envMode = "baked") {
       const persisted = parseAppleTaskEnvironmentLocator(locator);
       const current = validateAppleMachineIdentity(resolved.machineIdentity());
       if (
@@ -217,7 +227,7 @@ export function createAppleContainerTaskEnvironmentProvider<
           "task environment belongs to a different container backend",
         );
       }
-      return new AppleContainerTaskEnvironmentHandle(locator, resolved);
+      return new AppleContainerTaskEnvironmentHandle(locator, resolved, envMode);
     },
   };
 }
@@ -266,12 +276,14 @@ class AppleContainerTaskEnvironmentHandle
   constructor(
     locator: TaskEnvironmentLocator,
     private readonly deps: ResolvedAppleContainerDeps,
+    envMode: ProjectEnvMode,
   ) {
     this.#value = parseAppleTaskEnvironmentLocator(locator);
     this.durableIdentity = this.#value.containerName;
     this.descriptor = {
       taskId: this.#value.taskId,
       locator,
+      envMode,
       workspacePath: "/workspace",
     };
   }
@@ -294,12 +306,19 @@ class AppleContainerTaskEnvironmentHandle
   }
 
   exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
-    assertTaskEnvironmentProcessRequest(request);
+    assertTaskEnvironmentExecRequest(request);
+    refusePrivilegedExec(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    request.admit?.();
     return capturedCliExec(
       this.deps.spawn,
       this.deps.containerCliPath(),
-      appleExecArgs(this.#value.containerName, request, "interactive"),
-      request,
+      appleExecArgs(this.#value.containerName, profiled, "interactive"),
+      profiled,
     );
   }
 
@@ -307,11 +326,16 @@ class AppleContainerTaskEnvironmentHandle
     request: TaskEnvironmentSpawnRequest,
   ): Promise<TaskEnvironmentProcess> {
     assertTaskEnvironmentProcessRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     return streamingCliExec(
       this.deps.spawn,
       this.deps.containerCliPath(),
-      appleExecArgs(this.#value.containerName, request, "interactive"),
-      request,
+      appleExecArgs(this.#value.containerName, profiled, "interactive"),
+      profiled,
     );
   }
 
@@ -319,11 +343,16 @@ class AppleContainerTaskEnvironmentHandle
     request: TaskEnvironmentSessionRequest,
   ): Promise<TaskEnvironmentProcess> {
     assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     return streamingCliExec(
       this.deps.spawn,
       this.deps.containerCliPath(),
-      appleExecArgs(this.#value.containerName, request, "interactive"),
-      request,
+      appleExecArgs(this.#value.containerName, profiled, "interactive"),
+      profiled,
     );
   }
 
@@ -331,8 +360,13 @@ class AppleContainerTaskEnvironmentHandle
     request: TaskEnvironmentDetachedSessionRequest,
   ): Promise<TaskEnvironmentExecResult> {
     assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     const result = await this.deps.run(
-      appleExecArgs(this.#value.containerName, request, "detached"),
+      appleExecArgs(this.#value.containerName, profiled, "detached"),
       {
         timeoutMs: request.launchTimeoutMs,
         maxOutputBytes: request.maxOutputBytes,

package/lib/task-environment/docker.ts

@@ -22,7 +22,9 @@ import {
 import { taskDir } from "../env";
 import { PREVIEW_SIDECAR_TASK_LABEL } from "../preview-sidecar";
 import { assertSafeHostTaskId } from "../task-identity";
+import { applyProjectEnvProfile } from "../runtime-authority";
 import {
+  assertTaskEnvironmentExecRequest,
   assertTaskEnvironmentProcessRequest,
   assertTaskEnvironmentSessionRequest,
   type TaskEnvironmentCopyRequest,
@@ -35,6 +37,7 @@ import {
   type TaskEnvironmentPort,
   type TaskEnvironmentProcess,
   type TaskEnvironmentProcessExit,
+  type ProjectEnvMode,
   type TaskEnvironmentProvider,
   type TaskEnvironmentRecoveryContext,
   type TaskEnvironmentRecoveryResult,
@@ -73,6 +76,7 @@ export interface DockerTaskEnvironmentDeps {
   taskUp?: (
     input: TaskLaunchInput,
     credentials?: TaskUpCredentials,
+    envMode?: ProjectEnvMode,
   ) => Promise<TaskUpResult>;
   taskEnvironmentDown?: (taskId: string) => Promise<TaskDownResult>;
   taskStatus?: (taskId: string) => Promise<TaskStatusResult>;
@@ -123,7 +127,11 @@ export function createDockerTaskEnvironmentProvider(
         machine,
       );
       await request.onPrepared?.(preparedLocator);
-      const result = await resolved.taskUp(request.input, request.credentials);
+      const result = await resolved.taskUp(
+        request.input,
+        request.credentials,
+        request.envMode ?? "loader",
+      );
       const prepared = parseDockerTaskEnvironmentLocator(preparedLocator);
       // task-up composes its worktree path in shell from the operator's
       // UAI_WORKSPACE_ROOT verbatim, so a benign trailing slash would fail a
@@ -145,11 +153,15 @@ export function createDockerTaskEnvironmentProvider(
         machine,
       );
       return {
-        handle: new DockerTaskEnvironmentHandle(locator, resolved),
+        handle: new DockerTaskEnvironmentHandle(
+          locator,
+          resolved,
+          request.envMode ?? "loader",
+        ),
         result,
       };
     },
-    async reconstruct(locator) {
+    async reconstruct(locator, envMode = "baked") {
       const persisted = parseDockerTaskEnvironmentLocator(locator);
       const current = validateMachineIdentity(resolved.machineIdentity());
       if (
@@ -161,7 +173,7 @@ export function createDockerTaskEnvironmentProvider(
           "task environment belongs to a different container backend",
         );
       }
-      return new DockerTaskEnvironmentHandle(locator, resolved);
+      return new DockerTaskEnvironmentHandle(locator, resolved, envMode);
     },
   };
 }
@@ -256,12 +268,14 @@ class DockerTaskEnvironmentHandle
         DockerTaskEnvironmentDeps,
         "recover" | "recoveryDriver" | "taskStatus"
       >,
+    envMode: ProjectEnvMode,
   ) {
     this.#value = parseDockerTaskEnvironmentLocator(locator);
     this.durableIdentity = this.#value.containerName;
     this.descriptor = {
       taskId: this.#value.taskId,
       locator,
+      envMode,
       workspacePath: "/workspace",
       ...(this.#value.codeServerPort === undefined
         ? {}
@@ -293,12 +307,19 @@ class DockerTaskEnvironmentHandle
   }
 
   exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
-    assertTaskEnvironmentProcessRequest(request);
+    assertTaskEnvironmentExecRequest(request);
+    const { privileged, ...unprivileged } = request;
+    const profiled = applyProjectEnvProfile(
+      unprivileged,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
+    request.admit?.();
     return capturedCliExec(
       this.deps.spawn,
       "docker",
-      dockerExecArgs(this.#value.containerName, request),
-      request,
+      dockerExecArgs(this.#value.containerName, profiled, "interactive", privileged === true),
+      profiled,
     );
   }
 
@@ -306,11 +327,16 @@ class DockerTaskEnvironmentHandle
     request: TaskEnvironmentSpawnRequest,
   ): Promise<TaskEnvironmentProcess> {
     assertTaskEnvironmentProcessRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     return streamingCliExec(
       this.deps.spawn,
       "docker",
-      dockerExecArgs(this.#value.containerName, request),
-      request,
+      dockerExecArgs(this.#value.containerName, profiled),
+      profiled,
     );
   }
 
@@ -318,11 +344,16 @@ class DockerTaskEnvironmentHandle
     request: TaskEnvironmentSessionRequest,
   ): Promise<TaskEnvironmentProcess> {
     assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     return streamingCliExec(
       this.deps.spawn,
       "docker",
-      dockerExecArgs(this.#value.containerName, request),
-      request,
+      dockerExecArgs(this.#value.containerName, profiled),
+      profiled,
     );
   }
 
@@ -330,8 +361,13 @@ class DockerTaskEnvironmentHandle
     request: TaskEnvironmentDetachedSessionRequest,
   ): Promise<TaskEnvironmentExecResult> {
     assertTaskEnvironmentSessionRequest(request);
+    const profiled = applyProjectEnvProfile(
+      request,
+      this.descriptor.envMode ?? "baked",
+      "/usr/bin/zsh",
+    );
     const result = await this.deps.docker(
-      dockerExecArgs(this.#value.containerName, request, "detached"),
+      dockerExecArgs(this.#value.containerName, profiled, "detached"),
       {
         timeoutMs: request.launchTimeoutMs,
         maxOutputBytes: request.maxOutputBytes,
@@ -606,8 +642,11 @@ function dockerExecArgs(
     | TaskEnvironmentSessionRequest
     | TaskEnvironmentDetachedSessionRequest,
   mode: "interactive" | "detached" = "interactive",
+  /** Passed only by exec(), after assertTaskEnvironmentExecRequest. */
+  privileged = false,
 ): string[] {
   const args = ["exec", mode === "detached" ? "-d" : "-i"];
+  if (privileged) args.push("--privileged");
   if (request.cwd) args.push("--workdir", request.cwd);
   if (request.user) args.push("--user", request.user);
   for (const name of request.inheritEnv ?? []) {

package/lib/task-environment/index.ts

@@ -33,6 +33,7 @@ import { createMachineHostTaskEnvironmentProvider } from "./machine-task-up";
 import { TaskEnvironmentRegistry } from "./registry";
 import {
   parseTaskEnvironmentLocator,
+  type ProjectEnvMode,
   type TaskEnvironmentHandle,
   type TaskEnvironmentLocator,
   type TaskEnvironmentProvisioned,
@@ -47,6 +48,7 @@ export {
 import { sidecarMode } from "../sidecar";
 import { mountSharedFilesFromLease } from "../shared-files-s3";
 import { createSelfTaskEnvironmentProvider } from "./self";
+import { hostTaskEnvMode } from "../runtime-state";
 
 const registry = new TaskEnvironmentRegistry<
   TaskLaunchInput,
@@ -215,6 +217,7 @@ export function provisionTaskEnvironment(
       : dockerProvider;
   return provider.provision({
     taskId: input.task.id,
+    envMode: "loader",
     input,
     credentials,
     onPrepared,
@@ -223,8 +226,9 @@ export function provisionTaskEnvironment(
 
 export function reconstructTaskEnvironment(
   locator: TaskEnvironmentLocator,
+  envMode: ProjectEnvMode,
 ): Promise<TaskEnvironmentHandle<TaskDownResult>> {
-  return registry.reconstruct(locator);
+  return registry.reconstruct(locator, envMode);
 }
 
 export async function reconstructPersistedTaskEnvironment(
@@ -240,7 +244,7 @@ export async function reconstructPersistedTaskEnvironment(
       : requireMachineIdentity(),
   );
   if (locator === null) return null;
-  const handle = await registry.reconstruct(locator);
+  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");
   }