@agen-ai/sandbox-docker 0.0.0-stage → 0.4.4

package/dist/resources/owner.js

@@ -0,0 +1,313 @@
+import { z } from "zod/v4";
+import { SandboxOperationError, SandboxStateError, SandboxUnsupportedError, parseSandboxGuestPath, parseSandboxRecoveryRecord } from "@agen-ai/sandbox";
+import { createSandboxSpillStore, verifySandboxSpillDirectory } from "@agen-ai/sandbox/node";
+import { DOCKER_API } from "../policy/config.js";
+import { assertDockerController, assertDockerPolicy, verifyDaemon, verifyDatasetImages, verifyImage } from "../policy/preflight.js";
+import { dockerProfile } from "../policy/profiles.js";
+import { containerBody, verifyContainer } from "../policy/container.js";
+import { newRecoveryRecord, resourceLabels } from "../recovery/identity.js";
+import { importWorkspace } from "../workspace/imports.js";
+import { exportWorkspace } from "../workspace/exports.js";
+import { DockerProcessOwner } from "../process/owner.js";
+import { MAX_DATASET_ATTACHMENTS } from "../datasets/configuration.js";
+import { hasUnexpectedImageMountWarnings } from "../datasets/warnings.js";
+import { inspectResource } from "./inspect.js";
+const containerCreatedSchema = z.object({ Id: z.string().regex(/^[a-f0-9]{64}$/u), Warnings: z.array(z.string()).max(MAX_DATASET_ATTACHMENTS).nullable().optional() });
+const volumeCreatedSchema = z.object({ Name: z.string() });
+const networkCreatedSchema = z.object({ Id: z.string().regex(/^[a-f0-9]{64}$/u), Warning: z.string().optional() });
+class DockerResourceOwner {
+  constructor(api, config, request, record) {
+    this.api = api;
+    this.config = config;
+    this.request = request;
+    if (record) this.current = record;
+    else if (request) this.current = newRecoveryRecord(config, request);
+    else throw new SandboxStateError("Docker resource ownership needs a request or verified recovery record.");
+  }
+  current;
+  closed = false;
+  startActual;
+  stopActual;
+  destroyActual;
+  checkpoint;
+  checkpointTail = Promise.resolve();
+  returnedIds = /* @__PURE__ */ new Map();
+  createEffects = /* @__PURE__ */ new Map();
+  absent = /* @__PURE__ */ new Set();
+  process;
+  get id() {
+    return this.current.sandboxId;
+  }
+  get recoveryRecord() {
+    return this.current;
+  }
+  start(options) {
+    if (this.startActual || !this.request) return Promise.reject(new SandboxStateError("Docker resource startup is once-only."));
+    this.checkpoint = options.checkpoint;
+    this.startActual = this.acquire(this.request.policy, options);
+    return this.startActual;
+  }
+  async acquire(policy, options) {
+    assertDockerPolicy(policy);
+    this.assertOpen(options.signal);
+    assertDockerController(this.config);
+    await verifySandboxSpillDirectory(this.config.spillDirectory, { signal: options.signal });
+    this.assertOpen(options.signal);
+    const backendIdentity = await verifyDaemon(this.api, this.config, options.signal);
+    await verifyImage(this.api, this.config, options.signal);
+    await verifyDatasetImages(this.api, this.config, options.signal);
+    this.assertOpen(options.signal);
+    await this.publish({ ...this.current, phase: "starting", authority: { kind: "verified", backendIdentity } });
+    const storage = await this.createResource("storage", options.signal, async (resource) => {
+      const result = await this.api.json(
+        "POST",
+        `${DOCKER_API}/volumes/create`,
+        volumeCreatedSchema,
+        { body: { Name: resource.name, Driver: "local", Labels: resourceLabels(this.current, "storage") } }
+      );
+      return { id: result.Name };
+    });
+    const network = policy.network.kind === "outbound" ? await this.createResource("network", options.signal, async (resource) => {
+      const result = await this.api.json("POST", `${DOCKER_API}/networks/create`, networkCreatedSchema, { body: {
+        Name: resource.name,
+        Driver: "bridge",
+        Internal: false,
+        Attachable: false,
+        Ingress: false,
+        EnableIPv6: false,
+        CheckDuplicate: true,
+        Labels: resourceLabels(this.current, "network")
+      } });
+      return { id: result.Id, warning: Boolean(result.Warning) };
+    }) : void 0;
+    const platform = `linux/${dockerProfile(this.config.profile).imageArchitecture}`;
+    const createContainer = (role) => this.createResource(role, options.signal, async (resource) => {
+      const result = await this.api.json(
+        "POST",
+        `${DOCKER_API}/containers/create?name=${encodeURIComponent(resource.name)}&platform=${encodeURIComponent(platform)}`,
+        containerCreatedSchema,
+        { body: containerBody(this.config, this.current, policy, role, storage.id, network?.id) }
+      );
+      return {
+        id: result.Id,
+        warning: hasUnexpectedImageMountWarnings(result.Warnings ?? [], role === "compute" ? this.config.datasets.length : 0)
+      };
+    }, (inspection) => {
+      if (!inspection.container) throw new SandboxStateError("Docker did not inspect the created container.");
+      verifyContainer(inspection.container, this.config, policy, role, storage.id, network?.id, false);
+    });
+    const compute = await createContainer("compute");
+    await createContainer("export");
+    this.assertOpen(options.signal);
+    await this.assertAuthority(options.signal);
+    await importWorkspace(this.api, compute.id, (async function* () {
+    })(), this.config.user, {
+      signal: options.signal ?? new AbortController().signal,
+      buffers: policy.transfers,
+      quotas: {}
+    });
+    this.assertOpen(options.signal);
+    await this.assertAuthority(options.signal);
+    await this.api.request("POST", `${DOCKER_API}/containers/${compute.id}/start`, { signal: options.signal });
+    this.assertOpen(options.signal);
+    const running = await inspectResource(this.api, this.current, this.resource("compute"), compute.id, options.signal);
+    if (!running?.container) throw new SandboxStateError("Docker workload disappeared during startup.");
+    verifyContainer(running.container, this.config, policy, "compute", storage.id, network?.id, true);
+    await this.publish({ ...this.current, phase: "running" });
+    this.assertOpen(options.signal);
+    return Object.freeze({
+      effective: Object.freeze({
+        backendIdentity,
+        isolation: "container",
+        resources: policy.resources,
+        temporaryStorage: policy.temporaryStorage,
+        network: policy.network,
+        nonRoot: true,
+        readOnlyRoot: true,
+        workspaceDiskQuota: Object.freeze({ kind: "not_requested" })
+      }),
+      workspace: parseSandboxGuestPath("/workspace/work"),
+      openSpill: (operation) => createSandboxSpillStore({ directory: this.config.spillDirectory, signal: operation?.signal }),
+      importTree: (entries, operation) => this.importTree(entries, operation),
+      reserveProcess: (spec) => {
+        this.assertOpen();
+        if (this.process) throw new SandboxStateError("Docker admits only one process reservation.");
+        this.process = new DockerProcessOwner(this.api, this.config, compute.id, spec, policy, async (signal) => {
+          this.assertOpen(signal);
+          await this.assertAuthority(signal);
+          await this.requirePresent("compute", signal);
+          this.assertOpen(signal);
+        }, () => this.stop());
+        return this.process;
+      },
+      exportTree: (selection, consume, operation) => this.exportTree(selection, consume, operation, policy, storage.id, network?.id)
+    });
+  }
+  async importTree(entries, options) {
+    this.assertOpen(options.signal);
+    await this.assertAuthority(options.signal);
+    const compute = await this.requirePresent("compute", options.signal);
+    this.assertOpen(options.signal);
+    return importWorkspace(this.api, compute.id, entries, this.config.user, options);
+  }
+  async exportTree(selection, consume, options, policy, storageId, networkId) {
+    await this.assertAuthority(options.signal);
+    if (await this.resolveResource("compute", options.signal)) throw new SandboxStateError("Workspace export requires exact compute absence.");
+    await this.requirePresent("storage", options.signal);
+    const accessor = await this.requirePresent("export", options.signal);
+    if (!accessor.container) throw new SandboxStateError("Workspace export requires the exact archive accessor.");
+    verifyContainer(accessor.container, this.config, policy, "export", storageId, networkId, false);
+    return exportWorkspace(this.api, accessor.id, selection, consume, options);
+  }
+  async createResource(role, signal, create, validate) {
+    this.assertOpen(signal);
+    await this.assertAuthority(signal);
+    await this.updateIdentity(role, { kind: "creating" });
+    this.assertOpen(signal);
+    const effect = create(this.resource(role)).then((created) => {
+      this.returnedIds.set(role, created.id);
+      return created;
+    });
+    this.createEffects.set(role, effect);
+    const { id, warning } = await effect;
+    if (warning) throw new SandboxUnsupportedError("Docker warned while creating the requested resource.");
+    const resource = this.resource(role);
+    const inspection = await inspectResource(this.api, this.current, resource, id);
+    if (!inspection || inspection.id !== id) throw new SandboxStateError("Docker did not confirm the exact created resource ID.");
+    validate?.(inspection);
+    await this.updateIdentity(role, { kind: "identified", id, fingerprint: inspection.fingerprint });
+    this.assertOpen(signal);
+    return inspection;
+  }
+  stop() {
+    this.closed = true;
+    this.process?.closeAdmission();
+    this.stopActual ??= this.cleanupCompute().catch((error) => {
+      this.stopActual = void 0;
+      throw error;
+    });
+    return this.stopActual;
+  }
+  async cleanupCompute() {
+    this.cleanupPhase("stopping");
+    const entered = this.createEffects.get("compute");
+    if (entered || !this.request) {
+      try {
+        await this.deleteResource("compute");
+      } catch (error) {
+        if (!entered) throw error;
+      }
+      await entered?.catch(() => {
+      });
+      if (!this.absent.has("compute")) await this.deleteResource("compute");
+    }
+    await this.process?.computeStopped();
+    this.cleanupPhase("stopped");
+    await this.checkpointTail;
+  }
+  destroy() {
+    this.closed = true;
+    this.destroyActual ??= this.cleanupAll().catch((error) => {
+      this.destroyActual = void 0;
+      throw error;
+    });
+    return this.destroyActual;
+  }
+  async cleanupAll() {
+    const failures = [];
+    try {
+      await this.stop();
+    } catch (error) {
+      failures.push(error);
+    }
+    this.cleanupPhase("destroying");
+    for (const role of ["export", "storage", "network"]) {
+      if (!this.current.resources.some((resource) => resource.role === role)) continue;
+      try {
+        await this.deleteResource(role);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length) {
+      await this.checkpointTail;
+      throw new AggregateError(failures, "Docker cleanup retains unresolved resource ownership.");
+    }
+    this.cleanupPhase("destroyed");
+    await this.checkpointTail;
+  }
+  async resolveResource(role, signal) {
+    const resource = this.resource(role);
+    if (resource.identity.kind === "planned") return void 0;
+    if (this.request !== void 0 && !this.createEffects.has(role)) return void 0;
+    const reference = resource.identity.kind === "identified" ? resource.identity.id : this.returnedIds.get(role) ?? resource.name;
+    const inspection = await inspectResource(this.api, this.current, resource, reference, signal);
+    if (!inspection && resource.identity.kind === "creating") {
+      throw new SandboxStateError("Docker acquisition entered without a settled resource identity; an absent name cannot prove absence.");
+    }
+    if (inspection && resource.identity.kind === "creating") {
+      this.publishCleanup({ ...this.current, resources: this.current.resources.map((candidate) => candidate.role === role ? {
+        ...candidate,
+        identity: { kind: "identified", id: inspection.id, fingerprint: inspection.fingerprint }
+      } : candidate) });
+    }
+    return inspection;
+  }
+  async requirePresent(role, signal) {
+    const inspection = await this.resolveResource(role, signal);
+    if (!inspection) throw new SandboxStateError("The exact Docker resource is absent.");
+    return inspection;
+  }
+  async deleteResource(role) {
+    if (this.absent.has(role) || this.resource(role).identity.kind === "planned") return;
+    await this.assertAuthority();
+    const inspection = await this.resolveResource(role);
+    if (!inspection) {
+      this.absent.add(role);
+      return;
+    }
+    const id = encodeURIComponent(inspection.id);
+    const path = role === "compute" || role === "export" ? `${DOCKER_API}/containers/${id}?force=true&v=false` : role === "storage" ? `${DOCKER_API}/volumes/${id}` : `${DOCKER_API}/networks/${id}`;
+    await this.api.request("DELETE", path, { statuses: [204, 404] });
+    const remaining = await this.resolveResource(role);
+    if (remaining) throw new SandboxStateError("Docker acknowledged removal but the exact resource remains present.");
+    this.absent.add(role);
+  }
+  resource(role) {
+    const resource = this.current.resources.find((candidate) => candidate.role === role);
+    if (!resource) throw new SandboxStateError("Docker recovery record omits an owned resource role.");
+    return resource;
+  }
+  updateIdentity(role, identity) {
+    const next = { ...this.current, resources: this.current.resources.map((resource) => resource.role === role ? { ...resource, identity } : resource) };
+    return this.publish(next);
+  }
+  cleanupPhase(phase) {
+    if (this.current.authority.kind === "verified") this.publishCleanup({ ...this.current, phase });
+  }
+  publishCleanup(record) {
+    this.current = parseSandboxRecoveryRecord(record);
+    this.submitCheckpoint(this.current);
+  }
+  async publish(record) {
+    this.current = parseSandboxRecoveryRecord(record);
+    await this.submitCheckpoint(this.current);
+  }
+  submitCheckpoint(record) {
+    const writing = this.checkpoint?.(record) ?? Promise.resolve();
+    this.checkpointTail = Promise.allSettled([this.checkpointTail, writing]).then(() => {
+    });
+    return writing;
+  }
+  async assertAuthority(signal) {
+    if (this.current.authority.kind !== "verified" || await verifyDaemon(this.api, this.config, signal) !== this.current.authority.backendIdentity) {
+      throw new SandboxStateError("Docker resource operations cannot act on a different or unverified daemon.");
+    }
+  }
+  assertOpen(signal) {
+    if (this.closed || signal?.aborted) throw new SandboxOperationError("cancelled", "Docker sandbox admission is closed.");
+  }
+}
+export {
+  DockerResourceOwner
+};

package/dist/workspace/exports.d.ts

@@ -0,0 +1,5 @@
+import type { SandboxExportConsumer, SandboxInputTreeSelection, SandboxTransferSummary } from '@agen-ai/sandbox';
+import type { SandboxDriverTransferOptions } from '@agen-ai/sandbox/backend';
+import type { DockerApi } from '../resources/api.js';
+export declare function exportWorkspace(api: DockerApi, containerId: string, selection: SandboxInputTreeSelection, consume: SandboxExportConsumer, options: SandboxDriverTransferOptions): Promise<SandboxTransferSummary>;
+//# sourceMappingURL=exports.d.ts.map

package/dist/workspace/exports.js

@@ -0,0 +1,52 @@
+import { DOCKER_API } from "../policy/config.js";
+import { ARCHIVE_ROOT, ARCHIVE_WORK, unsafeArchive, workspaceName } from "./paths.js";
+import { pathStat, requireStat } from "./stat.js";
+import { exportSelectedPath } from "./selected.js";
+import { readTar } from "./tar/decode.js";
+async function workspace(api, containerId, consume, options) {
+  let root = false;
+  let work = false;
+  const result = await api.stream(
+    "GET",
+    `${DOCKER_API}/containers/${containerId}/archive?path=%2Fworkspace`,
+    { signal: options.signal, chunkBytes: options.buffers.chunkBytes },
+    async (response) => {
+      requireStat(pathStat(response), "/workspace", "directory");
+      const summary = await readTar(response.body, async (entry) => {
+        const path = workspaceName(entry.path, entry.kind === "directory");
+        if (path === ARCHIVE_ROOT) {
+          if (root) unsafeArchive("duplicate workspace root.");
+          root = true;
+        } else if (path === ARCHIVE_WORK) {
+          if (work) unsafeArchive("duplicate work root.");
+          work = true;
+        } else {
+          const relative = path.slice(ARCHIVE_WORK.length + 1);
+          await consume(entry.kind === "directory" ? { kind: "directory", path: relative } : { kind: "file", path: relative, byteLength: entry.size, executable: (entry.mode & 73) !== 0, bytes: entry.body }, { signal: options.signal });
+        }
+      }, { signal: options.signal, chunkBytes: options.buffers.chunkBytes, limitCode: "output_limit", maxArchiveBytes: options.quotas.maxArchiveBytes });
+      if (!root || !work) unsafeArchive("both fixed workspace directory records are required.");
+      return { ...summary, directories: summary.directories - 2n };
+    }
+  );
+  return result.value;
+}
+async function exportWorkspace(api, containerId, selection, consume, options) {
+  if (selection.kind === "workspace") return workspace(api, containerId, consume, options);
+  if (selection.kind === "subtree") return exportSelectedPath(api, containerId, selection.path, "directory", consume, options, options.quotas.maxArchiveBytes);
+  let files = 0n;
+  let payloadBytes = 0n;
+  let archiveBytes = 0n;
+  for await (const path of selection.paths) {
+    options.signal.throwIfAborted();
+    const remaining = options.quotas.maxArchiveBytes === void 0 ? void 0 : options.quotas.maxArchiveBytes - archiveBytes;
+    const result = await exportSelectedPath(api, containerId, path, "file", consume, options, remaining);
+    files += result.files;
+    payloadBytes += result.payloadBytes;
+    archiveBytes += result.archiveBytes;
+  }
+  return Object.freeze({ files, directories: 0n, payloadBytes, archiveBytes });
+}
+export {
+  exportWorkspace
+};

package/dist/workspace/imports.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxInputTreeEntry, SandboxTransferSummary } from '@agen-ai/sandbox';
+import type { SandboxDriverTransferOptions } from '@agen-ai/sandbox/backend';
+import type { DockerApi } from '../resources/api.js';
+export declare function importWorkspace(api: DockerApi, containerId: string, entries: AsyncIterable<SandboxInputTreeEntry>, user: Readonly<{
+    uid: number;
+    gid: number;
+}>, options: SandboxDriverTransferOptions): Promise<SandboxTransferSummary>;
+//# sourceMappingURL=imports.d.ts.map

