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

package/dist/workspace/tar/decode.js

@@ -0,0 +1,62 @@
+import { archiveName, unsafeArchive } from "../paths.js";
+import { consumeTarEntry } from "./entry.js";
+import { BLOCK_BYTES, MAX_PAX_BYTES, MAX_TRAILER_BYTES, parseHeader } from "./header.js";
+import { parsePax } from "./pax.js";
+import { TarReader } from "./reader.js";
+async function readTar(source, consume, options) {
+  const reader = new TarReader(source, options);
+  let files = 0n;
+  let directories = 0n;
+  let payloadBytes = 0n;
+  let pendingPax;
+  let primary;
+  let result;
+  try {
+    for (; ; ) {
+      const block = await reader.required(BLOCK_BYTES);
+      if (block.every((byte) => byte === 0)) {
+        if (pendingPax) unsafeArchive("PAX metadata lacks its following entry.");
+        await reader.zeroes(BLOCK_BYTES);
+        let trailerBytes = BLOCK_BYTES * 2;
+        for (; ; ) {
+          const trailing = await reader.exact(BLOCK_BYTES, true);
+          if (trailing === void 0) break;
+          if (trailing.some((byte) => byte !== 0)) unsafeArchive("nonzero padding or trailer.");
+          trailerBytes += BLOCK_BYTES;
+          if (trailerBytes > MAX_TRAILER_BYTES) unsafeArchive("trailing padding exceeds the framing bound.");
+        }
+        result = Object.freeze({ files, directories, payloadBytes, archiveBytes: reader.bytes });
+        break;
+      }
+      const header = parseHeader(block);
+      if (header.kind === "pax") {
+        if (pendingPax || header.size === 0 || header.size > MAX_PAX_BYTES) unsafeArchive("invalid bounded local PAX sequence.");
+        pendingPax = { path: parsePax(await reader.required(header.size)) };
+        await reader.zeroes((BLOCK_BYTES - header.size % BLOCK_BYTES) % BLOCK_BYTES);
+        continue;
+      }
+      const path = archiveName(pendingPax?.path ?? header.path, header.kind === "directory");
+      pendingPax = void 0;
+      await consumeTarEntry(reader, { ...header, kind: header.kind }, path, consume, options.chunkBytes);
+      payloadBytes += BigInt(header.size);
+      await reader.zeroes((BLOCK_BYTES - header.size % BLOCK_BYTES) % BLOCK_BYTES);
+      if (header.kind === "file") files += 1n;
+      else directories += 1n;
+    }
+  } catch (error) {
+    primary = { error };
+  } finally {
+    try {
+      await reader.close();
+    } catch (error) {
+      if (primary) throw new AggregateError([primary.error, error], "Archive validation and source cleanup both failed.");
+      throw error;
+    }
+  }
+  if (primary) throw primary.error;
+  if (!result) unsafeArchive("archive framing did not settle.");
+  return result;
+}
+export {
+  readTar
+};

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

@@ -0,0 +1,3 @@
+import type { TarInputEntry, TarOptions } from './contracts.js';
+export declare function writeTar(entries: AsyncIterable<TarInputEntry> | Iterable<TarInputEntry>, options: TarOptions): AsyncGenerator<Uint8Array>;
+//# sourceMappingURL=encode.d.ts.map

package/dist/workspace/tar/encode.js

