@runuai/host 0.9.150 → 0.9.151

package/lib/task-environment/types.ts

@@ -53,6 +53,15 @@ export interface TaskEnvironmentExecRequest {
    * default capabilities); every other provider refuses it.
    */
   privileged?: true;
+  /**
+   * ADR-154 §6: start the process under the engine supervisor, admitted by
+   * the runner and owned until a cleanup kills it. The provider runs, as
+   * root, the anchor's prefix, the task user the process would have run as
+   * (or "-" when the provider drops to it itself), "--", then the process
+   * as it would have run it; the supervisor drops to that user. A request
+   * that must run as root is never anchored.
+   */
+  anchor?: TaskEnvironmentAnchor;
   /**
    * Called by the provider at the last moment before the process starts,
    * after anything it awaits first (a machine looks up its address);
@@ -82,6 +91,27 @@ export interface TaskEnvironmentSpawnRequest {
   projectEnvProfile: ProjectEnvProfile;
   timeoutMs: number;
   maxOutputBytes: number;
+  /** ADR-154 §6: see `TaskEnvironmentExecRequest.anchor`. */
+  anchor?: TaskEnvironmentAnchor;
+  /** See `TaskEnvironmentExecRequest.admit`. */
+  admit?: () => void;
+}
+
+/**
+ * ADR-154 §6: the engine supervisor a process starts under
+ * (credential-consumers/engine-anchor.ts): its argv up to the user it drops
+ * to.
+ */
+export interface TaskEnvironmentAnchor {
+  readonly prefix: readonly [string, ...string[]];
+  /**
+   * When the launch carries engine credentials in its admission: what a
+   * provider that drops to the task user itself (anchor user "-") runs
+   * right after that drop, before the process; it reads them from the
+   * supervisor's hand-off. A provider whose supervisor drops (a named user)
+   * ignores it: the supervisor hands them to the engine itself.
+   */
+  readonly injector?: readonly [string, ...string[]];
 }
 
 /**
@@ -97,6 +127,10 @@ export interface TaskEnvironmentSessionRequest {
   env?: Readonly<Record<string, string>>;
   projectEnvProfile: ProjectEnvProfile;
   maxOutputBytes: number;
+  /** ADR-154 §6: see `TaskEnvironmentExecRequest.anchor`. */
+  anchor?: TaskEnvironmentAnchor;
+  /** See `TaskEnvironmentExecRequest.admit`. */
+  admit?: () => void;
 }
 
 /** A bounded control-plane launch of a detached durable-session runner. */
@@ -132,6 +166,14 @@ export interface TaskEnvironmentProcess {
 export interface TaskEnvironmentAgentSessionSurface {
   readonly descriptor: TaskEnvironmentDescriptor;
   readonly durableIdentity: string;
+  /** ADR-154 §6: whether the provider starts a request's `anchor`. One that
+   *  does not never runs a leased engine. */
+  readonly anchors?: boolean;
+  /** ADR-154 §6: "admission" when a request's environment would reach a
+   *  command line (a machine's ssh command, a local shell line), so a leased
+   *  launch's engine credentials travel in its admission instead; absent
+   *  when the provider passes them by name (`--env NAME`). */
+  readonly credentialDelivery?: "admission";
   spawnSession(
     request: TaskEnvironmentSessionRequest,
   ): Promise<TaskEnvironmentProcess>;
@@ -140,7 +182,7 @@ export interface TaskEnvironmentAgentSessionSurface {
   ): Promise<TaskEnvironmentExecResult>;
 }
 
-export type TaskEnvironmentCopyRequest =
+export type TaskEnvironmentCopyRequest = (
   | {
       direction: "into";
       /** Absolute host path. */
@@ -154,7 +196,31 @@ export type TaskEnvironmentCopyRequest =
       source: string;
       /** Absolute host path. */
       destination: string;
-    };
+    }
+) &
+  TaskEnvironmentCallOptions;
+
+/** What every call into an environment may carry. */
+export interface TaskEnvironmentCallOptions {
+  /** See `TaskEnvironmentExecRequest.admit`: the provider's last word before
+   *  its process or transport starts, after anything it awaits first. */
+  admit?: () => void;
+}
+
+/** How much of a workspace file a read takes. The task controls its
+ *  workspace, so every read of it is bounded. */
+export interface TaskEnvironmentReadOptions extends TaskEnvironmentCallOptions {
+  /** At most this many bytes (default `WORKSPACE_READ_MAX_BYTES`). */
+  maxBytes?: number;
+  /** Which end of a longer file is read: its start (the default) or its
+   *  end. */
+  from?: "start" | "end";
+}
+
+/** The most a workspace read takes, unless it asks for less. */
+export const WORKSPACE_READ_MAX_BYTES = 64 * 1024 * 1024;
+/** How long a workspace read may take before it is given up. */
+export const WORKSPACE_READ_TIMEOUT_MS = 60_000;
 
 export interface TaskEnvironmentPort {
   name?: string;
@@ -170,6 +236,9 @@ export type TaskEnvironmentStatus =
        * `containers` field while that protocol remains in service. */
       instances: string[];
       workspacePresent: boolean;
+      /** Not running, yet its processes still exist (a paused or
+       * restarting container): they run again without a new start. */
+      frozen?: true;
     }
   | { state: "unknown"; detail: string };
 
@@ -221,9 +290,12 @@ export interface TaskEnvironmentHandle<TTeardownResult = void>
    * (docker, apple) implement these as direct filesystem access — zero
    * behavior change; machine providers reach over their transport. Read
    * resolves null for a missing file and rejects for any other failure —
-   * absence and error are different facts. */
-  readWorkspaceFile(path: string): Promise<Uint8Array | null>;
-  writeWorkspaceFile(path: string, bytes: Uint8Array): Promise<void>;
+   * absence and error are different facts. A read takes only a regular
+   * file, never waits on one it opens (a FIFO or device is refused), takes
+   * at most `maxBytes`, and is given up past its bound: what the task puts
+   * in its workspace never stalls the runner. */
+  readWorkspaceFile(path: string, options?: TaskEnvironmentReadOptions): Promise<Uint8Array | null>;
+  writeWorkspaceFile(path: string, bytes: Uint8Array, options?: TaskEnvironmentCallOptions): Promise<void>;
   exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult>;
   spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess>;
   copy(request: TaskEnvironmentCopyRequest): Promise<void>;
@@ -255,6 +327,7 @@ export interface TaskEnvironmentHandle<TTeardownResult = void>
   gatewayTunnelSshArgs?(
     machinePort: number,
     hostPort: number,
+    options?: TaskEnvironmentCallOptions,
   ): Promise<string[]>;
 }
 
@@ -388,6 +461,17 @@ export function assertTaskEnvironmentSessionRequest(
   ) {
     throw new Error("task environment user must be a nonempty NUL-free value");
   }
+  if (
+    request.anchor !== undefined &&
+    (request.user === "root" ||
+      !Array.isArray(request.anchor.prefix) ||
+      request.anchor.prefix.length === 0 ||
+      request.anchor.prefix.some(
+        (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
+      ))
+  ) {
+    throw new Error("a task environment anchor must be a NUL-free argv for a task user's process");
+  }
   if (
     request.inheritEnv !== undefined &&
     (!Array.isArray(request.inheritEnv) ||