package/dist/workspace/imports.js

@@ -0,0 +1,49 @@
+import { SandboxOperationError } from "@agen-ai/sandbox";
+import { DOCKER_API } from "../policy/config.js";
+import { writeTar } from "./tar/encode.js";
+async function importWorkspace(api, containerId, entries, user, options) {
+  let files = 0n;
+  let directories = 0n;
+  let payloadBytes = 0n;
+  const source = async function* (signal) {
+    const directory = (path) => ({ ...user, path, kind: "directory", size: 0, mode: 448 });
+    yield directory("work");
+    for await (const entry of entries) {
+      signal.throwIfAborted();
+      const parts = entry.path.split("/");
+      const parentCount = entry.kind === "directory" ? parts.length : parts.length - 1;
+      for (let count = 1; count <= parentCount; count += 1) yield directory(`work/${parts.slice(0, count).join("/")}`);
+      if (entry.kind === "directory") {
+        directories += 1n;
+        continue;
+      }
+      files += 1n;
+      payloadBytes += BigInt(entry.byteLength);
+      const body = async function* () {
+        yield* entry.open({ signal });
+      };
+      yield { ...user, path: `work/${entry.path}`, kind: "file", size: entry.byteLength, mode: entry.executable ? 448 : 384, body: body() };
+    }
+  };
+  const result = await api.stream("PUT", `${DOCKER_API}/containers/${containerId}/archive?path=%2Fworkspace&noOverwriteDirNonDir=true`, {
+    signal: options.signal,
+    chunkBytes: options.buffers.chunkBytes,
+    contentType: "application/x-tar",
+    body: (signal) => writeTar(source(signal), {
+      signal,
+      chunkBytes: options.buffers.chunkBytes,
+      limitCode: "input_limit",
+      maxArchiveBytes: options.quotas.maxArchiveBytes
+    })
+  }, async ({ body }) => {
+    let bytes = 0;
+    for await (const chunk of body) {
+      bytes += chunk.length;
+      if (bytes > 64 * 1024) throw new SandboxOperationError("driver_failure", "Docker archive acknowledgement exceeds its control-response bound.");
+    }
+  });
+  return Object.freeze({ files, directories, payloadBytes, archiveBytes: result.uploadedBytes });
+}
+export {
+  importWorkspace
+};

