@runuai/host 0.9.14 → 0.9.42

package/lib/task-environment/types.ts

@@ -0,0 +1,408 @@
+/**
+ * Environment-level task boundary (ADR-101 Phase C).
+ *
+ * Providers own machine/container details. Generic orchestration receives an
+ * opaque, durable locator and a handle with bounded argv-based operations; it
+ * never receives a Docker socket, Compose project, or generic remote shell.
+ */
+
+export const TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION = 1 as const;
+
+export interface TaskEnvironmentLocator {
+  schemaVersion: typeof TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION;
+  /** Stable provider registry key, for example `docker-compose`. */
+  provider: string;
+  /** Provider-owned, JSON-serializable reconstruction payload. */
+  value: unknown;
+}
+
+export interface TaskEnvironmentDescriptor {
+  taskId: string;
+  locator: TaskEnvironmentLocator;
+  /** Absolute path as observed inside the environment. */
+  workspacePath: string;
+  codeServerPort?: number;
+  previewPorts?: Array<{ name: string; hostPort: number }>;
+  initWarning?: string;
+}
+
+export interface TaskEnvironmentExecRequest {
+  /** Executable followed by literal argv. Shell command strings are forbidden. */
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  /** Host environment names inherited by name, without copying values into argv. */
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  stdin?: Uint8Array;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}
+
+export interface TaskEnvironmentExecResult {
+  exitCode: number | null;
+  signal: string | null;
+  stdout: Uint8Array;
+  stderr: Uint8Array;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+export interface TaskEnvironmentSpawnRequest {
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  /** Host environment names inherited by name, without copying values into argv. */
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}
+
+/**
+ * Long-lived process request used only by agent-session adapters. Its
+ * lifetime is owned by the session and therefore has no wall-clock timeout;
+ * unread stdout/stderr remains bounded by `maxOutputBytes`.
+ */
+export interface TaskEnvironmentSessionRequest {
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  maxOutputBytes: number;
+}
+
+/** A bounded control-plane launch of a detached durable-session runner. */
+export interface TaskEnvironmentDetachedSessionRequest
+  extends TaskEnvironmentSessionRequest {
+  launchTimeoutMs: number;
+}
+
+export interface TaskEnvironmentProcessExit {
+  exitCode: number | null;
+  signal: string | null;
+}
+
+/**
+ * Streaming process primitive used by durable agent sessions. Providers must
+ * keep output buffering within `maxOutputBytes`; AsyncIterable does not imply
+ * permission to retain an unbounded unread stream.
+ */
+export interface TaskEnvironmentProcess {
+  readonly stdout: AsyncIterable<Uint8Array>;
+  readonly stderr: AsyncIterable<Uint8Array>;
+  readonly completion: Promise<TaskEnvironmentProcessExit>;
+  write(chunk: Uint8Array): Promise<void>;
+  closeInput(): Promise<void>;
+  terminate(signal?: "SIGTERM" | "SIGKILL"): Promise<void>;
+}
+
+/**
+ * Provider-neutral surface handed to agent adapters. `durableIdentity` is an
+ * opaque diagnostic/persistence value; callers must never parse it as a
+ * container or machine identifier.
+ */
+export interface TaskEnvironmentAgentSessionSurface {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  spawnSession(
+    request: TaskEnvironmentSessionRequest,
+  ): Promise<TaskEnvironmentProcess>;
+  launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult>;
+}
+
+export type TaskEnvironmentCopyRequest =
+  | {
+      direction: "into";
+      /** Absolute host path. */
+      source: string;
+      /** Absolute environment path. */
+      destination: string;
+    }
+  | {
+      direction: "out";
+      /** Absolute environment path. */
+      source: string;
+      /** Absolute host path. */
+      destination: string;
+    };
+
+export interface TaskEnvironmentPort {
+  name?: string;
+  containerPort: number;
+  host: "127.0.0.1";
+  hostPort: number;
+}
+
+export type TaskEnvironmentStatus =
+  | {
+      state: "running" | "stopped" | "absent";
+      /** Provider-level runtime identities, mapped to the legacy wire's
+       * `containers` field while that protocol remains in service. */
+      instances: string[];
+      workspacePresent: boolean;
+    }
+  | { state: "unknown"; detail: string };
+
+/**
+ * Recovery is allowed to perform provider-private repair, but its caller owns
+ * the surrounding task/channel lifecycle. These callbacks keep that ordering
+ * explicit without exposing a Docker container, Compose project, or VM
+ * identity to generic orchestration.
+ */
+export interface TaskEnvironmentRecoveryContext {
+  /** One-way host maintenance latch (standard image, shared CLI state, etc.). */
+  maintenanceReady: Promise<void>;
+  /** Provider work must stop before every externally-visible side effect when
+   * this generation is no longer current. */
+  isCurrent(): boolean;
+  /** Drain/tombstone consumers before stopping or repairing a live writer. */
+  quarantineConsumers?: () => Promise<void>;
+  /** Re-open admission only after the environment is proven operational. */
+  allowConsumers?: () => void;
+  /** Recreate durable consumers after admission has reopened. */
+  ensureConsumersStarted?: () => Promise<void>;
+}
+
+export type TaskEnvironmentRecoveryResult =
+  | {
+      outcome: "recovered";
+      /** Optional fresh provider status. Recovery itself is the authoritative
+       * proof; callers must not issue a second inventory probe merely to fill
+       * this field. */
+      status?: TaskEnvironmentStatus;
+      descriptor?: TaskEnvironmentDescriptor;
+    }
+  | {
+      outcome: "deferred";
+      /** Bounded, operator-safe reason. Deferred recovery is retryable and
+       * must never be interpreted as absence. */
+      detail: string;
+    };
+
+export interface TaskEnvironmentHandle<TTeardownResult = void>
+  extends TaskEnvironmentAgentSessionSurface {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult>;
+  spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess>;
+  copy(request: TaskEnvironmentCopyRequest): Promise<void>;
+  ports(): Promise<TaskEnvironmentPort[]>;
+  status(): Promise<TaskEnvironmentStatus>;
+  recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult>;
+  /** Resumable pause: halt the environment's processes while keeping every
+   * durable resource (worktree, volumes, container state) so a later
+   * provision/recovery can resume it. Idempotent for an already-stopped
+   * environment. */
+  stop(): Promise<void>;
+  /** Idempotent: success means provider-owned runtime resources are absent. */
+  teardown(): Promise<TTeardownResult>;
+  /** Direct-route inspection for backends whose container IPs are
+   * host-routable (ADR-106 Apple vmnet). Providers that publish host ports
+   * instead simply omit it. The proof must bind the answer to this exact
+   * task's container (label check), not merely a name lookup. */
+  inspectRoute?(): Promise<
+    | { kind: "running"; ipv4Address: string }
+    | { kind: "unavailable" }
+    | { kind: "unknown"; detail: string }
+  >;
+}
+
+export interface TaskEnvironmentProvisionRequest<TInput, TCredentials> {
+  taskId: string;
+  input: TInput;
+  credentials: TCredentials;
+  /**
+   * Awaited after the provider has derived and validated its durable identity,
+   * but before it creates any external resources. A crash after this callback
+   * can therefore be recovered from the opaque locator alone.
+   */
+  onPrepared?: (locator: TaskEnvironmentLocator) => Promise<void>;
+}
+
+export interface TaskEnvironmentProvisioned<TResult, TTeardownResult = void> {
+  handle: TaskEnvironmentHandle<TTeardownResult>;
+  /** Provider launch result retained for rolling wire compatibility. */
+  result: TResult;
+}
+
+export interface TaskEnvironmentProvider<
+  TInput,
+  TCredentials,
+  TResult,
+  TTeardownResult = void,
+> {
+  readonly kind: string;
+  provision(
+    request: TaskEnvironmentProvisionRequest<TInput, TCredentials>,
+  ): Promise<TaskEnvironmentProvisioned<TResult, TTeardownResult>>;
+  reconstruct(
+    locator: TaskEnvironmentLocator,
+  ): Promise<TaskEnvironmentHandle<TTeardownResult>>;
+}
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Shared admission guard for provider implementations and fake providers. */
+export function assertTaskEnvironmentProcessRequest(
+  request: TaskEnvironmentExecRequest | TaskEnvironmentSpawnRequest,
+): void {
+  assertTaskEnvironmentSessionRequest(request);
+  if (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0) {
+    throw new Error("task environment timeout must be a positive integer");
+  }
+}
+
+export function assertTaskEnvironmentSessionRequest(
+  request:
+    | TaskEnvironmentSessionRequest
+    | TaskEnvironmentDetachedSessionRequest
+    | TaskEnvironmentExecRequest
+    | TaskEnvironmentSpawnRequest,
+): void {
+  if (
+    !Array.isArray(request.argv) ||
+    request.argv.length === 0 ||
+    request.argv.some(
+      (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
+    )
+  ) {
+    throw new Error("task environment argv must contain nonempty NUL-free strings");
+  }
+  if (
+    request.cwd !== undefined &&
+    (!request.cwd.startsWith("/") || request.cwd.includes("\0"))
+  ) {
+    throw new Error("task environment cwd must be an absolute NUL-free path");
+  }
+  if (
+    request.user !== undefined &&
+    (request.user.length === 0 || request.user.includes("\0"))
+  ) {
+    throw new Error("task environment user must be a nonempty NUL-free value");
+  }
+  if (
+    request.inheritEnv !== undefined &&
+    (!Array.isArray(request.inheritEnv) ||
+      request.inheritEnv.length > 128 ||
+      new Set(request.inheritEnv).size !== request.inheritEnv.length ||
+      request.inheritEnv.some(
+        (name) => typeof name !== "string" || !ENV_NAME.test(name),
+      ))
+  ) {
+    throw new Error("task environment inherited env names are invalid");
+  }
+  for (const [name, value] of Object.entries(request.env ?? {})) {
+    if (
+      !ENV_NAME.test(name) ||
+      typeof value !== "string" ||
+      value.includes("\0")
+    ) {
+      throw new Error("task environment env must contain valid NUL-free entries");
+    }
+  }
+  if (
+    !Number.isSafeInteger(request.maxOutputBytes) ||
+    request.maxOutputBytes <= 0
+  ) {
+    throw new Error("task environment output limit must be a positive integer");
+  }
+  if (
+    "launchTimeoutMs" in request &&
+    (!Number.isSafeInteger(request.launchTimeoutMs) ||
+      request.launchTimeoutMs <= 0)
+  ) {
+    throw new Error(
+      "task environment detached launch timeout must be a positive integer",
+    );
+  }
+}
+
+export function serializeTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): string {
+  validateTaskEnvironmentLocator(locator);
+  return JSON.stringify(locator);
+}
+
+export function parseTaskEnvironmentLocator(raw: string): TaskEnvironmentLocator {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("task environment locator is not valid JSON");
+  }
+  return validateTaskEnvironmentLocator(parsed);
+}
+
+export function validateTaskEnvironmentLocator(
+  value: unknown,
+): TaskEnvironmentLocator {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("task environment locator must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).sort().join("\0") !==
+    ["provider", "schemaVersion", "value"].sort().join("\0")
+  ) {
+    throw new Error("task environment locator has unexpected fields");
+  }
+  if (record.schemaVersion !== TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION) {
+    throw new Error("unsupported task environment locator schema");
+  }
+  if (
+    typeof record.provider !== "string" ||
+    !/^[a-z][a-z0-9-]{0,63}$/.test(record.provider)
+  ) {
+    throw new Error("task environment locator provider is invalid");
+  }
+  assertJsonValue(record.value, 0);
+  return {
+    schemaVersion: TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+    provider: record.provider,
+    value: record.value,
+  };
+}
+
+function assertJsonValue(value: unknown, depth: number): void {
+  if (depth > 16) throw new Error("task environment locator is too deeply nested");
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("task environment locator contains a non-finite number");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 256) {
+      throw new Error("task environment locator array is too large");
+    }
+    for (const item of value) assertJsonValue(item, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length > 256) {
+      throw new Error("task environment locator object is too large");
+    }
+    for (const [key, item] of entries) {
+      if (key.includes("\0")) {
+        throw new Error("task environment locator key contains NUL");
+      }
+      assertJsonValue(item, depth + 1);
+    }
+    return;
+  }
+  throw new Error("task environment locator is not JSON-serializable");
+}

package/lib/task-identity.ts

@@ -0,0 +1,19 @@
+import { MAX_HOST_TASK_INVENTORY_TASK_ID_CHARS } from "../src/protocol";
+
+/** One identity grammar for inventory cursors and every orphan-GC path/label. */
+export const SAFE_HOST_TASK_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+export function isSafeHostTaskId(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_HOST_TASK_INVENTORY_TASK_ID_CHARS &&
+    SAFE_HOST_TASK_ID.test(value)
+  );
+}
+
+export function assertSafeHostTaskId(value: unknown): asserts value is string {
+  if (!isSafeHostTaskId(value)) {
+    throw new Error("invalid host task identity");
+  }
+}