@@ -0,0 +1,103 @@
+import { SandboxOperationError, SandboxUnsupportedError } from "@agen-ai/sandbox";
+import { archiveName } from "../paths.js";
+import { BLOCK_BYTES, MAX_OCTAL_SIZE, MAX_PAX_BYTES, makeHeader } from "./header.js";
+import { encodePaxPath } from "./pax.js";
+async function* payload(entry, options) {
+  let written = 0;
+  if (entry.body !== void 0) {
+    const source = entry.body;
+    const iterator = Symbol.asyncIterator in source ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+    let done = false;
+    let primary;
+    try {
+      for (; ; ) {
+        options.signal.throwIfAborted();
+        const item = await iterator.next();
+        options.signal.throwIfAborted();
+        if (item.done) {
+          done = true;
+          break;
+        }
+        const chunk = item.value;
+        if (!(chunk instanceof Uint8Array) || chunk.length > options.chunkBytes) throw new SandboxOperationError("input_limit", "Input file chunks exceed the selected byte buffer.");
+        if (chunk.length > entry.size - written) throw new SandboxOperationError("input_limit", "Input file body exceeds its declared size.");
+        written += chunk.length;
+        yield chunk;
+      }
+    } catch (error) {
+      primary = { error };
+    } finally {
+      if (!done) {
+        try {
+          await iterator.return?.();
+        } catch (error) {
+          if (primary) throw new AggregateError([primary.error, error], "Input file and producer cleanup both failed.");
+          throw error;
+        }
+      }
+    }
+    if (primary) throw primary.error;
+  }
+  if (written !== entry.size) throw new SandboxOperationError("input_limit", "Input file body ended before its declared size.");
+  if (written % BLOCK_BYTES) yield new Uint8Array(BLOCK_BYTES - written % BLOCK_BYTES);
+}
+async function* blocks(entries, options) {
+  for await (const entry of entries) {
+    options.signal.throwIfAborted();
+    archiveName(entry.path, entry.kind === "directory");
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_OCTAL_SIZE) {
+      throw new SandboxUnsupportedError("Docker tar entries require exact unsigned-octal sizes no greater than 8 GiB minus one byte.");
+    }
+    if (entry.kind === "directory" && entry.size !== 0) throw new SandboxUnsupportedError("Directory tar entries require zero bytes.");
+    const name = entry.kind === "directory" ? `${entry.path}/` : entry.path;
+    let headerName = name;
+    if (Buffer.byteLength(name) > 100) {
+      const pax = encodePaxPath(name);
+      if (pax.length > MAX_PAX_BYTES) throw new SandboxUnsupportedError("Docker path metadata exceeds the selected bounded PAX representation.");
+      yield makeHeader({ ...entry, path: "PaxHeader", kind: "pax", size: pax.length });
+      for (let offset = 0; offset < pax.length; offset += options.chunkBytes) yield pax.subarray(offset, offset + options.chunkBytes);
+      if (pax.length % BLOCK_BYTES) yield new Uint8Array(BLOCK_BYTES - pax.length % BLOCK_BYTES);
+      headerName = entry.kind === "directory" ? "entry/" : "entry";
+    }
+    yield makeHeader({ ...entry, path: headerName });
+    yield* payload(entry, options);
+  }
+  options.signal.throwIfAborted();
+  yield new Uint8Array(BLOCK_BYTES);
+  yield new Uint8Array(BLOCK_BYTES);
+}
+async function* writeTar(entries, options) {
+  let bytes = 0n;
+  const iterator = blocks(entries, options);
+  let done = false;
+  let primary;
+  try {
+    for (; ; ) {
+      const item = await iterator.next();
+      if (item.done) {
+        done = true;
+        break;
+      }
+      bytes += BigInt(item.value.length);
+      if (options.maxArchiveBytes !== void 0 && bytes > options.maxArchiveBytes) {
+        throw new SandboxOperationError(options.limitCode, "Workspace archive exceeds the caller-selected wire byte quota.");
+      }
+      yield item.value;
+    }
+  } catch (error) {
+    primary = { error };
+  } finally {
+    if (!done) {
+      try {
+        await iterator.return(void 0);
+      } catch (error) {
+        if (primary) throw new AggregateError([primary.error, error], "Archive transfer and producer cleanup both failed.");
+        throw error;
+      }
+    }
+  }
+  if (primary) throw primary.error;
+}
+export {
+  writeTar
+};

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

@@ -0,0 +1,6 @@
+import type { TarHeader, TarOutputEntry } from './contracts.js';
+import type { TarReader } from './reader.js';
+export declare function consumeTarEntry(reader: TarReader, header: TarHeader & {
+    readonly kind: 'file' | 'directory';
+}, path: string, consume: (entry: TarOutputEntry) => Promise<void>, chunkBytes: number): Promise<void>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/workspace/tar/entry.js