package/dist/workspace/paths.d.ts

@@ -0,0 +1,8 @@
+import { SandboxOperationError } from '@agen-ai/sandbox';
+export declare const ARCHIVE_ROOT = "workspace";
+export declare const ARCHIVE_WORK = "workspace/work";
+export declare function archiveError(message: string): SandboxOperationError;
+export declare function unsafeArchive(message: string): never;
+export declare function archiveName(name: string, directory: boolean): string;
+export declare function workspaceName(name: string, directory: boolean): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/workspace/paths.js

@@ -0,0 +1,39 @@
+import { SANDBOX_LIMITS, SandboxOperationError, parseSandboxRelativePath } from "@agen-ai/sandbox";
+const ARCHIVE_ROOT = "workspace";
+const ARCHIVE_WORK = `${ARCHIVE_ROOT}/work`;
+function archiveError(message) {
+  return new SandboxOperationError("driver_failure", `Unsafe workspace archive: ${message}`);
+}
+function unsafeArchive(message) {
+  throw archiveError(message);
+}
+function archiveName(name, directory) {
+  const canonical = directory && name.endsWith("/") ? name.slice(0, -1) : name;
+  const segments = canonical.split("/");
+  if (Buffer.byteLength(canonical) > SANDBOX_LIMITS.maxPathBytes + ARCHIVE_WORK.length + 1 || segments.length > SANDBOX_LIMITS.maxPathSegments + 2 || /[\\\p{Cc}]/u.test(canonical) || segments.some((part) => !part || part === "." || part === ".." || Buffer.byteLength(part) > SANDBOX_LIMITS.maxPathSegmentBytes)) {
+    unsafeArchive("entry names must be bounded canonical relative paths.");
+  }
+  return canonical;
+}
+function workspaceName(name, directory) {
+  const canonical = archiveName(name, directory);
+  if (canonical === ARCHIVE_ROOT || canonical === ARCHIVE_WORK) {
+    if (!directory) unsafeArchive("workspace roots must be directories.");
+    return canonical;
+  }
+  if (!canonical.startsWith(`${ARCHIVE_WORK}/`)) unsafeArchive("entries must remain inside the owned work directory.");
+  try {
+    parseSandboxRelativePath(canonical.slice(ARCHIVE_WORK.length + 1));
+  } catch {
+    unsafeArchive("work entries exceed the public relative-path bounds.");
+  }
+  return canonical;
+}
+export {
+  ARCHIVE_ROOT,
+  ARCHIVE_WORK,
+  archiveError,
+  archiveName,
+  unsafeArchive,
+  workspaceName
+};

