@brainbase-labs/cli 0.23.0 → 0.24.0

package/dist/index.js

@@ -36008,7 +36008,7 @@ function padStart(s, n) {
 // package.json
 var package_default = {
   name: "@brainbase-labs/cli",
-  version: "0.23.0",
+  version: "0.24.0",
   description: "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   type: "module",
   bin: {
@@ -78472,7 +78472,9 @@ import crypto6 from "node:crypto";
 import fs81 from "node:fs";
 import os16 from "node:os";
 import path88 from "node:path";
+import { Readable, Transform as Transform2 } from "node:stream";
 import { pipeline as pipeline2 } from "node:stream/promises";
+import { createGunzip, createInflateRaw } from "node:zlib";
 var SCHEMA_VERSION = "1";
 var SHA256_RE = /^[a-f0-9]{64}$/i;
 var ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
@@ -78480,6 +78482,9 @@ var ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var MAX_SPEC_BYTES = 20 * 1024 * 1024;
 var MAX_FINAL_OUTPUT_BYTES = 10 * 1024 * 1024;
 var MAX_TRAJECTORY_BYTES = 100 * 1024 * 1024;
+var MAX_REMOTE_INPUT_BYTES = 2 * 1024 * 1024 * 1024;
+var MAX_ARCHIVE_EXTRACTED_BYTES = 2 * 1024 * 1024 * 1024;
+var MAX_ARCHIVE_SCAN_BYTES = 2 * 1024 * 1024 * 1024;
 var RESERVED_WORKSPACE_PATHS = new Set([
   ".brainbase",
   ".git",
@@ -78507,21 +78512,51 @@ var NonSecretEnvironmentValueSchema = exports_external.object({
   sensitive: exports_external.literal(false)
 }).strict();
 var RootRelativePathSchema = exports_external.string().min(1).max(1024);
+var ArchivePathSchema = RootRelativePathSchema.refine((value) => {
+  try {
+    return safeRelPath(value) === value;
+  } catch {
+    return false;
+  }
+}, {
+  message: "must be a normalized safe relative path"
+});
 var BudgetSchema = exports_external.object({
   timeout_ms: exports_external.number().int().min(100).max(3600000),
   max_output_bytes: exports_external.number().int().min(1024).max(100 * 1024 * 1024)
 }).strict();
-var MaterialSchema = exports_external.object({
+var MaterialBaseSchema = {
   id: IdSchema,
-  kind: exports_external.enum(["file", "tar_gz"]),
   source: RootRelativePathSchema,
+  download_url_env: EnvNameSchema.optional(),
   destination: RootRelativePathSchema,
   sha256: Sha256Schema,
   size_bytes: exports_external.number().int().min(0).max(2 * 1024 * 1024 * 1024),
-  mode: exports_external.number().int().min(0).max(511).optional(),
+  mode: exports_external.number().int().min(0).max(511).optional()
+};
+var ExpandableMaterialSchema = {
   max_unpacked_bytes: exports_external.number().int().min(1).max(2 * 1024 * 1024 * 1024).optional(),
   max_file_count: exports_external.number().int().min(1).max(1e5).optional()
-}).strict();
+};
+var MaterialSchema = exports_external.discriminatedUnion("kind", [
+  exports_external.object({
+    ...MaterialBaseSchema,
+    ...ExpandableMaterialSchema,
+    kind: exports_external.literal("file")
+  }).strict(),
+  exports_external.object({
+    ...MaterialBaseSchema,
+    ...ExpandableMaterialSchema,
+    kind: exports_external.literal("tar_gz")
+  }).strict(),
+  exports_external.object({
+    ...MaterialBaseSchema,
+    kind: exports_external.literal("archive_file"),
+    archive_path: ArchivePathSchema,
+    file_sha256: Sha256Schema,
+    file_size_bytes: exports_external.number().int().min(0).max(2 * 1024 * 1024 * 1024)
+  }).strict()
+]);
 var CommandSchema = exports_external.object({
   id: IdSchema,
   argv: exports_external.array(exports_external.string().min(1)).min(1).max(128),
@@ -78588,6 +78623,7 @@ var EvaluatorSchema = exports_external.discriminatedUnion("type", [
 ]);
 var EvidenceFileSchema = exports_external.object({
   source: RootRelativePathSchema,
+  download_url_env: EnvNameSchema.optional(),
   sha256: Sha256Schema,
   size_bytes: exports_external.number().int().min(0).max(2 * 1024 * 1024 * 1024)
 }).strict();
@@ -78632,6 +78668,35 @@ var BenchmarkSpecSchema = exports_external.discriminatedUnion("phase", [
     }
   }
   const declaredSecrets = new Set(value.secret_env);
+  const remoteInputs = value.phase === "hydrate" ? value.materials : [
+    value.evidence.final_output,
+    value.evidence.trajectory,
+    ...value.references
+  ];
+  const remoteUrlEnvNames = new Set(remoteInputs.flatMap((input) => input.download_url_env ? [input.download_url_env] : []));
+  const uniqueRemoteInputs = new Map;
+  for (const input of remoteInputs) {
+    if (!input.download_url_env)
+      continue;
+    uniqueRemoteInputs.set([input.source, input.sha256, input.size_bytes].join("\x00"), input.size_bytes);
+  }
+  const remoteInputBytes = [...uniqueRemoteInputs.values()].reduce((total, size2) => total + size2, 0);
+  if (remoteInputBytes > MAX_REMOTE_INPUT_BYTES) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: [value.phase === "hydrate" ? "materials" : "references"],
+      message: "remote inputs exceed the aggregate download byte limit"
+    });
+  }
+  for (const name of remoteUrlEnvNames) {
+    if (Object.hasOwn(value.environment, name)) {
+      context.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        path: ["environment", name],
+        message: "signed download URLs must be supplied through the process environment"
+      });
+    }
+  }
   const commands = value.phase === "hydrate" ? value.setup_commands.map((command, index) => ({
     command,
     path: ["setup_commands", index, "secret_env"]
@@ -78641,6 +78706,13 @@ var BenchmarkSpecSchema = exports_external.discriminatedUnion("phase", [
   }] : []);
   for (const { command, path: issuePath } of commands) {
     for (const name of command.secret_env) {
+      if (remoteUrlEnvNames.has(name)) {
+        context.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          path: issuePath,
+          message: `signed download URL environment variables cannot be exposed to commands: ${name}`
+        });
+      }
       if (!declaredSecrets.has(name)) {
         context.addIssue({
           code: exports_external.ZodIssueCode.custom,
@@ -78667,6 +78739,15 @@ var BenchmarkSpecSchema = exports_external.discriminatedUnion("phase", [
       });
     }
   }
+  const materials = value.phase === "hydrate" ? value.materials : value.references;
+  const archiveOutputBytes = materials.reduce((total, material) => total + (material.kind === "archive_file" ? material.file_size_bytes : 0), 0);
+  if (archiveOutputBytes > MAX_ARCHIVE_EXTRACTED_BYTES) {
+    context.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: [value.phase === "hydrate" ? "materials" : "references"],
+      message: "archive-file materials exceed the aggregate extracted byte limit"
+    });
+  }
   if (value.phase === "evaluate" && value.evaluators.filter((evaluator) => evaluator.type === "sandbox_command").length > 1) {
     context.addIssue({
       code: exports_external.ZodIssueCode.custom,
@@ -78680,6 +78761,10 @@ var BENCHMARK_CAPABILITIES = {
   cli_version: VERSION,
   schema_versions: [SCHEMA_VERSION],
   phases: ["hydrate", "evaluate"],
+  features: [
+    "remote_input_references_v1",
+    "archive_file_materials_v1"
+  ],
   evaluator_types: [
     "output_assertion",
     "trajectory_assertion",
@@ -78703,6 +78788,11 @@ class BenchmarkPhaseError extends Error {
     this.name = "BenchmarkPhaseError";
   }
 }
+var ZIP_EOCD_SIGNATURE = 101010256;
+var ZIP_CENTRAL_SIGNATURE = 33639248;
+var ZIP_LOCAL_SIGNATURE = 67324752;
+var MAX_ZIP_EOCD_BYTES = 65535 + 22;
+var MAX_ARCHIVE_MEMBERS = 1e5;
 function nowIso() {
   return new Date().toISOString();
 }
@@ -78965,10 +79055,516 @@ async function verifyInput(stagingRoot, material) {
     if (actual !== material.sha256) {
       throw new BenchmarkPhaseError("digest_mismatch", `checksum mismatch for ${material.source}`, { expected: material.sha256, actual });
     }
+    return {
+      source,
+      sha256: actual,
+      size: opened.stat.size,
+      mode: opened.stat.mode & 511
+    };
   } finally {
     fs81.closeSync(opened.fd);
   }
-  return source;
+}
+function inputCacheKey(input) {
+  return [
+    input.source,
+    input.sha256,
+    input.size_bytes
+  ].join(":");
+}
+async function cachedVerifiedInput(stagingRoot, input, context) {
+  const cacheKey = inputCacheKey(input);
+  const cached2 = context.verifiedInputs.get(cacheKey);
+  if (cached2)
+    return cached2;
+  const verified = await verifyInput(stagingRoot, input);
+  context.verifiedInputs.set(cacheKey, verified);
+  return verified;
+}
+function stagedInputRecord(stagingRoot, verified) {
+  return {
+    root: "staging",
+    path: path88.relative(stagingRoot, verified.source).replace(/\\/g, "/"),
+    sha256: verified.sha256,
+    size: verified.size,
+    mode: verified.mode,
+    kind: "file"
+  };
+}
+function remoteUrlEnvironmentNames(spec) {
+  const inputs = spec.phase === "hydrate" ? spec.materials : [
+    spec.evidence.final_output,
+    spec.evidence.trajectory,
+    ...spec.references
+  ];
+  return new Set(inputs.flatMap((input) => input.download_url_env ? [input.download_url_env] : []));
+}
+function removeRemoteHydrationInputs(spec) {
+  const removedSources = new Set;
+  for (const material of spec.materials) {
+    if (!material.download_url_env || removedSources.has(material.source))
+      continue;
+    const relative = safeRelPath(material.source);
+    const source = path88.resolve(spec.staging_root, relative);
+    if (!isWithin(spec.staging_root, source)) {
+      throw new BenchmarkPhaseError("unsafe_path", `source escapes staging root: ${material.source}`);
+    }
+    assertNoSymlinkTraversal(spec.staging_root, relative);
+    try {
+      fs81.rmSync(source, { force: true });
+    } catch {
+      throw new BenchmarkPhaseError("staging_cleanup_failed", `downloaded benchmark input could not be removed: ${material.source}`);
+    }
+    removedSources.add(material.source);
+  }
+}
+async function downloadInputReference(stagingRoot, input, context) {
+  const cacheKey = inputCacheKey(input);
+  const cached2 = context.verifiedInputs.get(cacheKey);
+  if (cached2)
+    return cached2;
+  const envName = input.download_url_env;
+  if (!envName) {
+    return await cachedVerifiedInput(stagingRoot, input, context);
+  }
+  const relative = safeRelPath(input.source);
+  const destination = path88.resolve(stagingRoot, relative);
+  if (!isWithin(stagingRoot, destination)) {
+    throw new BenchmarkPhaseError("unsafe_path", `source escapes staging root: ${input.source}`);
+  }
+  assertNoSymlinkTraversal(stagingRoot, relative);
+  try {
+    fs81.lstatSync(destination);
+    return await cachedVerifiedInput(stagingRoot, input, context);
+  } catch (error2) {
+    if (error2.code !== "ENOENT")
+      throw error2;
+  }
+  const rawUrl = process.env[envName];
+  if (!rawUrl) {
+    throw new BenchmarkPhaseError("missing_environment", `required signed download URL environment variable is missing: ${envName}`);
+  }
+  let url2;
+  try {
+    url2 = new URL(rawUrl);
+  } catch {
+    throw new BenchmarkPhaseError("invalid_download_url", `signed download URL environment variable is invalid: ${envName}`);
+  }
+  if (url2.protocol !== "https:" || url2.username || url2.password) {
+    throw new BenchmarkPhaseError("invalid_download_url", `signed download URL environment variable must contain an HTTPS URL without credentials: ${envName}`);
+  }
+  const remainingMs = context.deadline - Date.now();
+  if (remainingMs <= 0) {
+    throw new BenchmarkPhaseError("phase_timeout", "phase budget expired");
+  }
+  fs81.mkdirSync(path88.dirname(destination), { recursive: true, mode: 448 });
+  assertNoSymlinkTraversal(stagingRoot, relative);
+  assertWritableDestination(stagingRoot, relative);
+  const temporary = `${destination}.${process.pid}.${crypto6.randomBytes(6).toString("hex")}.download`;
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), remainingMs);
+  let descriptor;
+  try {
+    let response;
+    try {
+      response = await fetch(url2, {
+        redirect: "error",
+        signal: controller.signal
+      });
+    } catch {
+      if (controller.signal.aborted || Date.now() >= context.deadline) {
+        throw new BenchmarkPhaseError("phase_timeout", "phase budget expired");
+      }
+      throw new BenchmarkPhaseError("download_failed", `signed input download failed for ${input.source}`);
+    }
+    if (response.redirected || response.status >= 300 && response.status < 400) {
+      throw new BenchmarkPhaseError("download_redirect_rejected", `signed input download redirected for ${input.source}`);
+    }
+    if (!response.ok || !response.body) {
+      throw new BenchmarkPhaseError("download_failed", `signed input download failed for ${input.source}`, { status: response.status });
+    }
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > input.size_bytes) {
+      throw new BenchmarkPhaseError("size_mismatch", `size mismatch for ${input.source}`, { expected: input.size_bytes, actual: Number(declaredLength) });
+    }
+    descriptor = fs81.openSync(temporary, "wx", 384);
+    const reader = response.body.getReader();
+    let actual;
+    let size2 = 0;
+    try {
+      const hash = crypto6.createHash("sha256");
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        assertBudget(context);
+        size2 += value.byteLength;
+        if (size2 > input.size_bytes) {
+          throw new BenchmarkPhaseError("size_mismatch", `size mismatch for ${input.source}`, { expected: input.size_bytes, actual: size2 });
+        }
+        hash.update(value);
+        let offset = 0;
+        while (offset < value.byteLength) {
+          offset += fs81.writeSync(descriptor, value, offset, value.byteLength - offset);
+        }
+      }
+      actual = hash.digest("hex");
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {}
+    }
+    if (size2 !== input.size_bytes) {
+      throw new BenchmarkPhaseError("size_mismatch", `size mismatch for ${input.source}`, { expected: input.size_bytes, actual: size2 });
+    }
+    if (actual !== input.sha256) {
+      throw new BenchmarkPhaseError("digest_mismatch", `checksum mismatch for ${input.source}`, { expected: input.sha256, actual });
+    }
+    fs81.fsyncSync(descriptor);
+    fs81.closeSync(descriptor);
+    descriptor = undefined;
+    assertNoSymlinkTraversal(stagingRoot, relative);
+    if (fs81.existsSync(destination)) {
+      return await cachedVerifiedInput(stagingRoot, input, context);
+    }
+    fs81.renameSync(temporary, destination);
+    return await cachedVerifiedInput(stagingRoot, input, context);
+  } catch (error2) {
+    if (!(error2 instanceof BenchmarkPhaseError) && (controller.signal.aborted || Date.now() >= context.deadline)) {
+      throw new BenchmarkPhaseError("phase_timeout", "phase budget expired");
+    }
+    if (error2 instanceof BenchmarkPhaseError)
+      throw error2;
+    throw new BenchmarkPhaseError("download_failed", `signed input download failed for ${input.source}`);
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+    if (descriptor !== undefined)
+      fs81.closeSync(descriptor);
+    fs81.rmSync(temporary, { force: true });
+  }
+}
+function readExactly(descriptor, length, position) {
+  const buffer = Buffer.alloc(length);
+  let offset = 0;
+  while (offset < length) {
+    const count = fs81.readSync(descriptor, buffer, offset, length - offset, position + offset);
+    if (count === 0) {
+      throw new BenchmarkPhaseError("invalid_archive", "archive ended unexpectedly");
+    }
+    offset += count;
+  }
+  return buffer;
+}
+function decodeZipPath(value, utf8) {
+  if (!utf8 && value.some((byte) => byte >= 128)) {
+    throw new BenchmarkPhaseError("invalid_archive", "ZIP members with non-UTF-8 names are unsupported");
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(value);
+  } catch {
+    throw new BenchmarkPhaseError("invalid_archive", "ZIP member name is not valid UTF-8");
+  }
+}
+function findZipMembers(archivePath, requested, context) {
+  const descriptor = fs81.openSync(archivePath, "r");
+  try {
+    assertBudget(context);
+    const archiveSize = fs81.fstatSync(descriptor).size;
+    const tailSize = Math.min(archiveSize, MAX_ZIP_EOCD_BYTES);
+    const tailOffset = archiveSize - tailSize;
+    const tail2 = readExactly(descriptor, tailSize, tailOffset);
+    let eocdOffset = -1;
+    for (let offset2 = tail2.length - 22;offset2 >= 0; offset2 -= 1) {
+      assertBudget(context);
+      if (tail2.readUInt32LE(offset2) === ZIP_EOCD_SIGNATURE) {
+        const commentLength = tail2.readUInt16LE(offset2 + 20);
+        if (offset2 + 22 + commentLength === tail2.length) {
+          eocdOffset = offset2;
+          break;
+        }
+      }
+    }
+    if (eocdOffset < 0) {
+      throw new BenchmarkPhaseError("invalid_archive", "invalid ZIP archive");
+    }
+    const diskNumber = tail2.readUInt16LE(eocdOffset + 4);
+    const directoryDisk = tail2.readUInt16LE(eocdOffset + 6);
+    const diskEntries = tail2.readUInt16LE(eocdOffset + 8);
+    const totalEntries = tail2.readUInt16LE(eocdOffset + 10);
+    const directorySize = tail2.readUInt32LE(eocdOffset + 12);
+    const directoryOffset = tail2.readUInt32LE(eocdOffset + 16);
+    if (diskNumber !== 0 || directoryDisk !== 0 || diskEntries !== totalEntries) {
+      throw new BenchmarkPhaseError("invalid_archive", "multi-disk ZIP archives are unsupported");
+    }
+    if (totalEntries === 65535 || directorySize === 4294967295 || directoryOffset === 4294967295) {
+      throw new BenchmarkPhaseError("invalid_archive", "ZIP64 archives are unsupported");
+    }
+    if (totalEntries > MAX_ARCHIVE_MEMBERS || directoryOffset + directorySize > tailOffset + eocdOffset) {
+      throw new BenchmarkPhaseError("invalid_archive", "ZIP central directory is invalid");
+    }
+    let offset = directoryOffset;
+    const found = new Map;
+    for (let index = 0;index < totalEntries; index += 1) {
+      assertBudget(context);
+      const header = readExactly(descriptor, 46, offset);
+      if (header.readUInt32LE(0) !== ZIP_CENTRAL_SIGNATURE) {
+        throw new BenchmarkPhaseError("invalid_archive", "ZIP central directory is invalid");
+      }
+      const flags = header.readUInt16LE(8);
+      const compressionMethod = header.readUInt16LE(10);
+      const compressedSize = header.readUInt32LE(20);
+      const uncompressedSize = header.readUInt32LE(24);
+      const nameLength = header.readUInt16LE(28);
+      const extraLength = header.readUInt16LE(30);
+      const commentLength = header.readUInt16LE(32);
+      const diskStart = header.readUInt16LE(34);
+      const externalAttributes = header.readUInt32LE(38);
+      const localHeaderOffset = header.readUInt32LE(42);
+      const recordSize = 46 + nameLength + extraLength + commentLength;
+      if (offset + recordSize > directoryOffset + directorySize || compressedSize === 4294967295 || uncompressedSize === 4294967295 || localHeaderOffset === 4294967295 || diskStart !== 0) {
+        throw new BenchmarkPhaseError("invalid_archive", "ZIP member metadata is invalid");
+      }
+      const name = decodeZipPath(readExactly(descriptor, nameLength, offset + 46), (flags & 2048) !== 0);
+      const material = requested.get(name);
+      if (material) {
+        if (found.has(name)) {
+          throw new BenchmarkPhaseError("invalid_archive", `archive member is duplicated: ${name}`);
+        }
+        const madeBy = header.readUInt16LE(4) >> 8;
+        const unixMode = externalAttributes >>> 16;
+        const fileType = unixMode & 61440;
+        if (name.endsWith("/") || (externalAttributes & 16) !== 0 || madeBy === 3 && fileType !== 0 && fileType !== 32768) {
+          throw new BenchmarkPhaseError("invalid_archive", `archive member must be a regular file: ${name}`);
+        }
+        if ((flags & 1) !== 0 || compressionMethod !== 0 && compressionMethod !== 8) {
+          throw new BenchmarkPhaseError("invalid_archive", `archive member uses unsupported ZIP features: ${name}`);
+        }
+        if (uncompressedSize !== material.file_size_bytes) {
+          throw new BenchmarkPhaseError("size_mismatch", `size mismatch for archive member ${name}`, { expected: material.file_size_bytes, actual: uncompressedSize });
+        }
+        const localHeader = readExactly(descriptor, 30, localHeaderOffset);
+        if (localHeader.readUInt32LE(0) !== ZIP_LOCAL_SIGNATURE || localHeader.readUInt16LE(6) !== flags || localHeader.readUInt16LE(8) !== compressionMethod) {
+          throw new BenchmarkPhaseError("invalid_archive", "ZIP local header is invalid");
+        }
+        const localNameLength = localHeader.readUInt16LE(26);
+        const localExtraLength = localHeader.readUInt16LE(28);
+        const localName = decodeZipPath(readExactly(descriptor, localNameLength, localHeaderOffset + 30), (flags & 2048) !== 0);
+        const dataOffset = localHeaderOffset + 30 + localNameLength + localExtraLength;
+        if (localName !== name || dataOffset + compressedSize > directoryOffset) {
+          throw new BenchmarkPhaseError("invalid_archive", "ZIP member bounds are invalid");
+        }
+        found.set(name, {
+          compressionMethod,
+          compressedSize,
+          dataOffset
+        });
+      }
+      offset += recordSize;
+    }
+    if (offset !== directoryOffset + directorySize) {
+      throw new BenchmarkPhaseError("invalid_archive", "ZIP central directory is invalid");
+    }
+    for (const memberPath of requested.keys()) {
+      if (!found.has(memberPath)) {
+        throw new BenchmarkPhaseError("missing_input", `archive member does not exist: ${memberPath}`);
+      }
+    }
+    return found;
+  } finally {
+    fs81.closeSync(descriptor);
+  }
+}
+async function writeVerifiedArchiveMember(source, destination, material, context) {
+  fs81.mkdirSync(path88.dirname(destination), { recursive: true, mode: 448 });
+  const temporary = `${destination}.${process.pid}.${crypto6.randomBytes(6).toString("hex")}.tmp`;
+  const descriptor = fs81.openSync(temporary, "wx", 384);
+  const hash = crypto6.createHash("sha256");
+  let size2 = 0;
+  try {
+    for await (const value of source) {
+      assertBudget(context);
+      const chunk2 = Buffer.isBuffer(value) ? value : Buffer.from(value);
+      size2 += chunk2.length;
+      if (size2 > material.file_size_bytes) {
+        throw new BenchmarkPhaseError("size_mismatch", `size mismatch for archive member ${material.archive_path}`, { expected: material.file_size_bytes, actual: size2 });
+      }
+      hash.update(chunk2);
+      let offset = 0;
+      while (offset < chunk2.length) {
+        offset += fs81.writeSync(descriptor, chunk2, offset, chunk2.length - offset);
+      }
+    }
+    if (size2 !== material.file_size_bytes) {
+      throw new BenchmarkPhaseError("size_mismatch", `size mismatch for archive member ${material.archive_path}`, { expected: material.file_size_bytes, actual: size2 });
+    }
+    const actual = hash.digest("hex");
+    if (actual !== material.file_sha256) {
+      throw new BenchmarkPhaseError("digest_mismatch", `checksum mismatch for archive member ${material.archive_path}`, { expected: material.file_sha256, actual });
+    }
+    fs81.fsyncSync(descriptor);
+    fs81.closeSync(descriptor);
+    fs81.renameSync(temporary, destination);
+  } catch (error2) {
+    if (error2 instanceof BenchmarkPhaseError)
+      throw error2;
+    throw new BenchmarkPhaseError("invalid_archive", `archive member could not be extracted: ${material.archive_path}`);
+  } finally {
+    try {
+      fs81.closeSync(descriptor);
+    } catch {}
+    fs81.rmSync(temporary, { force: true });
+  }
+}
+function isZipArchive(archivePath) {
+  const descriptor = fs81.openSync(archivePath, "r");
+  try {
+    const header = Buffer.alloc(4);
+    return fs81.readSync(descriptor, header, 0, header.length, 0) === header.length && [
+      ZIP_LOCAL_SIGNATURE,
+      ZIP_EOCD_SIGNATURE,
+      134695760
+    ].includes(header.readUInt32LE(0));
+  } finally {
+    fs81.closeSync(descriptor);
+  }
+}
+function isGzipArchive(archivePath) {
+  const descriptor = fs81.openSync(archivePath, "r");
+  try {
+    const header = Buffer.alloc(2);
+    return fs81.readSync(descriptor, header, 0, header.length, 0) === header.length && header[0] === 31 && header[1] === 139;
+  } finally {
+    fs81.closeSync(descriptor);
+  }
+}
+function archiveSourceCacheKey(material) {
+  return [
+    material.source,
+    material.sha256,
+    material.size_bytes,
+    material.download_url_env ?? ""
+  ].join("\x00");
+}
+function archiveMemberCacheKey(material) {
+  return [
+    archiveSourceCacheKey(material),
+    material.archive_path,
+    material.file_sha256,
+    material.file_size_bytes
+  ].join("\x00");
+}
+function archiveScanBudget(context) {
+  let scanned = 0;
+  return new Transform2({
+    transform(chunk2, _encoding, callback) {
+      try {
+        assertBudget(context);
+        scanned += chunk2.length;
+        if (scanned > MAX_ARCHIVE_SCAN_BYTES) {
+          throw new BenchmarkPhaseError("invalid_archive", "archive expands beyond the supported scan limit");
+        }
+        callback(null, chunk2);
+      } catch (error2) {
+        callback(error2);
+      }
+    }
+  });
+}
+async function extractArchiveMembers(archivePath, outputRoot, materials, context) {
+  const requested = new Map;
+  for (const material of materials) {
+    let memberPath;
+    try {
+      memberPath = safeRelPath(material.archive_path);
+    } catch {
+      throw new BenchmarkPhaseError("unsafe_path", "archive member path is unsafe");
+    }
+    const existing = requested.get(memberPath);
+    if (existing && (existing.file_sha256 !== material.file_sha256 || existing.file_size_bytes !== material.file_size_bytes)) {
+      throw new BenchmarkPhaseError("invalid_archive", `archive member has conflicting declarations: ${memberPath}`);
+    }
+    requested.set(memberPath, material);
+  }
+  const extracted = new Map;
+  if (isZipArchive(archivePath)) {
+    const indexed = findZipMembers(archivePath, requested, context);
+    for (const [memberPath, material] of requested) {
+      assertBudget(context);
+      const destination = path88.resolve(outputRoot, memberPath);
+      if (!isWithin(outputRoot, destination)) {
+        throw new BenchmarkPhaseError("unsafe_path", `archive member escapes output root: ${memberPath}`);
+      }
+      const member = indexed.get(memberPath);
+      const compressed = member.compressedSize === 0 ? Readable.from([]) : fs81.createReadStream(archivePath, {
+        start: member.dataOffset,
+        end: member.dataOffset + member.compressedSize - 1
+      });
+      const contents = member.compressionMethod === 8 ? compressed.pipe(createInflateRaw()) : compressed;
+      await writeVerifiedArchiveMember(contents, destination, material, context);
+      extracted.set(memberPath, destination);
+    }
+    return extracted;
+  }
+  const matches2 = new Map;
+  let validationError;
+  const unpack = co({
+    cwd: outputRoot,
+    strict: true,
+    preserveOwner: false,
+    filter: (entryPath, entryAny) => {
+      assertBudget(context);
+      const material = requested.get(entryPath);
+      if (!material)
+        return false;
+      const count = (matches2.get(entryPath) ?? 0) + 1;
+      matches2.set(entryPath, count);
+      const entry = entryAny;
+      if (count > 1) {
+        validationError = new BenchmarkPhaseError("invalid_archive", `archive member is duplicated: ${entryPath}`);
+        return false;
+      }
+      if (!["File", "OldFile", "ContiguousFile"].includes(entry.type)) {
+        validationError = new BenchmarkPhaseError("invalid_archive", `archive member must be a regular file: ${entryPath}`);
+        return false;
+      }
+      if (entry.size !== material.file_size_bytes) {
+        validationError = new BenchmarkPhaseError("size_mismatch", `size mismatch for archive member ${entryPath}`, { expected: material.file_size_bytes, actual: entry.size });
+        return false;
+      }
+      return true;
+    }
+  });
+  const archive = fs81.createReadStream(archivePath);
+  const scanBudget = archiveScanBudget(context);
+  try {
+    if (isGzipArchive(archivePath)) {
+      await pipeline2(archive, createGunzip(), scanBudget, unpack);
+    } else {
+      await pipeline2(archive, scanBudget, unpack);
+    }
+  } catch (error2) {
+    if (validationError)
+      throw validationError;
+    if (error2 instanceof BenchmarkPhaseError)
+      throw error2;
+    throw new BenchmarkPhaseError("invalid_archive", "archive members could not be extracted");
+  }
+  if (validationError)
+    throw validationError;
+  for (const [memberPath, material] of requested) {
+    if (!matches2.has(memberPath)) {
+      throw new BenchmarkPhaseError("missing_input", `archive member does not exist: ${memberPath}`);
+    }
+    const verified = await verifyInput(outputRoot, {
+      source: memberPath,
+      sha256: material.file_sha256,
+      size_bytes: material.file_size_bytes
+    });
+    assertBudget(context);
+    extracted.set(memberPath, verified.source);
+  }
+  return extracted;
 }
 async function atomicCopy(source, destination, mode, sourceRoot) {
   fs81.mkdirSync(path88.dirname(destination), { recursive: true });
@@ -79017,21 +79613,31 @@ async function recordFile(root, filePath, rootName, kind = "file") {
     fs81.closeSync(opened.fd);
   }
 }
-async function copyMaterial(material, sourceRoot, destinationRoot, destinationRootName, protectWorkspace) {
-  const source = await verifyInput(sourceRoot, material);
+async function copyMaterial(material, sourceRoot, destinationRoot, destinationRootName, protectWorkspace, context) {
+  const verifiedSource = material.kind === "archive_file" ? undefined : await cachedVerifiedInput(sourceRoot, material, context);
+  const source = material.kind === "archive_file" ? context.preparedArchiveFiles.get(archiveMemberCacheKey(material)) : verifiedSource?.source;
+  if (!source) {
+    throw new BenchmarkPhaseError("invalid_archive", `archive member was not prepared: ${material.id}`);
+  }
   const destinationRel = protectWorkspace ? workspaceRel(material.destination, material.kind === "tar_gz") : normalizedRootRelative(material.destination);
   if (!protectWorkspace && destinationRel.toLowerCase() === ".brainbase-benchmark-owner.json") {
     throw new BenchmarkPhaseError("reserved_path", "benchmark input cannot replace the phase ownership marker");
   }
-  if (material.kind === "file") {
+  if (material.kind === "file" || material.kind === "archive_file") {
     if (destinationRel === ".") {
       throw new BenchmarkPhaseError("unsafe_path", "file destination cannot be a directory root");
     }
     assertWritableDestination(destinationRoot, destinationRel);
     const destination = path88.resolve(destinationRoot, destinationRel);
-    await atomicCopy(source, destination, material.mode, sourceRoot);
+    if (material.kind === "file") {
+      await atomicCopy(source, destination, material.mode ?? verifiedSource?.mode, sourceRoot);
+    } else {
+      await atomicCopy(source, destination, material.mode, path88.dirname(source));
+    }
     const record3 = await recordFile(destinationRoot, destination, destinationRootName);
-    if (record3.sha256 !== material.sha256 || record3.size !== material.size_bytes) {
+    const expectedSha256 = material.kind === "archive_file" ? material.file_sha256 : material.sha256;
+    const expectedSize = material.kind === "archive_file" ? material.file_size_bytes : material.size_bytes;
+    if (record3.sha256 !== expectedSha256 || record3.size !== expectedSize) {
       throw new BenchmarkPhaseError("evidence_tampered", `material changed while it was copied: ${material.source}`);
     }
     return [record3];
@@ -79072,17 +79678,39 @@ async function copyMaterial(material, sourceRoot, destinationRoot, destinationRo
     fs81.rmSync(temporary, { recursive: true, force: true });
   }
 }
-async function preflightMaterial(material, sourceRoot, destinationRoot, protectWorkspace) {
-  const source = await verifyInput(sourceRoot, material);
+async function preflightMaterial(material, materials, sourceRoot, destinationRoot, protectWorkspace, context) {
+  const source = (await cachedVerifiedInput(sourceRoot, material, context)).source;
   const destinationRel = protectWorkspace ? workspaceRel(material.destination, material.kind === "tar_gz") : normalizedRootRelative(material.destination);
   if (!protectWorkspace && destinationRel.toLowerCase() === ".brainbase-benchmark-owner.json") {
     throw new BenchmarkPhaseError("reserved_path", "benchmark input cannot replace the phase ownership marker");
   }
-  if (material.kind === "file") {
+  if (material.kind === "file" || material.kind === "archive_file") {
     if (destinationRel === ".") {
       throw new BenchmarkPhaseError("unsafe_path", "file destination cannot be a directory root");
     }
     assertWritableDestination(destinationRoot, destinationRel);
+    if (material.kind === "archive_file") {
+      const cacheKey = archiveMemberCacheKey(material);
+      let extracted = context.preparedArchiveFiles.get(cacheKey);
+      if (!extracted) {
+        const temporary2 = fs81.mkdtempSync(path88.join(os16.tmpdir(), "brainbase-benchmark-member-"));
+        context.temporaryRoots.add(temporary2);
+        const archiveKey = archiveSourceCacheKey(material);
+        const related = materials.filter((candidate) => candidate.kind === "archive_file" && archiveSourceCacheKey(candidate) === archiveKey);
+        const extractedMembers = await extractArchiveMembers(source, temporary2, related, context);
+        for (const candidate of related) {
+          const prepared = extractedMembers.get(safeRelPath(candidate.archive_path));
+          if (!prepared) {
+            throw new BenchmarkPhaseError("missing_input", `archive member does not exist: ${candidate.archive_path}`);
+          }
+          context.preparedArchiveFiles.set(archiveMemberCacheKey(candidate), prepared);
+        }
+        extracted = context.preparedArchiveFiles.get(cacheKey);
+      }
+      if (!extracted) {
+        throw new BenchmarkPhaseError("missing_input", `archive member does not exist: ${material.archive_path}`);
+      }
+    }
     return [destinationRel];
   }
   const temporary = fs81.mkdtempSync(path88.join(os16.tmpdir(), "brainbase-benchmark-preflight-"));
@@ -79150,14 +79778,18 @@ function prepareOwnedDirectory(root, role, spec) {
 }
 function buildEnvironment(spec, secretNames, additions = {}) {
   const env3 = {};
+  const remoteUrlEnvNames = remoteUrlEnvironmentNames(spec);
   for (const name of BASE_ENV_NAMES) {
-    if (process.env[name] !== undefined)
+    if (!remoteUrlEnvNames.has(name) && process.env[name] !== undefined) {
       env3[name] = process.env[name];
+    }
   }
   for (const [name, declared] of Object.entries(spec.environment)) {
     env3[name] = declared.value;
   }
   for (const name of secretNames) {
+    if (remoteUrlEnvNames.has(name))
+      continue;
     const value = process.env[name];
     if (value === undefined) {
       throw new BenchmarkPhaseError("missing_environment", `required environment variable is missing: ${name}`);
@@ -79169,7 +79801,11 @@ function buildEnvironment(spec, secretNames, additions = {}) {
 }
 function redactCommandOutput(data, spec) {
   let value = data.toString("utf8");
-  for (const name of spec.secret_env) {
+  const sensitiveNames = new Set([
+    ...spec.secret_env,
+    ...remoteUrlEnvironmentNames(spec)
+  ]);
+  for (const name of sensitiveNames) {
     const secret = process.env[name];
     if (secret)
       value = value.split(secret).join("[REDACTED]");
@@ -79339,16 +79975,19 @@ async function executeHydrate(spec, context) {
   const plannedDestinations = [];
   for (const material of spec.materials) {
     assertBudget(context);
-    plannedDestinations.push(...await preflightMaterial(material, spec.staging_root, spec.workspace_root, true));
-    const source = await verifyInput(spec.staging_root, material);
-    context.inputs.push(await recordFile(spec.staging_root, source, "staging"));
+    const verified = await downloadInputReference(spec.staging_root, material, context);
+    plannedDestinations.push(...await preflightMaterial(material, spec.materials, spec.staging_root, spec.workspace_root, true, context));
+    const record3 = stagedInputRecord(spec.staging_root, verified);
+    if (!context.inputs.some((input) => input.path === record3.path && input.sha256 === record3.sha256 && input.size === record3.size)) {
+      context.inputs.push(record3);
+    }
   }
   validateDestinationGraph(plannedDestinations);
   for (const material of spec.materials) {
     assertBudget(context);
     const started = Date.now();
     try {
-      const records = await copyMaterial(material, spec.staging_root, spec.workspace_root, "workspace", true);
+      const records = await copyMaterial(material, spec.staging_root, spec.workspace_root, "workspace", true, context);
       outputs.push(...records);
       context.outputs.push(...records);
       context.steps.push({
@@ -79422,6 +80061,7 @@ async function executeHydrate(spec, context) {
   }
   outputs.splice(0, outputs.length, ...finalOutputs);
   context.outputs.splice(0, context.outputs.length, ...finalOutputs);
+  removeRemoteHydrationInputs(spec);
   assertBudget(context);
   return outputs;
 }
@@ -79627,6 +80267,8 @@ async function evaluateOne(evaluator, spec, finalOutput, trajectory, frozenEvide
   };
 }
 async function executeEvaluate(spec, context) {
+  await downloadInputReference(spec.staging_root, spec.evidence.final_output, context);
+  await downloadInputReference(spec.staging_root, spec.evidence.trajectory, context);
   const finalOutput = await readEvidence(spec.staging_root, spec.evidence.final_output);
   const trajectoryEvidence = await readEvidence(spec.staging_root, spec.evidence.trajectory);
   context.inputs.push(finalOutput.record, trajectoryEvidence.record);
@@ -79640,9 +80282,12 @@ async function executeEvaluate(spec, context) {
   const plannedReferences = [];
   for (const reference of spec.references) {
     assertBudget(context);
-    plannedReferences.push(...await preflightMaterial(reference, spec.staging_root, spec.tests_root, false));
-    const source = await verifyInput(spec.staging_root, reference);
-    context.inputs.push(await recordFile(spec.staging_root, source, "staging"));
+    const verified = await downloadInputReference(spec.staging_root, reference, context);
+    plannedReferences.push(...await preflightMaterial(reference, spec.references, spec.staging_root, spec.tests_root, false, context));
+    const record3 = stagedInputRecord(spec.staging_root, verified);
+    if (!context.inputs.some((input) => input.path === record3.path && input.sha256 === record3.sha256 && input.size === record3.size)) {
+      context.inputs.push(record3);
+    }
   }
   validateDestinationGraph(plannedReferences);
   assertBudget(context);
@@ -79707,7 +80352,7 @@ async function executeEvaluate(spec, context) {
   }
   await verifyRecordsUnchanged(manifest, spec);
   for (const reference of spec.references) {
-    const referenceOutputs = await copyMaterial(reference, spec.staging_root, spec.tests_root, "tests", false);
+    const referenceOutputs = await copyMaterial(reference, spec.staging_root, spec.tests_root, "tests", false, context);
     outputs.push(...referenceOutputs);
     context.outputs.push(...referenceOutputs);
   }
@@ -79857,19 +80502,26 @@ function prepareBenchmarkPhaseInvocation(specPathInput, resultPathInput, expecte
       spec_digest: digest,
       timeout_ms: spec.budget.timeout_ms
     };
+    let cachedResult;
     if (fs81.existsSync(resultPath)) {
       try {
         const cached2 = JSON.parse(fs81.readFileSync(resultPath, "utf8"));
         if (cached2.schema_version === SCHEMA_VERSION && cached2.phase === spec.phase && cached2.attempt_id === spec.attempt_id && cached2.phase_id === spec.phase_id && cached2.spec_digest === digest && cached2.status === "succeeded") {
-          return {
-            ok: true,
-            invocation,
-            spec_bytes: bytes,
-            cached_result: cached2
-          };
+          cachedResult = cached2;
         }
       } catch {}
     }
+    if (cachedResult) {
+      if (spec.phase === "hydrate") {
+        removeRemoteHydrationInputs(spec);
+      }
+      return {
+        ok: true,
+        invocation,
+        spec_bytes: bytes,
+        cached_result: cachedResult
+      };
+    }
     return { ok: true, invocation, spec_bytes: bytes };
   } catch (error2) {
     return {
@@ -79966,14 +80618,21 @@ async function runBenchmarkPhase(specPathInput, resultPathInput, expectedPhase,
       throw new BenchmarkPhaseError("invalid_result_path", `result path must be ${expectedResultPath}`);
     }
     resultPathValidated = true;
+    let cachedResult;
     if (fs81.existsSync(resultPath)) {
       try {
         const cached2 = JSON.parse(fs81.readFileSync(resultPath, "utf8"));
         if (cached2.schema_version === SCHEMA_VERSION && cached2.phase === spec.phase && cached2.attempt_id === spec.attempt_id && cached2.phase_id === spec.phase_id && cached2.spec_digest === digest && cached2.status === "succeeded") {
-          return { exitCode: 0, result: cached2 };
+          cachedResult = cached2;
         }
       } catch {}
     }
+    if (cachedResult) {
+      if (spec.phase === "hydrate") {
+        removeRemoteHydrationInputs(spec);
+      }
+      return { exitCode: 0, result: cachedResult };
+    }
     context = {
       deadline: started + spec.budget.timeout_ms,
       remainingOutputBytes: spec.budget.max_output_bytes,
@@ -79981,7 +80640,10 @@ async function runBenchmarkPhase(specPathInput, resultPathInput, expectedPhase,
       evaluators: [],
       inputs: [],
       outputs: [],
-      logsOwned: false
+      logsOwned: false,
+      verifiedInputs: new Map,
+      preparedArchiveFiles: new Map,
+      temporaryRoots: new Set
     };
     if (spec.phase === "hydrate") {
       outputs = await executeHydrate(spec, context);
@@ -80001,6 +80663,11 @@ async function runBenchmarkPhase(specPathInput, resultPathInput, expectedPhase,
         evaluators = context.evaluators;
     }
   }
+  if (context) {
+    for (const temporary of context.temporaryRoots) {
+      fs81.rmSync(temporary, { recursive: true, force: true });
+    }
+  }
   const result2 = {
     schema_version: SCHEMA_VERSION,
     cli_version: VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainbase-labs/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   "type": "module",
   "bin": {