@visulima/task-runner 1.0.0-alpha.8 → 1.0.0-alpha.9

package/dist/packem_shared/ReapiRemoteCache-vgRxDMmu.js

@@ -0,0 +1,1012 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  randomUUID
+} = __cjs_getBuiltinModule("node:crypto");
+const {
+  createWriteStream
+} = __cjs_getBuiltinModule("node:fs");
+const {
+  mkdir,
+  rm
+} = __cjs_getBuiltinModule("node:fs/promises");
+const {
+  Readable
+} = __cjs_getBuiltinModule("node:stream");
+const {
+  pipeline
+} = __cjs_getBuiltinModule("node:stream/promises");
+import { dirname } from '@visulima/path';
+
+const REMOTE_EXECUTION_PROTO = `syntax = "proto3";
+
+package build.bazel.remote.execution.v2;
+
+message Digest {
+  string hash = 1;
+  int64 size_bytes = 2;
+}
+
+message NodeProperties {
+  repeated NodeProperty properties = 1;
+  string mtime = 2;
+  uint32 unix_mode = 3;
+}
+
+message NodeProperty {
+  string name = 1;
+  string value = 2;
+}
+
+message OutputFile {
+  string path = 1;
+  Digest digest = 2;
+  bool is_executable = 4;
+  bytes contents = 5;
+  NodeProperties node_properties = 7;
+}
+
+message OutputDirectory {
+  string path = 1;
+  Digest tree_digest = 3;
+  bool is_topologically_sorted = 4;
+  Digest root_directory_digest = 5;
+}
+
+message OutputSymlink {
+  string path = 1;
+  string target = 2;
+  NodeProperties node_properties = 3;
+}
+
+message ActionResult {
+  repeated OutputFile output_files = 2;
+  repeated OutputSymlink output_file_symlinks = 10;
+  repeated OutputSymlink output_symlinks = 12;
+  repeated OutputDirectory output_directories = 3;
+  repeated OutputSymlink output_directory_symlinks = 11;
+  int32 exit_code = 4;
+  bytes stdout_raw = 5;
+  Digest stdout_digest = 6;
+  bytes stderr_raw = 7;
+  Digest stderr_digest = 8;
+}
+
+message FindMissingBlobsRequest {
+  string instance_name = 1;
+  repeated Digest blob_digests = 2;
+  DigestFunction.Value digest_function = 3;
+}
+
+message FindMissingBlobsResponse {
+  repeated Digest missing_blob_digests = 2;
+}
+
+message BatchUpdateBlobsRequest {
+  message Request {
+    Digest digest = 1;
+    bytes data = 2;
+    Compressor.Value compressor = 3;
+  }
+  string instance_name = 1;
+  repeated Request requests = 2;
+  DigestFunction.Value digest_function = 5;
+}
+
+message BatchUpdateBlobsResponse {
+  message Response {
+    Digest digest = 1;
+    Status status = 2;
+  }
+  repeated Response responses = 1;
+}
+
+message BatchReadBlobsRequest {
+  string instance_name = 1;
+  repeated Digest digests = 2;
+  repeated Compressor.Value acceptable_compressors = 3;
+  DigestFunction.Value digest_function = 4;
+}
+
+message BatchReadBlobsResponse {
+  message Response {
+    Digest digest = 1;
+    bytes data = 2;
+    Compressor.Value compressor = 4;
+    Status status = 3;
+  }
+  repeated Response responses = 1;
+}
+
+message GetActionResultRequest {
+  string instance_name = 1;
+  Digest action_digest = 2;
+  bool inline_stdout = 3;
+  bool inline_stderr = 4;
+  repeated string inline_output_files = 5;
+  DigestFunction.Value digest_function = 6;
+}
+
+message UpdateActionResultRequest {
+  string instance_name = 1;
+  Digest action_digest = 2;
+  ActionResult action_result = 3;
+  ResultsCachePolicy results_cache_policy = 4;
+  DigestFunction.Value digest_function = 5;
+}
+
+message ResultsCachePolicy {
+  int32 priority = 1;
+}
+
+message GetCapabilitiesRequest {
+  string instance_name = 1;
+}
+
+message ServerCapabilities {
+  CacheCapabilities cache_capabilities = 1;
+  ExecutionCapabilities execution_capabilities = 2;
+  SemVer deprecated_api_version = 3;
+  SemVer low_api_version = 4;
+  SemVer high_api_version = 5;
+}
+
+message ExecutionCapabilities {
+  DigestFunction.Value digest_function = 1;
+  bool exec_enabled = 2;
+  PriorityCapabilities execution_priority_capabilities = 3;
+  repeated string supported_node_properties = 4;
+  repeated DigestFunction.Value digest_functions = 5;
+}
+
+message CacheCapabilities {
+  repeated DigestFunction.Value digest_functions = 1;
+  ActionCacheUpdateCapabilities action_cache_update_capabilities = 2;
+  PriorityCapabilities cache_priority_capabilities = 3;
+  int64 max_batch_total_size_bytes = 4;
+  SymlinkAbsolutePathStrategy.Value symlink_absolute_path_strategy = 5;
+  repeated Compressor.Value supported_compressors = 6;
+  repeated Compressor.Value supported_batch_update_compressors = 7;
+}
+
+message ActionCacheUpdateCapabilities {
+  bool update_enabled = 1;
+}
+
+message PriorityCapabilities {
+  message PriorityRange {
+    int32 min_priority = 1;
+    int32 max_priority = 2;
+  }
+  repeated PriorityRange priorities = 1;
+}
+
+message SymlinkAbsolutePathStrategy {
+  enum Value {
+    UNKNOWN = 0;
+    DISALLOWED = 1;
+    ALLOWED = 2;
+  }
+}
+
+message DigestFunction {
+  enum Value {
+    UNKNOWN = 0;
+    SHA256 = 1;
+    SHA1 = 2;
+    MD5 = 3;
+    VSO = 4;
+    SHA384 = 5;
+    SHA512 = 6;
+    MURMUR3 = 7;
+    SHA256TREE = 8;
+    BLAKE3 = 9;
+  }
+}
+
+message Compressor {
+  enum Value {
+    IDENTITY = 0;
+    ZSTD = 1;
+    DEFLATE = 2;
+    BROTLI = 3;
+  }
+}
+
+message SemVer {
+  int32 major = 1;
+  int32 minor = 2;
+  string patch = 3;
+  string prerelease = 4;
+}
+
+message Status {
+  int32 code = 1;
+  string message = 2;
+}
+
+service ContentAddressableStorage {
+  rpc FindMissingBlobs(FindMissingBlobsRequest) returns (FindMissingBlobsResponse);
+  rpc BatchUpdateBlobs(BatchUpdateBlobsRequest) returns (BatchUpdateBlobsResponse);
+  rpc BatchReadBlobs(BatchReadBlobsRequest) returns (BatchReadBlobsResponse);
+}
+
+service ActionCache {
+  rpc GetActionResult(GetActionResultRequest) returns (ActionResult);
+  rpc UpdateActionResult(UpdateActionResultRequest) returns (ActionResult);
+}
+
+service Capabilities {
+  rpc GetCapabilities(GetCapabilitiesRequest) returns (ServerCapabilities);
+}
+`;
+const BYTESTREAM_PROTO = `syntax = "proto3";
+
+package google.bytestream;
+
+message ReadRequest {
+  string resource_name = 1;
+  int64 read_offset = 2;
+  int64 read_limit = 3;
+}
+
+message ReadResponse {
+  bytes data = 10;
+}
+
+message WriteRequest {
+  string resource_name = 1;
+  int64 write_offset = 2;
+  bool finish_write = 3;
+  bytes data = 10;
+}
+
+message WriteResponse {
+  int64 committed_size = 1;
+}
+
+service ByteStream {
+  rpc Read(ReadRequest) returns (stream ReadResponse);
+  rpc Write(stream WriteRequest) returns (WriteResponse);
+}
+`;
+
+let cached;
+const importGrpc = async () => {
+  let grpc;
+  let protoLoader;
+  try {
+    grpc = await import('@grpc/grpc-js');
+  } catch (error) {
+    throw new Error(
+      '[task-runner] remoteCache.backend = "reapi" needs the optional peer dependency `@grpc/grpc-js`. Install it with `pnpm add @grpc/grpc-js` (or your package manager\'s equivalent), or switch to backend: "http".',
+      { cause: error }
+    );
+  }
+  try {
+    protoLoader = await import('@grpc/proto-loader');
+  } catch (error) {
+    throw new Error(
+      '[task-runner] remoteCache.backend = "reapi" needs the optional peer dependency `@grpc/proto-loader`. Install it with `pnpm add @grpc/proto-loader` (or your package manager\'s equivalent), or switch to backend: "http".',
+      { cause: error }
+    );
+  }
+  return { grpc, protoLoader };
+};
+const loadReapiProto = async () => {
+  const { grpc, protoLoader } = await importGrpc();
+  if (cached === void 0) {
+    let protobufjs;
+    try {
+      protobufjs = await import('../packem_chunks/index.js').then(n => n.i);
+    } catch (error) {
+      throw new Error(
+        '[task-runner] remoteCache.backend = "reapi" needs `protobufjs` (normally installed transitively via `@grpc/proto-loader`). Install it with `pnpm add protobufjs` (or your package manager\'s equivalent) if your installer does not hoist transitive deps.',
+        { cause: error }
+      );
+    }
+    const { parse, Root } = protobufjs;
+    const root = new Root();
+    parse(REMOTE_EXECUTION_PROTO, root, { keepCase: true });
+    parse(BYTESTREAM_PROTO, root, { keepCase: true });
+    root.resolveAll();
+    const json = root.toJSON();
+    const definition = protoLoader.fromJSON(json, {
+      arrays: true,
+      defaults: true,
+      enums: String,
+      keepCase: true,
+      longs: Number,
+      objects: true,
+      oneofs: true
+    });
+    const loaded = grpc.loadPackageDefinition(definition);
+    const reapi = loaded.build.bazel.remote.execution.v2;
+    const byteStream = loaded.google.bytestream;
+    cached = {
+      clients: {
+        ActionCache: reapi.ActionCache,
+        ByteStream: byteStream.ByteStream,
+        Capabilities: reapi.Capabilities,
+        ContentAddressableStorage: reapi.ContentAddressableStorage
+      },
+      definition
+    };
+  }
+  return { clients: cached.clients, grpc };
+};
+
+const COMPRESSOR_IDENTITY = "IDENTITY";
+const STATUS_OK = 0;
+const STATUS_NOT_FOUND = 5;
+const STATUS_UNAUTHENTICATED = 16;
+const STATUS_PERMISSION_DENIED = 7;
+const DEFAULT_MAX_BATCH_TOTAL_SIZE_BYTES = 4 * 1024 * 1024;
+const STREAM_CHUNK_SIZE = 64 * 1024;
+const BATCH_ENTRY_OVERHEAD_BYTES = 256;
+const STREAM_DEADLINE_MULTIPLIER = 10;
+const buildReadResourceName = (instanceName, digest) => {
+  const prefix = instanceName === "" ? "" : `${instanceName}/`;
+  return `${prefix}blobs/${digest.hash}/${String(digest.sizeBytes)}`;
+};
+const buildWriteResourceName = (instanceName, digest) => {
+  const prefix = instanceName === "" ? "" : `${instanceName}/`;
+  return `${prefix}uploads/${randomUUID()}/blobs/${digest.hash}/${String(digest.sizeBytes)}`;
+};
+const callUnary = async (client, method, request, metadata, deadlineMs) => {
+  const fn = client[method];
+  if (typeof fn !== "function") {
+    throw new TypeError(`[task-runner] REAPI client is missing method ${method} — proto descriptor mismatch.`);
+  }
+  return new Promise((resolve, reject) => {
+    const callOptions = { deadline: Date.now() + deadlineMs };
+    fn.call(
+      client,
+      request,
+      metadata,
+      callOptions,
+      (error, response) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(response);
+      }
+    );
+  });
+};
+class ReapiRemoteCache {
+  #target;
+  #useTls;
+  #bearerToken;
+  #instanceName;
+  #read;
+  #write;
+  #timeout;
+  #onUploadError;
+  #inflightUploads = /* @__PURE__ */ new Map();
+  #clientsPromise;
+  #capabilities;
+  constructor(options) {
+    const { target, useTls } = parseGrpcUrl(options.url);
+    this.#target = target;
+    this.#useTls = useTls;
+    this.#bearerToken = options.bearerToken;
+    this.#instanceName = options.instanceName ?? "";
+    this.#timeout = options.timeout ?? 3e4;
+    this.#onUploadError = options.onUploadError;
+    const mode = options.mode ?? "readwrite";
+    this.#read = mode === "read" || mode === "readwrite";
+    this.#write = mode === "write" || mode === "readwrite";
+    if (this.#bearerToken !== void 0 && !this.#useTls && options.allowInsecureBearer !== true) {
+      throw new Error(
+        '[task-runner] remoteCache.backend = "reapi" refuses to send a bearer token over cleartext gRPC. Use `grpcs://` (or terminate TLS at a reverse proxy), or pass `allowInsecureBearer: true` for trusted-boundary deployments (loopback, mesh mTLS sidecar).'
+      );
+    }
+  }
+  /**
+   * Close all gRPC channels held by this backend. Idempotent — safe
+   * to call multiple times, and safe to call before any RPC was
+   * issued. If `#getClients` is currently in flight we await its
+   * resolution so the underlying channels are observable to close.
+   */
+  async close() {
+    const pending = this.#clientsPromise;
+    if (pending === void 0) {
+      return;
+    }
+    this.#clientsPromise = void 0;
+    let resolved;
+    try {
+      resolved = await pending;
+    } catch {
+      return;
+    }
+    for (const client of [resolved.actionCache, resolved.byteStream, resolved.capabilities, resolved.cas]) {
+      try {
+        client.close();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Diagnostic probe — fetches the server's `Capabilities` RPC response
+   * (or the cached value, if a previous call already negotiated). Used
+   * by `vis cache doctor` to surface what the server advertises without
+   * forcing the operator to issue a real CAS RPC.
+   *
+   * Bypasses the read/write mode gate intentionally: a probe must work
+   * even on a cache configured `mode: "write"` so the operator can
+   * verify the connection regardless of how the runner uses it.
+   */
+  async probeCapabilities() {
+    return this.#negotiateCapabilities();
+  }
+  async containsAction(actionDigest) {
+    if (!this.#read) {
+      return false;
+    }
+    await this.#assertSha256Supported();
+    try {
+      const { actionCache } = await this.#getClients();
+      const metadata = await this.#buildMetadata();
+      await callUnary(
+        actionCache,
+        "GetActionResult",
+        {
+          action_digest: digestToProto(actionDigest),
+          inline_stderr: false,
+          inline_stdout: false,
+          instance_name: this.#instanceName
+        },
+        metadata,
+        this.#timeout
+      );
+      return true;
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async fetchBlob(digest, destinationPath) {
+    if (!this.#read) {
+      return false;
+    }
+    await this.#assertSha256Supported();
+    try {
+      const maxBatchSize = await this.#getMaxBatchSize();
+      await mkdir(dirname(destinationPath), { recursive: true });
+      if (digest.sizeBytes <= maxBatchSize) {
+        const bytes = await this.#batchReadOne(digest);
+        if (bytes === void 0) {
+          return false;
+        }
+        await pipeline(Readable.from(bytes), createWriteStream(destinationPath));
+        return true;
+      }
+      return await this.#streamRead(digest, destinationPath);
+    } catch {
+      await rm(destinationPath, { force: true }).catch(() => {
+      });
+      return false;
+    }
+  }
+  async retrieveAction(actionDigest) {
+    if (!this.#read) {
+      return null;
+    }
+    await this.#assertSha256Supported();
+    try {
+      const { actionCache } = await this.#getClients();
+      const metadata = await this.#buildMetadata();
+      const proto = await callUnary(
+        actionCache,
+        "GetActionResult",
+        {
+          action_digest: digestToProto(actionDigest),
+          inline_stderr: false,
+          inline_stdout: false,
+          instance_name: this.#instanceName
+        },
+        metadata,
+        this.#timeout
+      );
+      return protoToActionResult(proto);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async storeAction(actionDigest, result, blobs) {
+    if (!this.#write) {
+      return false;
+    }
+    await this.#assertSha256Supported();
+    try {
+      const missing = await this.#findMissingBlobs(blobs.map((blob) => blob.digest));
+      const missingSet = new Set(missing.map((digest) => digest.hash));
+      const blobsToUpload = blobs.filter((blob) => missingSet.has(blob.digest.hash));
+      await this.#uploadBlobs(blobsToUpload);
+      const { actionCache } = await this.#getClients();
+      const metadata = await this.#buildMetadata();
+      await callUnary(
+        actionCache,
+        "UpdateActionResult",
+        {
+          action_digest: digestToProto(actionDigest),
+          action_result: actionResultToProto(result),
+          instance_name: this.#instanceName
+        },
+        metadata,
+        this.#timeout
+      );
+      return true;
+    } catch (error) {
+      this.#onUploadError?.(actionDigest.hash, error);
+      return false;
+    }
+  }
+  async #getClients() {
+    if (this.#clientsPromise === void 0) {
+      this.#clientsPromise = (async () => {
+        const { clients, grpc } = await loadReapiProto();
+        const credentials = this.#useTls ? grpc.credentials.createSsl() : grpc.credentials.createInsecure();
+        return {
+          actionCache: new clients.ActionCache(this.#target, credentials),
+          byteStream: new clients.ByteStream(this.#target, credentials),
+          capabilities: new clients.Capabilities(this.#target, credentials),
+          cas: new clients.ContentAddressableStorage(this.#target, credentials),
+          clients,
+          grpc
+        };
+      })();
+    }
+    return this.#clientsPromise;
+  }
+  async #buildMetadata() {
+    const { grpc } = await this.#getClients();
+    const metadata = new grpc.Metadata();
+    if (this.#bearerToken !== void 0) {
+      metadata.set("authorization", `Bearer ${this.#bearerToken}`);
+    }
+    return metadata;
+  }
+  async #getMaxBatchSize() {
+    const negotiated = await this.#negotiateCapabilities();
+    return negotiated.maxBatchTotalSizeBytes;
+  }
+  /**
+   * One-shot capability negotiation. Caches the result so the
+   * first {@link RemoteCacheBackend} method to need it pays the
+   * round-trip and every subsequent call sees the cached values.
+   *
+   * Auth failures (`UNAUTHENTICATED` / `PERMISSION_DENIED`) are
+   * re-thrown — falling back silently would let a misconfigured
+   * token survive until the next CAS RPC, where the failure mode is
+   * less obviously "fix your auth". `NOT_FOUND` and benign network
+   * errors degrade to defaults so the backend stays usable against
+   * older REAPI servers that do not implement Capabilities.
+   *
+   * `digest_functions` is recorded so `#assertSha256Supported`
+   * can refuse to talk to a server that only advertises non-sha256
+   * digests — vis pins sha256 for action digests and a server
+   * expecting BLAKE3 would reject every request with
+   * `INVALID_ARGUMENT`.
+   */
+  async #negotiateCapabilities() {
+    if (this.#capabilities !== void 0) {
+      return this.#capabilities;
+    }
+    try {
+      const { capabilities } = await this.#getClients();
+      const metadata = await this.#buildMetadata();
+      const response = await callUnary(
+        capabilities,
+        "GetCapabilities",
+        { instance_name: this.#instanceName },
+        metadata,
+        this.#timeout
+      );
+      const cacheCaps = response?.cache_capabilities;
+      const advertised = cacheCaps && typeof cacheCaps.max_batch_total_size_bytes === "number" ? cacheCaps.max_batch_total_size_bytes : 0;
+      const digestFunctions = (cacheCaps?.digest_functions ?? []).map(String);
+      this.#capabilities = {
+        digestFunctions,
+        maxBatchTotalSizeBytes: advertised > 0 ? advertised : DEFAULT_MAX_BATCH_TOTAL_SIZE_BYTES
+      };
+      return this.#capabilities;
+    } catch (error) {
+      if (isAuthError(error)) {
+        throw error;
+      }
+      this.#capabilities = { digestFunctions: [], maxBatchTotalSizeBytes: DEFAULT_MAX_BATCH_TOTAL_SIZE_BYTES };
+      return this.#capabilities;
+    }
+  }
+  /**
+   * Refuse to issue CAS / ActionCache RPCs against a server whose
+   * advertised digest functions don't include sha256. Skipped when
+   * negotiation found an empty list (older / non-conforming
+   * servers) — there we fall back to "try it and let the server
+   * reject" rather than refusing outright.
+   */
+  async #assertSha256Supported() {
+    const { digestFunctions } = await this.#negotiateCapabilities();
+    if (digestFunctions.length === 0) {
+      return;
+    }
+    const supportsSha256 = digestFunctions.some((name) => name.toUpperCase() === "SHA256");
+    if (!supportsSha256) {
+      throw new Error(
+        `[task-runner] REAPI server does not advertise SHA256 in cache_capabilities.digest_functions (got: ${digestFunctions.join(", ")}). vis pins sha256 for action digests; a server expecting a different digest function would reject every request.`
+      );
+    }
+  }
+  async #findMissingBlobs(digests) {
+    if (digests.length === 0) {
+      return [];
+    }
+    const { cas } = await this.#getClients();
+    const metadata = await this.#buildMetadata();
+    const response = await callUnary(
+      cas,
+      "FindMissingBlobs",
+      {
+        blob_digests: digests.map((digest) => digestToProto(digest)),
+        instance_name: this.#instanceName
+      },
+      metadata,
+      this.#timeout
+    );
+    const missing = response?.missing_blob_digests ?? [];
+    return missing.map((proto) => protoToDigest(proto));
+  }
+  async #uploadBlobs(blobs) {
+    if (blobs.length === 0) {
+      return;
+    }
+    const maxBatchSize = await this.#getMaxBatchSize();
+    const perBlobLimit = maxBatchSize - BATCH_ENTRY_OVERHEAD_BYTES;
+    const small = [];
+    const large = [];
+    for (const blob of blobs) {
+      (blob.digest.sizeBytes <= perBlobLimit ? small : large).push(blob);
+    }
+    const batches = bucketIntoBatches(small, maxBatchSize);
+    for (const batch of batches) {
+      await this.#uploadBatchOnce(batch);
+    }
+    for (const blob of large) {
+      await this.#uploadStreamOnce(blob);
+    }
+  }
+  async #uploadBatchOnce(blobs) {
+    const dedupedBlobs = [];
+    const dedupedPromises = [];
+    for (const blob of blobs) {
+      const inflight = this.#inflightUploads.get(blob.digest.hash);
+      if (inflight !== void 0) {
+        dedupedPromises.push(inflight);
+        continue;
+      }
+      dedupedBlobs.push(blob);
+    }
+    if (dedupedBlobs.length > 0) {
+      const promise = this.#uploadBatchToWire(dedupedBlobs);
+      for (const blob of dedupedBlobs) {
+        this.#inflightUploads.set(blob.digest.hash, promise);
+      }
+      try {
+        await promise;
+      } finally {
+        for (const blob of dedupedBlobs) {
+          this.#inflightUploads.delete(blob.digest.hash);
+        }
+      }
+    }
+    await Promise.all(dedupedPromises);
+  }
+  async #uploadBatchToWire(blobs) {
+    const requests = [];
+    for (const blob of blobs) {
+      const data = await streamToBuffer(await blob.open());
+      requests.push({
+        compressor: COMPRESSOR_IDENTITY,
+        data,
+        digest: digestToProto(blob.digest)
+      });
+    }
+    const { cas } = await this.#getClients();
+    const metadata = await this.#buildMetadata();
+    const response = await callUnary(
+      cas,
+      "BatchUpdateBlobs",
+      {
+        instance_name: this.#instanceName,
+        requests
+      },
+      metadata,
+      this.#timeout
+    );
+    const responses = response?.responses ?? [];
+    for (const entry of responses) {
+      const code = entry.status.code ?? 0;
+      if (code !== STATUS_OK) {
+        throw new Error(`[task-runner] BatchUpdateBlobs reported code ${String(code)} for ${entry.digest.hash}: ${entry.status.message ?? ""}`);
+      }
+    }
+    return true;
+  }
+  async #uploadStreamOnce(blob) {
+    const inflight = this.#inflightUploads.get(blob.digest.hash);
+    if (inflight !== void 0) {
+      await inflight;
+      return;
+    }
+    const promise = this.#streamWrite(blob);
+    this.#inflightUploads.set(blob.digest.hash, promise);
+    try {
+      await promise;
+    } finally {
+      this.#inflightUploads.delete(blob.digest.hash);
+    }
+  }
+  async #streamWrite(blob) {
+    const { byteStream } = await this.#getClients();
+    const metadata = await this.#buildMetadata();
+    const resourceName = buildWriteResourceName(this.#instanceName, blob.digest);
+    const writeFn = byteStream.Write;
+    if (typeof writeFn !== "function") {
+      throw new TypeError("[task-runner] REAPI ByteStream client is missing Write method.");
+    }
+    await new Promise((resolve, reject) => {
+      const callOptions = { deadline: Date.now() + this.#timeout * STREAM_DEADLINE_MULTIPLIER };
+      const call = writeFn.call(byteStream, metadata, callOptions, (error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      void (async () => {
+        try {
+          let writeOffset = 0;
+          let firstChunk = true;
+          const stream = await blob.open();
+          for await (const rawChunk of stream) {
+            const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+            for (let pos = 0; pos < chunk.byteLength; pos += STREAM_CHUNK_SIZE) {
+              const slice = chunk.subarray(pos, pos + STREAM_CHUNK_SIZE);
+              call.write({
+                data: slice,
+                finish_write: false,
+                resource_name: firstChunk ? resourceName : "",
+                write_offset: writeOffset
+              });
+              writeOffset += slice.byteLength;
+              firstChunk = false;
+            }
+          }
+          call.write({
+            data: Buffer.alloc(0),
+            finish_write: true,
+            resource_name: firstChunk ? resourceName : "",
+            write_offset: writeOffset
+          });
+          call.end();
+        } catch (error) {
+          try {
+            call.cancel?.();
+          } catch {
+          }
+          reject(error);
+        }
+      })();
+    });
+    return true;
+  }
+  async #batchReadOne(digest) {
+    const { cas } = await this.#getClients();
+    const metadata = await this.#buildMetadata();
+    const response = await callUnary(
+      cas,
+      "BatchReadBlobs",
+      {
+        acceptable_compressors: [COMPRESSOR_IDENTITY],
+        digests: [digestToProto(digest)],
+        instance_name: this.#instanceName
+      },
+      metadata,
+      this.#timeout
+    );
+    const entry = response?.responses?.[0];
+    if (!entry) {
+      return void 0;
+    }
+    const code = entry.status.code ?? 0;
+    if (code !== STATUS_OK) {
+      return void 0;
+    }
+    if (entry.data === void 0) {
+      return Buffer.alloc(0);
+    }
+    return Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data);
+  }
+  async #streamRead(digest, destinationPath) {
+    const { byteStream } = await this.#getClients();
+    const metadata = await this.#buildMetadata();
+    const resourceName = buildReadResourceName(this.#instanceName, digest);
+    const readFn = byteStream.Read;
+    if (typeof readFn !== "function") {
+      throw new TypeError("[task-runner] REAPI ByteStream client is missing Read method.");
+    }
+    const callOptions = { deadline: Date.now() + this.#timeout * STREAM_DEADLINE_MULTIPLIER };
+    const call = readFn.call(
+      byteStream,
+      { read_limit: 0, read_offset: 0, resource_name: resourceName },
+      metadata,
+      callOptions
+    );
+    const writer = createWriteStream(destinationPath);
+    try {
+      for await (const message of call) {
+        const { data } = message;
+        if (data === void 0) {
+          continue;
+        }
+        if (!writer.write(Buffer.isBuffer(data) ? data : Buffer.from(data))) {
+          await new Promise((resolve) => {
+            writer.once("drain", () => {
+              resolve();
+            });
+          });
+        }
+      }
+      await new Promise((resolve, reject) => {
+        writer.end((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+      return true;
+    } catch (error) {
+      writer.destroy();
+      if (isNotFoundError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+}
+const digestToProto = (digest) => {
+  return {
+    hash: digest.hash,
+    size_bytes: digest.sizeBytes
+  };
+};
+const protoToDigest = (proto) => {
+  return {
+    hash: proto?.hash ?? "",
+    sizeBytes: typeof proto?.size_bytes === "number" ? proto.size_bytes : 0
+  };
+};
+const protoToActionResult = (proto) => {
+  return {
+    exitCode: proto?.exit_code ?? 0,
+    outputDirectories: (proto?.output_directories ?? []).map((entry) => {
+      return {
+        path: entry.path,
+        treeDigest: protoToDigest(entry.tree_digest)
+      };
+    }),
+    outputFiles: (proto?.output_files ?? []).map((entry) => {
+      return {
+        digest: protoToDigest(entry.digest),
+        isExecutable: entry.is_executable ?? false,
+        path: entry.path
+      };
+    }),
+    stdoutDigest: proto?.stdout_digest === void 0 ? void 0 : protoToDigest(proto.stdout_digest)
+  };
+};
+const actionResultToProto = (result) => {
+  return {
+    exit_code: result.exitCode,
+    output_directories: result.outputDirectories.map((entry) => {
+      return {
+        path: entry.path,
+        tree_digest: digestToProto(entry.treeDigest)
+      };
+    }),
+    output_files: result.outputFiles.map((entry) => {
+      return {
+        digest: digestToProto(entry.digest),
+        is_executable: entry.isExecutable,
+        path: entry.path
+      };
+    }),
+    stdout_digest: result.stdoutDigest === void 0 ? void 0 : digestToProto(result.stdoutDigest)
+  };
+};
+const isNotFoundError = (error) => {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const { code } = error;
+  return code === STATUS_NOT_FOUND;
+};
+const isAuthError = (error) => {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const { code } = error;
+  return code === STATUS_UNAUTHENTICATED || code === STATUS_PERMISSION_DENIED;
+};
+const parseGrpcUrl = (url) => {
+  const trimmed = url.trim();
+  if (trimmed === "") {
+    throw new Error("[task-runner] REAPI backend requires a non-empty `url`.");
+  }
+  const match = /^(grpcs?):\/\/(.+)$/i.exec(trimmed);
+  if (match === null) {
+    return { target: trimmed, useTls: false };
+  }
+  const [, scheme, target] = match;
+  const finalTarget = (target ?? "").trim();
+  if (finalTarget === "") {
+    throw new Error(`[task-runner] REAPI backend url ${url} is missing a host:port target.`);
+  }
+  return { target: finalTarget, useTls: scheme?.toLowerCase() === "grpcs" };
+};
+const bucketIntoBatches = (blobs, maxBatchSize) => {
+  const batches = [];
+  let current = [];
+  let currentSize = 0;
+  for (const blob of blobs) {
+    const entrySize = blob.digest.sizeBytes + BATCH_ENTRY_OVERHEAD_BYTES;
+    if (currentSize + entrySize > maxBatchSize && current.length > 0) {
+      batches.push(current);
+      current = [];
+      currentSize = 0;
+    }
+    current.push(blob);
+    currentSize += entrySize;
+  }
+  if (current.length > 0) {
+    batches.push(current);
+  }
+  return batches;
+};
+const streamToBuffer = async (source) => {
+  const chunks = [];
+  for await (const chunk of source) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+};
+
+export { ReapiRemoteCache };