package/dist/workspace/selected.d.ts

@@ -0,0 +1,5 @@
+import type { SandboxExportConsumer, SandboxTransferSummary } from '@agen-ai/sandbox';
+import type { SandboxDriverTransferOptions } from '@agen-ai/sandbox/backend';
+import type { DockerApi } from '../resources/api.js';
+export declare function exportSelectedPath(api: DockerApi, containerId: string, path: string, kind: 'file' | 'directory', consume: SandboxExportConsumer, options: SandboxDriverTransferOptions, maxArchiveBytes: bigint | undefined): Promise<SandboxTransferSummary>;
+//# sourceMappingURL=selected.d.ts.map

package/dist/workspace/selected.js

@@ -0,0 +1,34 @@
+import { DOCKER_API } from "../policy/config.js";
+import { unsafeArchive } from "./paths.js";
+import { pathStat, sameStat, selectedPathStat } from "./stat.js";
+import { readTar } from "./tar/decode.js";
+async function exportSelectedPath(api, containerId, path, kind, consume, options, maxArchiveBytes) {
+  const stat = await selectedPathStat(api, containerId, path, kind, options.signal, options.buffers.chunkBytes);
+  const result = await api.stream(
+    "GET",
+    `${DOCKER_API}/containers/${containerId}/archive?path=${encodeURIComponent(`/workspace/work/${path}`)}`,
+    { signal: options.signal, chunkBytes: options.buffers.chunkBytes },
+    async (response) => {
+      sameStat(pathStat(response), stat);
+      let observedRoot = false;
+      const summary = await readTar(response.body, async (entry) => {
+        let relative;
+        if (entry.path === stat.name) {
+          if (observedRoot || entry.kind !== kind || (entry.mode & 511) !== (stat.mode & 511) || kind === "file" && entry.size !== stat.size) unsafeArchive("selected archive requires one matching root entry.");
+          observedRoot = true;
+          relative = path;
+        } else {
+          if (kind !== "directory" || !entry.path.startsWith(`${stat.name}/`)) unsafeArchive("archive entry is outside the selected root.");
+          relative = `${path}${entry.path.slice(stat.name.length)}`;
+        }
+        await consume(entry.kind === "directory" ? { kind: "directory", path: relative } : { kind: "file", path: relative, byteLength: entry.size, executable: (entry.mode & 73) !== 0, bytes: entry.body }, { signal: options.signal });
+      }, { signal: options.signal, chunkBytes: options.buffers.chunkBytes, limitCode: "output_limit", maxArchiveBytes });
+      if (!observedRoot) unsafeArchive("selected root is missing from its archive.");
+      return summary;
+    }
+  );
+  return result.value;
+}
+export {
+  exportSelectedPath
+};