@@ -0,0 +1,80 @@
+import { archiveError, unsafeArchive } from "../paths.js";
+async function consumeTarEntry(reader, header, path, consume, chunkBytes) {
+  let remaining = header.size;
+  let active = true;
+  let entered = false;
+  let pending;
+  let failure;
+  const reject = (message) => {
+    const error = archiveError(message);
+    failure ??= { error, origin: "ownership" };
+    const result = Promise.reject(error);
+    void result.catch(() => {
+    });
+    return result;
+  };
+  const iterator = {
+    next() {
+      if (!active) return reject("entry body is retired outside its callback.");
+      if (pending) return reject("concurrent entry body pulls are forbidden.");
+      const actual = Promise.resolve().then(async () => {
+        try {
+          if (remaining === 0) return { done: true, value: void 0 };
+          let chunk;
+          try {
+            chunk = await reader.take(Math.min(remaining, chunkBytes));
+          } catch (error) {
+            failure ??= { error, origin: "source" };
+            throw error;
+          }
+          if (!active) unsafeArchive("entry callback returned with an active body pull.");
+          if (!chunk) unsafeArchive("unexpected EOF inside payload.");
+          remaining -= chunk.length;
+          return { done: false, value: chunk };
+        } catch (error) {
+          failure ??= { error, origin: "ownership" };
+          throw error;
+        } finally {
+          pending = void 0;
+        }
+      });
+      pending = actual;
+      void actual.catch(() => {
+      });
+      return actual;
+    },
+    async return() {
+      active = false;
+      await pending?.catch(() => {
+      });
+      return { done: true, value: void 0 };
+    }
+  };
+  const body = { [Symbol.asyncIterator]() {
+    if (!active || entered) unsafeArchive("entry body is single-use and callback-scoped.");
+    entered = true;
+    return iterator;
+  } };
+  let callbackFailure;
+  try {
+    await consume(Object.freeze({ path, kind: header.kind, size: header.size, mode: header.mode, body }));
+  } catch (error) {
+    callbackFailure = { error };
+  }
+  const enteredPull = pending;
+  active = false;
+  await enteredPull?.catch(() => {
+  });
+  if (callbackFailure) {
+    if (failure?.origin === "source" && failure.error !== callbackFailure.error) {
+      throw new AggregateError([callbackFailure.error, failure.error], "Archive callback and entered source pull both failed.");
+    }
+    throw callbackFailure.error;
+  }
+  if (failure) throw failure.error;
+  if (enteredPull) unsafeArchive("entry callback returned with an active body pull.");
+  if (remaining !== 0) unsafeArchive("entry callback must drain its complete body.");
+}
+export {
+  consumeTarEntry
+};

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

@@ -0,0 +1,11 @@
+import type { TarHeader, TarInputEntry } from './contracts.js';
+export declare const BLOCK_BYTES = 512;
+export declare const MAX_OCTAL_SIZE: number;
+export declare const MAX_PAX_BYTES = 4096;
+export declare const MAX_TRAILER_BYTES: number;
+export declare function text(bytes: Uint8Array): string;
+export declare function parseHeader(block: Uint8Array): TarHeader;
+export declare function makeHeader(entry: Omit<TarInputEntry, 'body' | 'kind'> & {
+    readonly kind: TarHeader['kind'];
+}): Uint8Array;
+//# sourceMappingURL=header.d.ts.map

package/dist/workspace/tar/header.js

