@springbrand/agent-runtime 0.1.3-alpha.4 → 0.1.3-alpha.6

package/src/adapter/cloudflare/sandbox/adapter.ts

@@ -0,0 +1,1509 @@
+import {
+  ContainerUnavailableError,
+  getSandbox,
+  OperationInterruptedError,
+  parseSSEStream,
+  RPCTransportError,
+  type ExecEvent,
+  type ExecOptions,
+  type ExecResult,
+  type ProcessOptions,
+  type Sandbox,
+  type SessionOptions,
+  type StreamOptions,
+} from "@cloudflare/sandbox";
+import {
+  SandboxPortError,
+  type RuntimeSandboxPort,
+  type SandboxErrorCode,
+  type SandboxExecInput,
+  type SandboxExecResult,
+  type SandboxProcessLogs,
+  type SandboxProcessSummary,
+  type SandboxStartProcessInput,
+  type SandboxSyncFailure,
+  type SandboxSyncResult,
+  type WorkspacePort,
+} from "../../../kernel/bindings";
+import type {
+  WorkspaceFileVersion,
+  WorkspacePublishPort,
+} from "../workspace/publisher";
+import { SANDBOX_HOST_POLICY } from "./policy";
+
+const EXEC_SESSION_ID = "agent";
+const PROCESS_SESSION_ID = "agent-processes";
+const BACKGROUND_PROCESS_PREFIX = "ua-bg-";
+const HYDRATION_MARKER =
+  "/tmp/.universal-agent/workspace-hydrated.json";
+const WORKSPACE_PAGE_SIZE = 256;
+const OUTPUT_BYTES = SANDBOX_HOST_POLICY.maxOutputBytes;
+const MAX_PUBLISH_FILE_BYTES =
+  SANDBOX_HOST_POLICY.maxPublishFileBytes;
+const MAX_HYDRATION_MANIFEST_BYTES =
+  SANDBOX_HOST_POLICY.maxHydrationManifestBytes;
+const MAX_HYDRATION_MANIFEST_FILES =
+  SANDBOX_HOST_POLICY.maxHydrationFiles;
+const DEFAULT_EXEC_TIMEOUT_MS =
+  SANDBOX_HOST_POLICY.defaultExecTimeoutMs;
+const MAX_EXEC_TIMEOUT_MS =
+  SANDBOX_HOST_POLICY.maxExecTimeoutMs;
+const EXEC_SESSION_CLEANUP_TIMEOUT_MS = 5_000;
+const EXCLUDED_PUBLISH_SEGMENTS = new Set([
+  ".git",
+  ".venv",
+  "__pycache__",
+  "node_modules",
+]);
+
+type SandboxEvent =
+  | "sandbox.container.cold_start"
+  | "sandbox.workspace.pulled"
+  | "sandbox.workspace.published"
+  | "sandbox.process.started"
+  | "sandbox.process.stopped";
+
+export interface SandboxObserver {
+  emit(
+    event: SandboxEvent,
+    fields: Readonly<Record<string, string | number | boolean>>,
+  ): void;
+}
+
+export interface SandboxAdmission {
+  begin(operationId: string): Promise<{
+    granted: boolean;
+    reason?: "rate_limited" | "concurrency_limited";
+  }>;
+  end(operationId: string): Promise<void>;
+}
+
+interface SandboxFileEntry {
+  name: string;
+  absolutePath: string;
+  relativePath: string;
+  type: "file" | "directory" | "symlink" | "other";
+  size: number;
+}
+
+interface SandboxProcessLike {
+  id: string;
+  command: string;
+  status: string;
+  exitCode?: number;
+}
+
+interface HydrationManifest {
+  files: Map<string, WorkspaceFileVersion>;
+}
+
+interface SandboxSessionLike {
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  execStream?(
+    command: string,
+    options?: StreamOptions,
+  ): Promise<ReadableStream<Uint8Array>>;
+  startProcess(
+    command: string,
+    options?: ProcessOptions,
+  ): Promise<SandboxProcessLike>;
+}
+
+interface SandboxClientLike {
+  createSession(options: SessionOptions): Promise<SandboxSessionLike>;
+  getSession(id: string): Promise<SandboxSessionLike>;
+  deleteSession(id: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  mkdir(path: string): Promise<void>;
+  writeFile(
+    path: string,
+    content: string | ReadableStream<Uint8Array>,
+  ): Promise<void>;
+  readFileBytes(path: string): Promise<{
+    content: ReadableStream<Uint8Array>;
+    size: number;
+    mimeType: string;
+  }>;
+  deleteFile(path: string): Promise<void>;
+  listFiles(
+    path: string,
+    options?: { recursive?: boolean; includeHidden?: boolean },
+  ): Promise<readonly SandboxFileEntry[]>;
+  listProcesses(
+    sessionId: string,
+  ): Promise<readonly SandboxProcessLike[]>;
+  getProcess(
+    id: string,
+    sessionId: string,
+  ): Promise<SandboxProcessLike | null>;
+  getProcessLogs(id: string, sessionId: string): Promise<{
+    stdout: string;
+    stderr: string;
+  }>;
+  killProcess(id: string, sessionId: string): Promise<void>;
+  cleanupCompletedProcesses(sessionId: string): Promise<number>;
+  destroy(): Promise<void>;
+}
+
+type SandboxClientFactory = (
+  namespace: DurableObjectNamespace<Sandbox>,
+  sandboxId: string,
+) => SandboxClientLike;
+
+export interface CloudflareSandboxAdapterOptions {
+  sandboxNamespace: DurableObjectNamespace<Sandbox>;
+  sandboxId: string;
+  workspace: WorkspacePort;
+  publisher: WorkspacePublishPort;
+  admission?: SandboxAdmission;
+  observer?: SandboxObserver;
+  clientFactory?: SandboxClientFactory;
+}
+
+function sdkClientFactory(
+  namespace: DurableObjectNamespace<Sandbox>,
+  sandboxId: string,
+): SandboxClientLike {
+  const sandbox = getSandbox(namespace, sandboxId, {
+    transport: "rpc",
+    enableDefaultSession: false,
+    keepAlive: false,
+    normalizeId: true,
+  });
+
+  const wrapProcess = (process: {
+    id: string;
+    command: string;
+    status: string;
+    exitCode?: number;
+  }): SandboxProcessLike => ({
+    id: process.id,
+    command: process.command,
+    status: process.status,
+    ...(process.exitCode === undefined
+      ? {}
+      : { exitCode: process.exitCode }),
+  });
+
+  const wrapSession = (session: {
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execStream(
+      command: string,
+      options?: StreamOptions,
+    ): Promise<ReadableStream<Uint8Array>>;
+    startProcess(
+      command: string,
+      options?: ProcessOptions,
+    ): Promise<{
+      id: string;
+      command: string;
+      status: string;
+      exitCode?: number;
+    }>;
+  }): SandboxSessionLike => ({
+    exec: (command, options) => session.exec(command, options),
+    execStream: (command, options) =>
+      session.execStream(command, options),
+    startProcess: async (command, options) =>
+      wrapProcess(await session.startProcess(command, options)),
+  });
+
+  return {
+    createSession: async (options) =>
+      wrapSession(await sandbox.createSession(options)),
+    getSession: async (id) =>
+      wrapSession(await sandbox.getSession(id)),
+    deleteSession: async (id) => {
+      await sandbox.deleteSession(id);
+    },
+    exists: async (path) => (await sandbox.exists(path)).exists,
+    mkdir: async (path) => {
+      await sandbox.mkdir(path, { recursive: true });
+    },
+    writeFile: async (path, content) => {
+      await sandbox.writeFile(path, content);
+    },
+    readFileBytes: async (path) => {
+      const result = await sandbox.readFile(path, {
+        encoding: "none",
+      });
+      return {
+        content: result.content,
+        size: result.size,
+        mimeType: result.mimeType,
+      };
+    },
+    deleteFile: async (path) => {
+      await sandbox.deleteFile(path);
+    },
+    listFiles: async (path, options) => {
+      const result = await sandbox.listFiles(path, options);
+      return result.files.map((entry) => ({
+        name: entry.name,
+        absolutePath: entry.absolutePath,
+        relativePath: entry.relativePath,
+        type: entry.type,
+        size: entry.size,
+      }));
+    },
+    listProcesses: async (sessionId) =>
+      (await sandbox.listProcesses(sessionId)).map(wrapProcess),
+    getProcess: async (id, sessionId) => {
+      const process = await sandbox.getProcess(id, sessionId);
+      return process ? wrapProcess(process) : null;
+    },
+    getProcessLogs: async (id, sessionId) => {
+      const logs = await sandbox.getProcessLogs(id, sessionId);
+      return {
+        stdout: logs.stdout,
+        stderr: logs.stderr,
+      };
+    },
+    killProcess: async (id, sessionId) => {
+      await sandbox.killProcess(id, "SIGTERM", sessionId);
+    },
+    cleanupCompletedProcesses: (sessionId) =>
+      sandbox.cleanupCompletedProcesses(sessionId),
+    destroy: () => sandbox.destroy(),
+  };
+}
+
+function streamBytes(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+function normalizedPath(
+  value: string | undefined,
+  roots: readonly string[],
+  defaultPath: string,
+): string {
+  if (value === undefined || !value.trim()) return defaultPath;
+  if (value.includes("\0")) {
+    throw new SandboxPortError("invalid_path", "path contains a NUL byte");
+  }
+  const portable = value.trim().replaceAll("\\", "/");
+  const segments = portable.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new SandboxPortError(
+      "invalid_path",
+      "path traversal is not allowed",
+    );
+  }
+  const absolute = portable.startsWith("/")
+    ? `/${segments.join("/")}`
+    : `${defaultPath}/${segments.join("/")}`;
+  if (
+    !roots.some(
+      (root) => pathInside(root, absolute),
+    )
+  ) {
+    throw new SandboxPortError(
+      "invalid_path",
+      `path must be inside ${roots.join(" or ")}`,
+    );
+  }
+  return absolute;
+}
+
+function pathInside(root: string, path: string): boolean {
+  if (root === "/") return path.startsWith("/");
+  return path === root || path.startsWith(`${root}/`);
+}
+
+function canonicalPathInside(
+  path: string,
+  root: string,
+): string {
+  const normalized = normalizedPath(path, [root], root);
+  if (normalized !== path) {
+    throw new SandboxPortError(
+      "invalid_path",
+      `non-canonical path is not allowed: ${path}`,
+    );
+  }
+  return normalized;
+}
+
+function outputTail(value: string, limit = OUTPUT_BYTES): {
+  value: string;
+  truncated: boolean;
+} {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= limit) {
+    return { value, truncated: false };
+  }
+  const tail = new TextDecoder().decode(
+    encoded.slice(encoded.byteLength - limit),
+  );
+  return {
+    value: tail.startsWith("\uFFFD") ? tail.slice(1) : tail,
+    truncated: true,
+  };
+}
+
+function appendOutputTail(
+  current: string,
+  chunk: string,
+): { value: string; truncated: boolean } {
+  return outputTail(`${current}${chunk}`);
+}
+
+async function readBoundedStream(
+  stream: ReadableStream<Uint8Array>,
+  expectedBytes: number,
+  limit = MAX_PUBLISH_FILE_BYTES,
+  errorCode: SandboxErrorCode = "publish_too_large",
+): Promise<Uint8Array> {
+  if (expectedBytes > limit) {
+    throw new SandboxPortError(
+      errorCode,
+      `stream exceeds the ${limit}-byte transport limit`,
+    );
+  }
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel("stream transport limit exceeded");
+        throw new SandboxPortError(
+          errorCode,
+          `stream exceeds the ${limit}-byte transport limit`,
+        );
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function alreadyExists(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase();
+  return (
+    message.includes("session_already_exists") ||
+    message.includes("already exists")
+  );
+}
+
+function timedOut(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase();
+  return message.includes("timeout") || message.includes("timed out");
+}
+
+function mappedError(error: unknown): SandboxPortError {
+  if (error instanceof SandboxPortError) return error;
+  const message = errorMessage(error).toLowerCase();
+  let code: SandboxErrorCode = "operation_failed";
+  if (
+    error instanceof ContainerUnavailableError ||
+    message.includes("container unavailable")
+  ) {
+    code = message.includes("capacity")
+      ? "capacity_unavailable"
+      : "startup_failed";
+  } else if (
+    error instanceof RPCTransportError ||
+    error instanceof OperationInterruptedError
+  ) {
+    code = "startup_failed";
+  } else if (timedOut(error)) {
+    code = "timeout";
+  }
+  return new SandboxPortError(code, "Sandbox operation failed");
+}
+
+function workspaceToSandboxPath(
+  path: string,
+  root: "/" | "/shared",
+): string {
+  if (root === "/shared") {
+    return path === "/shared" ? "/shared" : path;
+  }
+  return path === "/" ? "/workspace" : `/workspace${path}`;
+}
+
+function sandboxToWorkspacePath(path: string): string {
+  if (path === "/workspace") return "/";
+  if (path.startsWith("/workspace/")) {
+    return path.slice("/workspace".length);
+  }
+  return path;
+}
+
+function parentPath(path: string): string {
+  const index = path.lastIndexOf("/");
+  return index <= 0 ? "/" : path.slice(0, index);
+}
+
+function syncFailure(
+  path: string,
+  error: unknown,
+): SandboxSyncFailure {
+  return {
+    path,
+    errorCode:
+      error instanceof SandboxPortError
+        ? error.code
+        : "operation_failed",
+  };
+}
+
+export class CloudflareSandboxAdapter implements RuntimeSandboxPort {
+  private readonly client: SandboxClientLike;
+  private readonly sessions = new Map<string, SandboxSessionLike>();
+  private hydration?: Promise<SandboxSyncResult>;
+  private manifest?: HydrationManifest;
+  private serial: Promise<void> = Promise.resolve();
+
+  constructor(private readonly options: CloudflareSandboxAdapterOptions) {
+    this.client = (
+      options.clientFactory ?? sdkClientFactory
+    )(options.sandboxNamespace, options.sandboxId);
+  }
+
+  async exec(
+    input: SandboxExecInput,
+    signal?: AbortSignal,
+  ): Promise<SandboxExecResult> {
+    signal?.throwIfAborted();
+    return this.withAdmission(() =>
+      this.enqueue(async () => {
+        await this.ensureHydrated();
+        const cwd = normalizedPath(
+          input.cwd,
+          ["/workspace", "/shared", "/tmp"],
+          "/workspace",
+        );
+        const timeout = Math.min(
+          Math.max(input.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS, 1),
+          MAX_EXEC_TIMEOUT_MS,
+        );
+        const session = await this.ensureSession(
+          EXEC_SESSION_ID,
+          "/workspace",
+          MAX_EXEC_TIMEOUT_MS,
+        );
+        let prepared:
+          | { command: string; env?: Record<string, string>; stdinPath?: string }
+          | undefined;
+        try {
+          prepared = await this.prepareCommand(input.command, input.stdin);
+          const command = prepared.command;
+          const execOptions = {
+            cwd,
+            timeout,
+            ...(prepared.env ? { env: prepared.env } : {}),
+          };
+          return await this.runForeground(signal, timeout, async () => {
+            if (session.execStream) {
+              return await this.execBounded(
+                session,
+                command,
+                execOptions,
+              );
+            }
+            const result = await session.exec(
+              command,
+              execOptions,
+            );
+            const stdout = outputTail(result.stdout);
+            const stderr = outputTail(result.stderr);
+            return {
+              success: result.success,
+              stdout: stdout.value,
+              stderr: stderr.value,
+              exitCode: result.exitCode,
+              stdoutTruncated: stdout.truncated,
+              stderrTruncated: stderr.truncated,
+            };
+          });
+        } catch (error) {
+          if (timedOut(error) || signal?.aborted) {
+            await this.deleteExecutionSession();
+          }
+          signal?.throwIfAborted();
+          throw mappedError(error);
+        } finally {
+          if (prepared?.stdinPath) {
+            await this.cleanupWithin(
+              this.client.deleteFile(prepared.stdinPath),
+            );
+          }
+        }
+      }),
+    );
+  }
+
+  async startProcess(
+    input: SandboxStartProcessInput,
+  ): Promise<SandboxProcessSummary> {
+    return this.withAdmission(() =>
+      this.enqueue(async () => {
+        await this.ensureHydrated();
+        const cwd = normalizedPath(
+          input.cwd,
+          ["/workspace", "/shared", "/tmp"],
+          "/workspace",
+        );
+        const session = await this.ensureSession(
+          PROCESS_SESSION_ID,
+          "/workspace",
+        );
+        let prepared:
+          | { command: string; env?: Record<string, string>; stdinPath?: string }
+          | undefined;
+        try {
+          const running = await this.pruneProcessesForStart();
+          if (
+            running.length >=
+            SANDBOX_HOST_POLICY.maxBackgroundProcesses
+          ) {
+            throw new SandboxPortError(
+              "capacity_unavailable",
+              "background process limit reached",
+            );
+          }
+          prepared = await this.prepareCommand(
+            input.command,
+            input.stdin,
+          );
+          const process = await session.startProcess(prepared.command, {
+            cwd,
+            autoCleanup: false,
+            processId:
+              `${BACKGROUND_PROCESS_PREFIX}${Date.now().toString(36)}-` +
+              crypto.randomUUID(),
+            ...(prepared.env ? { env: prepared.env } : {}),
+          });
+          this.emit("sandbox.process.started", { success: true });
+          return this.processSummary(process);
+        } catch (error) {
+          throw mappedError(error);
+        } finally {
+          if (prepared?.stdinPath) {
+            await this.client
+              .deleteFile(prepared.stdinPath)
+              .catch(() => undefined);
+          }
+        }
+      }),
+    );
+  }
+
+  async getProcessLogs(id: string): Promise<SandboxProcessLogs> {
+    return this.withAdmission(async () => {
+      await this.ensureHydrated();
+      this.assertProcessId(id);
+      try {
+        const process = await this.client.getProcess(
+          id,
+          PROCESS_SESSION_ID,
+        );
+        if (!process) {
+          throw new SandboxPortError(
+            "not_found",
+            "background process was not found",
+          );
+        }
+        if (this.processExpired(id)) {
+          await this.client
+            .killProcess(id, PROCESS_SESSION_ID)
+            .catch(() => undefined);
+          throw new SandboxPortError(
+            "not_found",
+            "background process lease expired",
+          );
+        }
+        const logs = await this.client.getProcessLogs(
+          id,
+          PROCESS_SESSION_ID,
+        );
+        const stdout = outputTail(logs.stdout);
+        const stderr = outputTail(logs.stderr);
+        return {
+          id,
+          stdout: stdout.value,
+          stderr: stderr.value,
+          stdoutTruncated: stdout.truncated,
+          stderrTruncated: stderr.truncated,
+        };
+      } catch (error) {
+        throw mappedError(error);
+      }
+    });
+  }
+
+  async stopProcess(id: string): Promise<{ stopped: boolean }> {
+    return this.withAdmission(async () => {
+      await this.ensureHydrated();
+      this.assertProcessId(id);
+      try {
+        const process = await this.client.getProcess(
+          id,
+          PROCESS_SESSION_ID,
+        );
+        if (!process) {
+          throw new SandboxPortError(
+            "not_found",
+            "background process was not found",
+          );
+        }
+        if (this.processExpired(id)) {
+          await this.client
+            .killProcess(id, PROCESS_SESSION_ID)
+            .catch(() => undefined);
+          throw new SandboxPortError(
+            "not_found",
+            "background process lease expired",
+          );
+        }
+        await this.client.killProcess(id, PROCESS_SESSION_ID);
+        this.emit("sandbox.process.stopped", { success: true });
+        return { stopped: true };
+      } catch (error) {
+        throw mappedError(error);
+      }
+    });
+  }
+
+  async publishFiles(
+    paths: readonly string[],
+  ): Promise<SandboxSyncResult> {
+    return this.withAdmission(() =>
+      this.enqueue(async () => {
+        await this.ensureHydrated();
+        const manifest = this.manifest;
+        if (!manifest) {
+          throw new SandboxPortError(
+            "workspace_hydration_failed",
+            "Sandbox hydration snapshot is unavailable",
+          );
+        }
+        const result: {
+          files: string[];
+          skipped: string[];
+          failed: SandboxSyncFailure[];
+          bytes: number;
+        } = {
+          files: [],
+          skipped: [],
+          failed: [],
+          bytes: 0,
+        };
+
+        const entries = new Map<string, SandboxFileEntry>();
+        for (const input of paths) {
+          const path = normalizedPath(
+            input,
+            ["/workspace"],
+            "/workspace",
+          );
+          let selected: readonly SandboxFileEntry[];
+          try {
+            await this.assertNoSymlinkComponents(path);
+            selected = await this.collectPublishEntries(path);
+          } catch (error) {
+            if (
+              error instanceof SandboxPortError &&
+              error.code === "invalid_path"
+            ) {
+              throw error;
+            }
+            result.failed.push(syncFailure(path, error));
+            continue;
+          }
+          for (const entry of selected) {
+            this.assertPublishEntry(path, entry);
+            if (entry.type === "symlink") {
+              throw new SandboxPortError(
+                "invalid_path",
+                `symbolic links cannot be published: ${entry.absolutePath}`,
+              );
+            }
+            if (this.isExcludedPublishPath(entry.absolutePath)) {
+              result.skipped.push(entry.absolutePath);
+            } else if (entry.type === "file") {
+              entries.set(entry.absolutePath, entry);
+            } else if (entry.type === "directory") {
+              // Parent directories are created by the persistent Workspace
+              // write. Empty directories are intentionally not persisted.
+            } else {
+              result.skipped.push(entry.absolutePath);
+            }
+          }
+        }
+
+        if (
+          entries.size > SANDBOX_HOST_POLICY.maxPublishFiles
+        ) {
+          throw new SandboxPortError(
+            "publish_limit_exceeded",
+            "publish selection exceeds the file-count limit",
+          );
+        }
+        const ordered = [...entries.values()].sort((left, right) =>
+          left.absolutePath.localeCompare(right.absolutePath),
+        );
+        let selectedBytes = 0;
+        for (const entry of ordered) {
+          if (entry.size > MAX_PUBLISH_FILE_BYTES) {
+            throw new SandboxPortError(
+              "publish_too_large",
+              `publish file exceeds the byte limit: ${entry.absolutePath}`,
+            );
+          }
+          selectedBytes += entry.size;
+          if (
+            selectedBytes >
+            SANDBOX_HOST_POLICY.maxPublishBytes
+          ) {
+            throw new SandboxPortError(
+              "publish_limit_exceeded",
+              "publish selection exceeds the total byte limit",
+            );
+          }
+        }
+
+        let manifestChanged = false;
+        for (const entry of ordered) {
+          const workspacePath = sandboxToWorkspacePath(
+            entry.absolutePath,
+          );
+          try {
+            const file = await this.client.readFileBytes(
+              entry.absolutePath,
+            );
+            const bytes = await readBoundedStream(
+              file.content,
+              file.size,
+            );
+            const written =
+              await this.options.publisher.writeFileBytesIfUnchanged(
+                workspacePath,
+                bytes,
+                file.mimeType,
+                manifest.files.get(entry.absolutePath) ?? null,
+              );
+            if (!written.written) {
+              result.failed.push({
+                path: entry.absolutePath,
+                errorCode: "workspace_conflict",
+              });
+              continue;
+            }
+            manifest.files.set(
+              entry.absolutePath,
+              written.version,
+            );
+            manifestChanged = true;
+            result.files.push(entry.absolutePath);
+            result.bytes += bytes.byteLength;
+          } catch (error) {
+            result.failed.push(
+              syncFailure(entry.absolutePath, error),
+            );
+          }
+        }
+        if (manifestChanged) {
+          await this.writeHydrationManifest(manifest);
+        }
+        const frozen = this.freezeSyncResult(result);
+        this.emit("sandbox.workspace.published", {
+          success: frozen.failed.length === 0,
+          files: frozen.files.length,
+          failed: frozen.failed.length,
+          bytes: frozen.bytes,
+        });
+        return frozen;
+      }),
+    );
+  }
+
+  async destroy(): Promise<void> {
+    await this.client.destroy();
+  }
+
+  private async withAdmission<T>(
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    const operationId = crypto.randomUUID();
+    const admission = this.options.admission;
+    if (admission) {
+      const decision = await admission.begin(operationId);
+      if (!decision.granted) {
+        throw new SandboxPortError(
+          decision.reason ?? "rate_limited",
+          "Sandbox operation admission limit reached",
+        );
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      if (admission) {
+        await admission.end(operationId).catch(() => undefined);
+      }
+    }
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const next = this.serial.then(operation, operation);
+    this.serial = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  }
+
+  private async ensureHydrated(): Promise<SandboxSyncResult> {
+    if (!this.hydration) {
+      this.hydration = (async () => {
+        try {
+          if (this.manifest) {
+            return this.freezeSyncResult({
+              files: [],
+              skipped: [],
+              failed: [],
+              bytes: 0,
+            });
+          }
+          const existing = await this.readHydrationManifest();
+          if (existing) {
+            this.manifest = existing;
+            return this.freezeSyncResult({
+              files: [],
+              skipped: [],
+              failed: [],
+              bytes: 0,
+            });
+          }
+          this.emit("sandbox.container.cold_start", {
+            markerMissing: true,
+          });
+          const result = await this.pullWorkspaceInternal();
+          if (result.failed.length > 0) {
+            throw new Error("Workspace hydration was partial");
+          }
+          this.emit("sandbox.workspace.pulled", {
+            success: true,
+            files: result.files.length,
+            skipped: result.skipped.length,
+            bytes: result.bytes,
+          });
+          return result;
+        } catch (error) {
+          throw new SandboxPortError(
+            "workspace_hydration_failed",
+            "persistent Workspace could not be copied into the Sandbox",
+          );
+        }
+      })().finally(() => {
+        this.hydration = undefined;
+      });
+    }
+    return this.hydration;
+  }
+
+  private async pullWorkspaceInternal(): Promise<SandboxSyncResult> {
+    const result: {
+      files: string[];
+      skipped: string[];
+      failed: SandboxSyncFailure[];
+      bytes: number;
+    } = {
+      files: [],
+      skipped: [],
+      failed: [],
+      bytes: 0,
+    };
+    const currentManifest: HydrationManifest = {
+      files: new Map(),
+    };
+    let visitedEntries = 0;
+    await this.client.mkdir("/workspace");
+    await this.client.mkdir("/shared");
+
+    for (const root of ["/", "/shared"] as const) {
+      const pending: string[] = [root];
+      while (pending.length > 0) {
+        const directory = pending.pop()!;
+        let offset = 0;
+        while (true) {
+          const entries = await this.options.workspace.readDir(
+            directory,
+            {
+              limit: WORKSPACE_PAGE_SIZE,
+              offset,
+            },
+          );
+          for (const entry of entries) {
+            visitedEntries += 1;
+            if (
+              visitedEntries >
+              SANDBOX_HOST_POLICY.maxHydrationEntries
+            ) {
+              throw new SandboxPortError(
+                "capacity_unavailable",
+                "Workspace hydration exceeds the traversal limit",
+              );
+            }
+            const sourcePath = canonicalPathInside(
+              entry.path,
+              root,
+            );
+            const destination = workspaceToSandboxPath(
+              sourcePath,
+              root,
+            );
+            if (entry.type === "symlink") {
+              result.skipped.push(destination);
+              continue;
+            }
+            if (entry.type === "directory") {
+              await this.client.mkdir(destination);
+              pending.push(sourcePath);
+              continue;
+            }
+            if (entry.size > MAX_PUBLISH_FILE_BYTES) {
+              result.skipped.push(destination);
+              continue;
+            }
+            if (
+              currentManifest.files.size >=
+              SANDBOX_HOST_POLICY.maxHydrationFiles
+            ) {
+              throw new SandboxPortError(
+                "capacity_unavailable",
+                "Workspace hydration exceeds the file-count limit",
+              );
+            }
+            if (
+              result.bytes + entry.size >
+              SANDBOX_HOST_POLICY.maxHydrationBytes
+            ) {
+              throw new SandboxPortError(
+                "capacity_unavailable",
+                "Workspace hydration exceeds the total byte limit",
+              );
+            }
+            const bytes =
+              await this.options.workspace.readFileBytes(sourcePath);
+            if (!bytes) {
+              result.failed.push({
+                path: destination,
+                errorCode: "operation_failed",
+              });
+              continue;
+            }
+            if (
+              bytes.byteLength > MAX_PUBLISH_FILE_BYTES ||
+              result.bytes + bytes.byteLength >
+                SANDBOX_HOST_POLICY.maxHydrationBytes
+            ) {
+              throw new SandboxPortError(
+                "capacity_unavailable",
+                "Workspace hydration exceeds the byte limit",
+              );
+            }
+            await this.client.mkdir(parentPath(destination));
+            await this.client.writeFile(
+              destination,
+              streamBytes(bytes),
+            );
+            currentManifest.files.set(destination, {
+              updatedAt: entry.updatedAt,
+              size: entry.size,
+            });
+            result.files.push(destination);
+            result.bytes += bytes.byteLength;
+          }
+          if (entries.length < WORKSPACE_PAGE_SIZE) break;
+          offset += entries.length;
+        }
+      }
+    }
+    if (result.failed.length === 0) {
+      await this.writeHydrationManifest(currentManifest);
+    }
+    return this.freezeSyncResult(result);
+  }
+
+  private async readHydrationManifest(): Promise<HydrationManifest | null> {
+    try {
+      if (!(await this.client.exists(HYDRATION_MARKER))) {
+        return null;
+      }
+      const file = await this.client.readFileBytes(HYDRATION_MARKER);
+      const bytes = await readBoundedStream(
+        file.content,
+        file.size,
+        MAX_HYDRATION_MANIFEST_BYTES,
+        "operation_failed",
+      );
+      const parsed: unknown = JSON.parse(
+        new TextDecoder().decode(bytes),
+      );
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        !("complete" in parsed) ||
+        parsed.complete !== true ||
+        !("files" in parsed) ||
+        !Array.isArray(parsed.files) ||
+        parsed.files.length > MAX_HYDRATION_MANIFEST_FILES
+      ) {
+        return null;
+      }
+      const files = new Map<string, WorkspaceFileVersion>();
+      for (const item of parsed.files) {
+        if (
+          typeof item !== "object" ||
+          item === null ||
+          !("path" in item) ||
+          typeof item.path !== "string" ||
+          !("updatedAt" in item) ||
+          typeof item.updatedAt !== "number" ||
+          !Number.isFinite(item.updatedAt) ||
+          !("size" in item) ||
+          typeof item.size !== "number" ||
+          !Number.isFinite(item.size) ||
+          item.size < 0
+        ) {
+          return null;
+        }
+        const root = pathInside("/shared", item.path)
+          ? "/shared"
+          : "/workspace";
+        files.set(canonicalPathInside(item.path, root), {
+          updatedAt: item.updatedAt,
+          size: item.size,
+        });
+      }
+      return { files };
+    } catch {
+      // A missing, invalid, oversized, or user-modified marker forces a fresh
+      // hydrate. It must never authorize broader file access.
+      return null;
+    }
+  }
+
+  private async writeHydrationManifest(
+    manifest: HydrationManifest,
+  ): Promise<void> {
+    const serialized = JSON.stringify({
+      complete: true,
+      files: [...manifest.files]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([path, version]) => ({ path, ...version })),
+    });
+    if (
+      new TextEncoder().encode(serialized).byteLength >
+      MAX_HYDRATION_MANIFEST_BYTES
+    ) {
+      throw new SandboxPortError(
+        "capacity_unavailable",
+        "Workspace hydration manifest exceeds the byte limit",
+      );
+    }
+    await this.client.mkdir(parentPath(HYDRATION_MARKER));
+    await this.client.writeFile(HYDRATION_MARKER, serialized);
+    this.manifest = { files: new Map(manifest.files) };
+  }
+
+  private async ensureSession(
+    id: string,
+    cwd: string,
+    commandTimeoutMs?: number,
+  ): Promise<SandboxSessionLike> {
+    const existing = this.sessions.get(id);
+    if (existing) return existing;
+    try {
+      const created = await this.client.createSession({
+        id,
+        cwd,
+        ...(commandTimeoutMs === undefined
+          ? {}
+          : { commandTimeoutMs }),
+      });
+      this.sessions.set(id, created);
+      return created;
+    } catch (error) {
+      if (!alreadyExists(error)) throw mappedError(error);
+      const session = await this.client.getSession(id);
+      this.sessions.set(id, session);
+      return session;
+    }
+  }
+
+  private async runForeground<T>(
+    signal: AbortSignal | undefined,
+    timeoutMs: number,
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    signal?.throwIfAborted();
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+    // The SDK timeout cannot settle a stalled SSE transport, so the Host
+    // independently bounds how long a Runtime turn can wait for it.
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timeout = setTimeout(
+        () =>
+          reject(
+            new SandboxPortError(
+              "timeout",
+              "Sandbox execution exceeded its deadline",
+            ),
+          ),
+        timeoutMs,
+      );
+    });
+    const interrupted = new Promise<never>((_resolve, reject) => {
+      if (!signal) return;
+      onAbort = () => {
+        reject(
+          signal.reason ?? new DOMException("Aborted", "AbortError"),
+        );
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+      return await Promise.race([
+        operation(),
+        deadline,
+        interrupted,
+      ]);
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+      if (signal && onAbort) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  }
+
+  private async deleteExecutionSession(): Promise<void> {
+    this.sessions.delete(EXEC_SESSION_ID);
+    await this.cleanupWithin(
+      this.client.deleteSession(EXEC_SESSION_ID),
+    );
+  }
+
+  private async cleanupWithin(operation: Promise<unknown>): Promise<void> {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        operation.catch(() => undefined),
+        new Promise<void>((resolve) => {
+          timeout = setTimeout(
+            resolve,
+            EXEC_SESSION_CLEANUP_TIMEOUT_MS,
+          );
+        }),
+      ]);
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+    }
+  }
+
+  private async execBounded(
+    session: SandboxSessionLike,
+    command: string,
+    options: StreamOptions,
+  ): Promise<SandboxExecResult> {
+    const stream = await session.execStream!(command, options);
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let exitCode: number | undefined;
+    for await (const event of parseSSEStream<ExecEvent>(stream)) {
+      if (event.type === "stdout" && event.data) {
+        const next = appendOutputTail(stdout, event.data);
+        stdout = next.value;
+        stdoutTruncated ||= next.truncated;
+      } else if (event.type === "stderr" && event.data) {
+        const next = appendOutputTail(stderr, event.data);
+        stderr = next.value;
+        stderrTruncated ||= next.truncated;
+      } else if (event.type === "complete") {
+        exitCode = event.exitCode ?? event.result?.exitCode;
+      } else if (event.type === "error") {
+        throw new Error(event.error ?? event.data ?? "command failed");
+      }
+    }
+    if (exitCode === undefined) {
+      throw new Error("streaming command ended without an exit code");
+    }
+    return {
+      success: exitCode === 0,
+      stdout,
+      stderr,
+      exitCode,
+      stdoutTruncated,
+      stderrTruncated,
+    };
+  }
+
+  private async prepareCommand(
+    command: string,
+    stdin?: string,
+  ): Promise<{
+    command: string;
+    env?: Record<string, string>;
+    stdinPath?: string;
+  }> {
+    if (stdin === undefined) return { command };
+    const stdinPath =
+      `/tmp/.universal-agent/stdin-${crypto.randomUUID()}`;
+    await this.client.mkdir(parentPath(stdinPath));
+    await this.client.writeFile(
+      stdinPath,
+      streamBytes(new TextEncoder().encode(stdin)),
+    );
+    return {
+      command:
+        `sh -lc "$UA_SANDBOX_COMMAND" < ${stdinPath}`,
+      env: { UA_SANDBOX_COMMAND: command },
+      stdinPath,
+    };
+  }
+
+  private processSummary(
+    process: SandboxProcessLike,
+  ): SandboxProcessSummary {
+    return {
+      id: process.id,
+      command: process.command,
+      status: process.status,
+      ...(process.exitCode === undefined
+        ? {}
+        : { exitCode: process.exitCode }),
+    };
+  }
+
+  private assertProcessId(id: string): void {
+    if (this.processStartedAt(id) === null) {
+      throw new SandboxPortError(
+        "not_found",
+        "background process was not found",
+      );
+    }
+  }
+
+  private processStartedAt(id: string): number | null {
+    if (!id.startsWith(BACKGROUND_PROCESS_PREFIX)) return null;
+    const token = id
+      .slice(BACKGROUND_PROCESS_PREFIX.length)
+      .split("-", 1)[0];
+    if (!token) return null;
+    const startedAt = Number.parseInt(token, 36);
+    return Number.isSafeInteger(startedAt) && startedAt > 0
+      ? startedAt
+      : null;
+  }
+
+  private processExpired(id: string): boolean {
+    const startedAt = this.processStartedAt(id);
+    return (
+      startedAt === null ||
+      Date.now() - startedAt >
+        SANDBOX_HOST_POLICY.maxBackgroundProcessAgeMs
+    );
+  }
+
+  private async pruneProcessesForStart(): Promise<
+    readonly SandboxProcessLike[]
+  > {
+    await this.client
+      .cleanupCompletedProcesses(PROCESS_SESSION_ID)
+      .catch(() => undefined);
+    const now = Date.now();
+    const running: SandboxProcessLike[] = [];
+    for (const process of await this.client.listProcesses(
+      PROCESS_SESSION_ID,
+    )) {
+      const startedAt = this.processStartedAt(process.id);
+      if (startedAt === null || process.status !== "running") continue;
+      if (
+        now - startedAt >
+        SANDBOX_HOST_POLICY.maxBackgroundProcessAgeMs
+      ) {
+        await this.client
+          .killProcess(process.id, PROCESS_SESSION_ID)
+          .catch(() => undefined);
+        continue;
+      }
+      running.push(process);
+    }
+    return running;
+  }
+
+  private async assertNoSymlinkComponents(
+    path: string,
+  ): Promise<void> {
+    const root = pathInside("/shared", path)
+      ? "/shared"
+      : "/workspace";
+    if (path === root) return;
+
+    const segments = path.slice(root.length + 1).split("/");
+    let parent = root;
+    for (const segment of segments) {
+      const current = `${parent}/${segment}`;
+      const siblings = await this.client.listFiles(parent, {
+        includeHidden: true,
+      });
+      const entry = siblings.find(
+        (candidate) => candidate.absolutePath === current,
+      );
+      if (!entry) return;
+      this.assertPublishEntry(current, entry);
+      if (entry.type === "symlink") {
+        throw new SandboxPortError(
+          "invalid_path",
+          `symbolic links cannot be published: ${current}`,
+        );
+      }
+      if (current !== path && entry.type !== "directory") {
+        throw new SandboxPortError(
+          "not_found",
+          `Sandbox path was not found: ${path}`,
+        );
+      }
+      parent = current;
+    }
+  }
+
+  private assertPublishEntry(
+    selectedPath: string,
+    entry: SandboxFileEntry,
+  ): void {
+    const root = pathInside("/shared", selectedPath)
+      ? "/shared"
+      : "/workspace";
+    const absolutePath = canonicalPathInside(
+      entry.absolutePath,
+      root,
+    );
+    if (!pathInside(selectedPath, absolutePath)) {
+      throw new SandboxPortError(
+        "invalid_path",
+        `Sandbox listed a path outside the explicit publish selection: ${entry.absolutePath}`,
+      );
+    }
+  }
+
+  private async collectPublishEntries(
+    path: string,
+  ): Promise<readonly SandboxFileEntry[]> {
+    let selected: SandboxFileEntry | undefined;
+    if (path !== "/workspace") {
+      selected = (
+        await this.client.listFiles(parentPath(path), {
+          includeHidden: true,
+        })
+      ).find((candidate) => candidate.absolutePath === path);
+      if (!selected) {
+        throw new SandboxPortError(
+          "not_found",
+          `Sandbox path was not found: ${path}`,
+        );
+      }
+      if (selected.type !== "directory") return [selected];
+    }
+
+    const files: SandboxFileEntry[] = [];
+    const pending = [path];
+    let visitedEntries = 0;
+    while (pending.length > 0) {
+      const directory = pending.pop()!;
+      const children = await this.client.listFiles(directory, {
+        recursive: false,
+        includeHidden: true,
+      });
+      for (const child of children) {
+        this.assertPublishEntry(path, child);
+        visitedEntries += 1;
+        if (
+          visitedEntries >
+          SANDBOX_HOST_POLICY.maxPublishEntries
+        ) {
+          throw new SandboxPortError(
+            "publish_limit_exceeded",
+            "publish selection exceeds the traversal limit",
+          );
+        }
+        if (child.type === "directory") {
+          if (!this.isExcludedPublishPath(child.absolutePath)) {
+            pending.push(child.absolutePath);
+          }
+          files.push(child);
+          continue;
+        }
+        files.push(child);
+      }
+    }
+    return selected ? [selected, ...files] : files;
+  }
+
+  private isExcludedPublishPath(path: string): boolean {
+    return path
+      .slice("/workspace".length)
+      .split("/")
+      .filter(Boolean)
+      .some((segment) => EXCLUDED_PUBLISH_SEGMENTS.has(segment));
+  }
+
+  private freezeSyncResult(input: {
+    files: readonly string[];
+    skipped: readonly string[];
+    failed: readonly SandboxSyncFailure[];
+    bytes: number;
+  }): SandboxSyncResult {
+    return Object.freeze({
+      files: Object.freeze([...input.files]),
+      skipped: Object.freeze([...input.skipped]),
+      failed: Object.freeze(
+        input.failed.map((failure) => Object.freeze({ ...failure })),
+      ),
+      bytes: input.bytes,
+    });
+  }
+
+  private emit(
+    event: SandboxEvent,
+    fields: Readonly<Record<string, string | number | boolean>>,
+  ): void {
+    try {
+      this.options.observer?.emit(event, fields);
+    } catch {
+      // Observability must never overturn a completed Sandbox operation.
+    }
+  }
+}
+
+export function createCloudflareSandboxAdapter(
+  options: Omit<CloudflareSandboxAdapterOptions, "clientFactory">,
+): CloudflareSandboxAdapter {
+  return new CloudflareSandboxAdapter(options);
+}