package/dist/workspace/stat.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod/v4';
+import type { DockerEngineStreamResponse } from '../engine/contracts.js';
+import type { DockerApi } from '../resources/api.js';
+declare const statSchema: z.ZodObject<{
+    name: z.ZodString;
+    size: z.ZodNumber;
+    mode: z.ZodNumber;
+    mtime: z.ZodString;
+    linkTarget: z.ZodString;
+}, z.core.$strict>;
+export type DockerPathStat = z.infer<typeof statSchema>;
+export declare function pathStat(response: DockerEngineStreamResponse): DockerPathStat;
+export declare function requireStat(stat: DockerPathStat, path: string, kind: 'file' | 'directory'): void;
+export declare function sameStat(actual: DockerPathStat, expected: DockerPathStat): void;
+export declare function statPath(api: DockerApi, containerId: string, path: string, signal: AbortSignal, chunkBytes: number): Promise<DockerPathStat>;
+export declare function selectedPathStat(api: DockerApi, containerId: string, relative: string, kind: 'file' | 'directory', signal: AbortSignal, chunkBytes: number): Promise<DockerPathStat>;
+export {};
+//# sourceMappingURL=stat.d.ts.map

package/dist/workspace/stat.js

@@ -0,0 +1,63 @@
+import { z } from "zod/v4";
+import { DOCKER_API } from "../policy/config.js";
+import { unsafeArchive } from "./paths.js";
+const statSchema = z.strictObject({
+  name: z.string().min(1).max(1024),
+  size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  mode: z.number().int().nonnegative().max(4294967295),
+  mtime: z.string().min(1).max(64),
+  linkTarget: z.string().max(4096)
+});
+const MODE_DIRECTORY = 2147483648;
+const MODE_TYPE = 2401763328;
+function pathStat(response) {
+  const name = "x-docker-container-path-stat";
+  const encoded = response.headers[name];
+  let count = 0;
+  for (let index = 0; index < response.rawHeaders.length; index += 2) if (response.rawHeaders[index].toLowerCase() === name) count += 1;
+  if (count !== 1 || typeof encoded !== "string" || encoded.length > 8192 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(encoded)) unsafeArchive("Docker stat header must be one bounded canonical Base64 value.");
+  const bytes = Buffer.from(encoded, "base64");
+  if (bytes.toString("base64") !== encoded) unsafeArchive("Docker stat header is not canonical Base64.");
+  let value;
+  try {
+    value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    return unsafeArchive("Docker stat header requires valid UTF-8 JSON.");
+  }
+  const parsed = statSchema.safeParse(value);
+  if (!parsed.success) unsafeArchive("Docker stat header does not match the bounded path-stat contract.");
+  return parsed.data;
+}
+function requireStat(stat, path, kind) {
+  const type = (stat.mode & MODE_TYPE) >>> 0;
+  if (stat.name !== path.slice(path.lastIndexOf("/") + 1) || stat.linkTarget !== "" || type !== (kind === "directory" ? MODE_DIRECTORY : 0)) unsafeArchive("selected paths require the requested regular file or directory without symlink traversal.");
+}
+function sameStat(actual, expected) {
+  if (actual.name !== expected.name || actual.size !== expected.size || actual.mode !== expected.mode || actual.mtime !== expected.mtime || actual.linkTarget !== expected.linkTarget) unsafeArchive("selected path metadata changed between stat and archive observations.");
+}
+async function statPath(api, containerId, path, signal, chunkBytes) {
+  const result = await api.stream("HEAD", `${DOCKER_API}/containers/${containerId}/archive?path=${encodeURIComponent(path)}`, { signal, chunkBytes }, async (response) => {
+    const stat = pathStat(response);
+    for await (const chunk of response.body) if (chunk.length) unsafeArchive("HEAD unexpectedly returned a body.");
+    return stat;
+  });
+  return result.value;
+}
+async function selectedPathStat(api, containerId, relative, kind, signal, chunkBytes) {
+  const parts = ["workspace", "work", ...relative.split("/")];
+  for (let count = 1; count < parts.length; count += 1) {
+    const path2 = `/${parts.slice(0, count).join("/")}`;
+    requireStat(await statPath(api, containerId, path2, signal, chunkBytes), path2, "directory");
+  }
+  const path = `/${parts.join("/")}`;
+  const stat = await statPath(api, containerId, path, signal, chunkBytes);
+  requireStat(stat, path, kind);
+  return stat;
+}
+export {
+  pathStat,
+  requireStat,
+  sameStat,
+  selectedPathStat,
+  statPath
+};