@@ -0,0 +1,84 @@
+import { SandboxUnsupportedError } from "@agen-ai/sandbox";
+import { archiveName, unsafeArchive } from "../paths.js";
+const BLOCK_BYTES = 512;
+const MAX_OCTAL_SIZE = 8 * 1024 ** 3 - 1;
+const MAX_PAX_BYTES = 4096;
+const MAX_TRAILER_BYTES = 10 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+function text(bytes) {
+  try {
+    return utf8.decode(bytes);
+  } catch {
+    return unsafeArchive("header text must be valid UTF-8.");
+  }
+}
+function field(block, offset, length) {
+  const bytes = block.subarray(offset, offset + length);
+  const terminator = bytes.indexOf(0);
+  if (terminator < 0) return text(bytes);
+  if (bytes.subarray(terminator).some((byte) => byte !== 0)) unsafeArchive("hidden bytes after a text terminator.");
+  return text(bytes.subarray(0, terminator));
+}
+function octal(block, offset, length) {
+  const bytes = block.subarray(offset, offset + length);
+  if (bytes.some((byte) => byte !== 0 && byte !== 32 && (byte < 48 || byte > 55))) unsafeArchive("numeric headers require unsigned octal.");
+  const encoded = text(bytes);
+  if (!/^[ \0]*[0-7]*[ \0]*$/u.test(encoded)) unsafeArchive("numeric headers require unsigned octal.");
+  const digits = encoded.replace(/^[ \0]+|[ \0]+$/gu, "");
+  const value = digits ? Number.parseInt(digits, 8) : 0;
+  if (!Number.isSafeInteger(value)) unsafeArchive("numeric header exceeds the safe integer range.");
+  return value;
+}
+function parseHeader(block) {
+  const checksum = octal(block, 148, 8);
+  let sum = 0;
+  for (let index = 0; index < BLOCK_BYTES; index += 1) sum += index >= 148 && index < 156 ? 32 : block[index];
+  if (sum !== checksum) unsafeArchive("checksum mismatch.");
+  if (field(block, 257, 6) !== "ustar" || text(block.subarray(263, 265)) !== "00") unsafeArchive("only POSIX ustar/PAX is supported.");
+  const flag = block[156];
+  const kind = flag === 53 ? "directory" : flag === 48 || flag === 0 ? "file" : flag === 120 ? "pax" : void 0;
+  if (!kind) unsafeArchive("only regular files, directories and local PAX records are supported; links and special files are forbidden.");
+  if (field(block, 157, 100)) unsafeArchive("links and link metadata are forbidden.");
+  const prefix = field(block, 345, 155);
+  const name = field(block, 0, 100);
+  const path = prefix ? `${prefix}/${name}` : name;
+  archiveName(path, kind !== "file");
+  const mode = octal(block, 100, 8);
+  const size = octal(block, 124, 12);
+  for (const [offset, length] of [[108, 8], [116, 8], [136, 12], [329, 8], [337, 8]]) octal(block, offset, length);
+  field(block, 265, 32);
+  field(block, 297, 32);
+  if (mode > 4095 || size > MAX_OCTAL_SIZE || block.subarray(500).some((byte) => byte !== 0)) unsafeArchive("unsupported numeric or extension metadata.");
+  if (kind === "directory" && size !== 0) unsafeArchive("directory entries cannot carry payload.");
+  return { path, kind, mode, size };
+}
+function putOctal(header, offset, length, value) {
+  if (!Number.isSafeInteger(value) || value < 0 || value.toString(8).length >= length) {
+    throw new SandboxUnsupportedError("Docker tar metadata exceeds the selected unsigned-octal representation.");
+  }
+  header.write(value.toString(8).padStart(length - 1, "0"), offset, length - 1, "ascii");
+}
+function makeHeader(entry) {
+  if (Buffer.byteLength(entry.path) > 100 || entry.mode > 4095) throw new SandboxUnsupportedError("Docker tar header name or mode is not representable.");
+  const header = Buffer.alloc(BLOCK_BYTES);
+  header.write(entry.path, 0, 100, "utf8");
+  for (const [offset, length, value] of [[100, 8, entry.mode], [108, 8, entry.uid], [116, 8, entry.gid], [124, 12, entry.size], [136, 12, 0], [329, 8, 0], [337, 8, 0]]) {
+    putOctal(header, offset, length, value);
+  }
+  header[156] = entry.kind === "directory" ? 53 : entry.kind === "pax" ? 120 : 48;
+  header.write("ustar\0", 257, 6, "ascii");
+  header.write("00", 263, 2, "ascii");
+  header.fill(32, 148, 156);
+  header.write(header.reduce((total, byte) => total + byte, 0).toString(8).padStart(6, "0"), 148, 6, "ascii");
+  header[154] = 0;
+  return header;
+}
+export {
+  BLOCK_BYTES,
+  MAX_OCTAL_SIZE,
+  MAX_PAX_BYTES,
+  MAX_TRAILER_BYTES,
+  makeHeader,
+  parseHeader,
+  text
+};

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

@@ -0,0 +1,3 @@
+export declare function parsePax(bytes: Uint8Array): string | undefined;
+export declare function encodePaxPath(path: string): Uint8Array;
+//# sourceMappingURL=pax.d.ts.map

package/dist/workspace/tar/pax.js

@@ -0,0 +1,40 @@
+import { archiveName, unsafeArchive } from "../paths.js";
+import { text } from "./header.js";
+function parsePax(bytes) {
+  const keys = /* @__PURE__ */ new Set();
+  let offset = 0;
+  let path;
+  while (offset < bytes.length) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0 || space - offset > 5) unsafeArchive("PAX requires bounded decimal lengths.");
+    const digits = text(bytes.subarray(offset, space));
+    if (!/^[1-9][0-9]*$/u.test(digits)) unsafeArchive("PAX length must be canonical decimal.");
+    const end = offset + Number(digits);
+    if (end > bytes.length || end <= space + 2 || bytes[end - 1] !== 10) unsafeArchive("PAX length or newline mismatch.");
+    const record = text(bytes.subarray(space + 1, end - 1));
+    const equals = record.indexOf("=");
+    const key = record.slice(0, equals);
+    const value = record.slice(equals + 1);
+    if (equals <= 0 || keys.has(key)) unsafeArchive("PAX keys must be unique.");
+    keys.add(key);
+    if (key === "path") {
+      archiveName(value, true);
+      path = value;
+    } else if (!["mtime", "atime", "ctime"].includes(key) || !/^-?[0-9]{1,16}(?:\.[0-9]{1,9})?$/u.test(value)) {
+      unsafeArchive("only path and inert timestamps are supported in PAX records.");
+    }
+    offset = end;
+  }
+  return path;
+}
+function encodePaxPath(path) {
+  const payload = ` path=${path}
+`;
+  let size = Buffer.byteLength(payload) + 1;
+  while (String(size).length + Buffer.byteLength(payload) !== size) size = String(size).length + Buffer.byteLength(payload);
+  return Buffer.from(`${size}${payload}`);
+}
+export {
+  encodePaxPath,
+  parsePax
+};

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

@@ -0,0 +1,16 @@
+import type { TarOptions } from './contracts.js';
+export declare class TarReader {
+    private readonly options;
+    private readonly iterator;
+    private current;
+    private ended;
+    private received;
+    bytes: bigint;
+    constructor(source: AsyncIterable<Uint8Array>, options: TarOptions);
+    take(maximum: number): Promise<Uint8Array | undefined>;
+    exact(size: number, eofAllowed?: boolean): Promise<Uint8Array | undefined>;
+    required(size: number): Promise<Uint8Array>;
+    zeroes(size: number): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/workspace/tar/reader.js

@@ -0,0 +1,69 @@
+import { SandboxOperationError } from "@agen-ai/sandbox";
+import { unsafeArchive } from "../paths.js";
+class TarReader {
+  constructor(source, options) {
+    this.options = options;
+    this.iterator = source[Symbol.asyncIterator]();
+  }
+  iterator;
+  current = new Uint8Array();
+  ended = false;
+  received = 0n;
+  bytes = 0n;
+  async take(maximum) {
+    this.options.signal.throwIfAborted();
+    while (!this.current.length && !this.ended) {
+      const item = await this.iterator.next();
+      this.options.signal.throwIfAborted();
+      if (item.done) this.ended = true;
+      else {
+        if (!(item.value instanceof Uint8Array) || item.value.length > this.options.chunkBytes) unsafeArchive("source chunks exceed the selected byte buffer.");
+        this.received += BigInt(item.value.length);
+        if (this.options.maxArchiveBytes !== void 0 && this.received > this.options.maxArchiveBytes) {
+          throw new SandboxOperationError(this.options.limitCode, "Workspace archive exceeds the caller-selected wire byte quota.");
+        }
+        this.current = item.value;
+      }
+    }
+    if (this.ended) return void 0;
+    const chunk = this.current.subarray(0, maximum);
+    this.current = this.current.subarray(chunk.length);
+    this.bytes += BigInt(chunk.length);
+    return chunk;
+  }
+  async exact(size, eofAllowed = false) {
+    const result = new Uint8Array(size);
+    let position = 0;
+    while (position < size) {
+      const chunk = await this.take(size - position);
+      if (chunk === void 0) {
+        if (eofAllowed && position === 0) return void 0;
+        unsafeArchive("unexpected EOF inside framing or payload.");
+      }
+      result.set(chunk, position);
+      position += chunk.length;
+    }
+    return result;
+  }
+  async required(size) {
+    const bytes = await this.exact(size);
+    if (!bytes) unsafeArchive("unexpected EOF inside framing.");
+    return bytes;
+  }
+  async zeroes(size) {
+    let remaining = size;
+    while (remaining > 0) {
+      const chunk = await this.take(remaining);
+      if (!chunk) unsafeArchive("unexpected EOF inside padding.");
+      if (chunk.some((byte) => byte !== 0)) unsafeArchive("nonzero padding or trailer.");
+      remaining -= chunk.length;
+    }
+  }
+  async close() {
+    this.current = new Uint8Array();
+    if (!this.ended) await this.iterator.return?.();
+  }
+}
+export {
+  TarReader
+};

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@agen-ai/sandbox-docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.4",
+  "private": false,
+  "description": "Explicit local Docker Engine resources, policy enforcement and recovery for AgenAI sandboxes.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@agen-ai/sandbox": "^0.4.4",
+    "@agen-ai/validation": "^0.4.4"
+  },
+  "devDependencies": {
+    "tar-stream": "3.2.2",
+    "tsup": "^8.5.0",
+    "@agen-ai/agent-protocol": "^0.4.4",
+    "@agen-ai/agent-runtime": "^0.4.4",
+    "@agen-ai/provider-acp": "^0.4.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trevor-nichols/agenai-agent-sdk.git",
+    "directory": "packages/sandbox-docker"
+  },
+  "homepage": "https://github.com/trevor-nichols/agenai-agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/trevor-nichols/agenai-agent-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:runtime && pnpm run build:types",
+    "build:runtime": "tsup",
+    "build:types": "tsc --project tsconfig.json --emitDeclarationOnly --outDir dist",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.test.json --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:integration": "node --import tsx --test tests/integration/*.test.ts",
+    "clean": "rimraf dist *.tsbuildinfo"
+  }
 }