package/dist/workspace/tar/contracts.d.ts

@@ -0,0 +1,28 @@
+import type { SandboxByteSource, SandboxTransferSummary } from '@agen-ai/sandbox';
+export interface TarInputEntry {
+    readonly path: string;
+    readonly kind: 'file' | 'directory';
+    readonly size: number;
+    readonly body?: SandboxByteSource;
+    readonly mode: number;
+    readonly uid: number;
+    readonly gid: number;
+}
+export interface TarHeader {
+    readonly path: string;
+    readonly kind: 'file' | 'directory' | 'pax';
+    readonly size: number;
+    readonly mode: number;
+}
+export interface TarOutputEntry extends Omit<TarHeader, 'kind'> {
+    readonly kind: 'file' | 'directory';
+    readonly body: AsyncIterable<Uint8Array>;
+}
+export interface TarOptions {
+    readonly signal: AbortSignal;
+    readonly chunkBytes: number;
+    readonly maxArchiveBytes?: bigint;
+    readonly limitCode: 'input_limit' | 'output_limit';
+}
+export type TarSummary = SandboxTransferSummary;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/workspace/tar/decode.d.ts

@@ -0,0 +1,3 @@
+import type { TarOptions, TarOutputEntry, TarSummary } from './contracts.js';
+export declare function readTar(source: AsyncIterable<Uint8Array>, consume: (entry: TarOutputEntry) => Promise<void>, options: TarOptions): Promise<TarSummary>;
+//# sourceMappingURL=decode.d.ts.map