@browserbridge/bbx 1.8.0 → 1.10.0

package/packages/agent-client/src/cli.js

@@ -4,11 +4,19 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
-import { createRuntimeContext, METHODS } from '../../protocol/src/index.js';
+import {
+  createRuntimeContext,
+  describeBridgeMethods,
+  isBridgeMethod,
+  isHarDocument,
+  METHODS,
+} from '../../protocol/src/index.js';
 import {
   restartRegisteredMcpProcesses,
   tryStartMcpProcessControl,
@@ -16,6 +24,8 @@ import {
 import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
 import {
   extractRemoteFlag,
+  extractHarFlags,
+  extractPresetFlag,
   extractScreenshotFlags,
   extractTabFlag,
   parseCallCommand,
@@ -23,7 +33,7 @@ import {
   readStdin,
 } from './cli-args.js';
 import { runBatchCalls } from './cli-batch.js';
-import { parseIntArg } from './cli-helpers.js';
+import { isElementRef, parseIntArg } from './cli-helpers.js';
 import { printCallResponse, printJson, printSummary, printUsage } from './cli-output.js';
 import { handleProxyCommand, handleRemoteCommand } from './cli-proxy-remote.js';
 import {
@@ -32,12 +42,16 @@ import {
   uninstallBrowserBridge,
 } from './cli-setup-commands.js';
 import { SHORTCUT_COMMANDS } from './command-registry.js';
+import { getAutoUpdatePolicy, parseAutoUpdatePolicy, setAutoUpdatePolicy } from './config.js';
 import { formatMcpConfig, isMcpClientName, MCP_CLIENT_NAMES } from './mcp-config.js';
 import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
 import { createBridgeClientForDestination } from './remotes.js';
+import { atomicWriteFile } from './atomic-write.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
+/** @typedef {import('../../protocol/src/types.js').ArtifactDescriptor} ArtifactDescriptor */
+/** @typedef {import('../../protocol/src/types.js').HarExportResult} HarExportResult */
 
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
@@ -57,6 +71,7 @@ const LOCAL_ONLY_COMMANDS = new Set([
   '--version',
   '-v',
   'skill',
+  'protocol',
   'install',
   'uninstall',
   'install-skill',
@@ -64,6 +79,7 @@ const LOCAL_ONLY_COMMANDS = new Set([
   'mcp',
   'proxy',
   'remote',
+  'config',
   'doctor',
   'restart',
 ]);
@@ -103,6 +119,22 @@ if (command === 'skill') {
   process.exit(0);
 }
 
+if (command === 'protocol') {
+  const [subcommand, target, ...extra] = rest;
+  if (subcommand !== 'describe' || extra.length > 0) {
+    process.stderr.write('Usage: bbx protocol describe [method|group]\n');
+    process.exit(1);
+  }
+  await runLocalCommand(async () => {
+    printJson(
+      target
+        ? describeBridgeMethods(isBridgeMethod(target) ? { method: target } : { group: target })
+        : describeBridgeMethods()
+    );
+  });
+  process.exit();
+}
+
 if (command === 'install') {
   const { execFileSync } = await import('node:child_process');
   const installScript = path.resolve(
@@ -134,7 +166,7 @@ if (command === 'install-mcp') {
 }
 
 if (command === 'mcp') {
-  const [subcommand, clientName] = rest;
+  const [subcommand, clientName, ...extra] = rest;
   if (subcommand === 'serve') {
     const control = await tryStartMcpProcessControl();
     try {
@@ -146,7 +178,7 @@ if (command === 'mcp') {
     await new Promise(() => {});
   }
   if (subcommand === 'config') {
-    if (!clientName || !isMcpClientName(clientName)) {
+    if (!clientName || !isMcpClientName(clientName) || extra.length > 0) {
       process.stderr.write(`Usage: bbx mcp config <${MCP_CLIENT_NAMES.join('|')}>\n`);
       process.exit(1);
     }
@@ -167,6 +199,11 @@ if (command === 'remote') {
   process.exit();
 }
 
+if (command === 'config') {
+  await runLocalCommand(() => handleConfigCommand(rest));
+  process.exit();
+}
+
 const clientTimeoutMs = getClientTimeoutOverride();
 applyWindowsTcpTransportDefaults();
 const client = await createCliClient();
@@ -189,6 +226,26 @@ async function runLocalCommand(run) {
   }
 }
 
+/**
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+async function handleConfigCommand(args) {
+  const [action, key, value] = args;
+  if (action === 'get' && key === 'auto-update' && value === undefined) {
+    process.stdout.write(`${await getAutoUpdatePolicy()}\n`);
+    return;
+  }
+  if (action === 'set' && key === 'auto-update' && value !== undefined && args.length === 3) {
+    const policy = parseAutoUpdatePolicy(value);
+    const configPath = await setAutoUpdatePolicy(policy);
+    process.stdout.write(`Browser Bridge auto-update policy set to "${policy}".\n`);
+    process.stdout.write(`Config: ${configPath}\n`);
+    return;
+  }
+  throw new Error('Usage: bbx config <get auto-update|set auto-update off|compatible>');
+}
+
 /**
  * Create the bridge client for this invocation, honoring the --remote flag
  * and BBX_REMOTE env var. Exits with a friendly error when the destination
@@ -213,6 +270,7 @@ async function createCliClient() {
 }
 
 async function main() {
+  let relaunchAfterUpdate = false;
   try {
     if (command === 'status') {
       const healthResponse = await requestBridge(
@@ -226,8 +284,10 @@ async function main() {
     }
 
     if (command === 'access-request') {
+      if (rest.length > 1) throw new Error('Usage: bbx access-request [intent]');
+      const params = SHORTCUT_COMMANDS['access-request'].build(rest);
       await printSummary(
-        await requestBridge(client, 'access.request', {}, { source: REQUEST_SOURCE })
+        await requestBridge(client, 'access.request', params, { source: REQUEST_SOURCE })
       );
       return;
     }
@@ -338,12 +398,13 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printCallResponse(response);
+      printCallResponse(response, method);
       return;
     }
 
     if (command === 'batch') {
-      const results = await runBatchCalls(client, rest[0], REQUEST_SOURCE);
+      const { preset, rest: batchArgs } = extractPresetFlag(rest);
+      const results = await runBatchCalls(client, batchArgs[0], REQUEST_SOURCE, { preset });
       if (results.some((result) => !result.ok)) {
         process.exitCode = 1;
       }
@@ -357,7 +418,7 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printCallResponse(response);
+      printCallResponse(response, method);
       return;
     }
 
@@ -378,7 +439,7 @@ async function main() {
       const [key, refOrSelector] = rest;
       if (!key) throw new Error('Usage: press-key <key> [ref|selector]');
       const target = refOrSelector
-        ? refOrSelector.startsWith('el_')
+        ? isElementRef(refOrSelector)
           ? { elementRef: refOrSelector }
           : { selector: refOrSelector }
         : undefined;
@@ -431,6 +492,7 @@ async function main() {
           elementRef,
           format: screenshotOptions.format,
           quality: screenshotOptions.quality,
+          delivery: 'artifact',
         },
         { tabId: parsed.tabId, source: REQUEST_SOURCE }
       );
@@ -453,8 +515,11 @@ async function main() {
       ) {
         throw new Error(`Screenshot path extension must match ${screenshotOptions.format} format.`);
       }
-      const data = screenshotResult.image.replace(/^data:image\/(?:png|jpeg|webp);base64,/, '');
-      await fs.promises.writeFile(filePath, Buffer.from(data, 'base64'));
+      const imageBytes =
+        screenshotResult.delivery === 'artifact'
+          ? await downloadArtifact(client, screenshotResult.artifact, 'screenshot')
+          : decodeScreenshotDataUrl(screenshotResult.image);
+      await atomicWriteFile(filePath, imageBytes);
       printJson({
         ok: true,
         summary: `Screenshot saved to ${filePath}.`,
@@ -469,6 +534,50 @@ async function main() {
       return;
     }
 
+    if (command === 'har') {
+      const parsed = extractTabFlag(rest);
+      const harOptions = extractHarFlags(parsed.rest);
+      const [outputPath = 'browser-bridge.har', ...extra] = harOptions.rest;
+      if (extra.length > 0) {
+        throw new Error(
+          'Usage: har [--tab <tabId>] [--limit 1-200] [--url-pattern <pattern>] [--delivery inline|artifact|auto] [outPath]'
+        );
+      }
+      if (path.extname(outputPath) !== '.har') {
+        throw new Error('HAR output path must use the .har extension.');
+      }
+      const response = await requestBridge(
+        client,
+        'network.export_har',
+        {
+          limit: harOptions.limit,
+          urlPattern: harOptions.urlPattern,
+          delivery: harOptions.delivery,
+        },
+        { tabId: parsed.tabId, source: REQUEST_SOURCE }
+      );
+      if (!response.ok) {
+        await printSummary(response);
+        return;
+      }
+      const result = /** @type {HarExportResult} */ (response.result);
+      let harBytes;
+      if (result.delivery === 'artifact') {
+        harBytes = await downloadArtifact(client, result.artifact, 'har');
+        assertValidHarBytes(harBytes);
+      } else {
+        assertValidHarDocument(result.har);
+        harBytes = Buffer.from(`${JSON.stringify(result.har, null, 2)}\n`, 'utf8');
+      }
+      await atomicWriteFile(outputPath, harBytes);
+      printJson({
+        ok: true,
+        summary: `HAR saved to ${outputPath}.`,
+        evidence: { savedTo: outputPath, delivery: result.delivery },
+      });
+      return;
+    }
+
     if (command === 'intercept') {
       const { tabId, rest: iArgs } = extractTabFlag(rest);
       const sub = iArgs[0];
@@ -559,25 +668,144 @@ async function main() {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const raw = getErrorCode(error);
-    let code = 'ERROR';
-    if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
-      code = 'DAEMON_OFFLINE';
-    } else if (raw === 'BRIDGE_TIMEOUT') {
-      code = 'BRIDGE_TIMEOUT';
-    } else if (/socket closed/i.test(message)) {
-      code = 'CONNECTION_LOST';
-    } else if (raw) {
-      code = String(raw);
+    if (raw === 'BBX_NPM_UPDATED') {
+      relaunchAfterUpdate = true;
+    } else {
+      let code = 'ERROR';
+      if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
+        code = 'DAEMON_OFFLINE';
+      } else if (raw === 'BRIDGE_TIMEOUT') {
+        code = 'BRIDGE_TIMEOUT';
+      } else if (/socket closed/i.test(message)) {
+        code = 'CONNECTION_LOST';
+      } else if (raw) {
+        code = String(raw);
+      }
+      printJson({
+        ok: false,
+        summary: `${code}: ${message}`,
+        evidence: null,
+      });
+      process.exitCode = 1;
     }
-    printJson({
-      ok: false,
-      summary: `${code}: ${message}`,
-      evidence: null,
-    });
-    process.exitCode = 1;
   } finally {
     await client.close();
   }
+  if (relaunchAfterUpdate) {
+    relaunchCli();
+  }
+}
+
+/** @param {string} value */
+function decodeScreenshotDataUrl(value) {
+  const match = /^data:image\/(?:png|jpeg|webp);base64,([A-Za-z0-9+/]*={0,2})$/u.exec(value);
+  if (!match) throw new Error('Screenshot response contains invalid base64 image data.');
+  const bytes = Buffer.from(match[1], 'base64');
+  if (bytes.toString('base64') !== match[1]) {
+    throw new Error('Screenshot response contains non-canonical base64 image data.');
+  }
+  return bytes;
+}
+
+/**
+ * @param {import('./client.js').BridgeClient} client
+ * @param {ArtifactDescriptor} artifact
+ * @param {'screenshot' | 'har'} [expectedKind]
+ */
+async function downloadArtifact(client, artifact, expectedKind) {
+  const chunks = [];
+  let offset = 0;
+  try {
+    if (expectedKind && artifact.kind !== expectedKind) {
+      throw new Error(`Artifact kind does not match the expected ${expectedKind} result.`);
+    }
+    if (expectedKind === 'har' && artifact.mimeType !== 'application/json') {
+      throw new Error('HAR artifact MIME type is invalid.');
+    }
+    while (offset < artifact.byteLength) {
+      const response = await requestBridge(
+        client,
+        'artifact.read',
+        { artifactId: artifact.artifactId, offset },
+        { source: REQUEST_SOURCE }
+      );
+      if (!response.ok) throw new Error(response.error.message);
+      const result = /** @type {Record<string, unknown>} */ (response.result);
+      if (result.artifactId !== artifact.artifactId || result.offset !== offset) {
+        throw new Error('Artifact chunk metadata is inconsistent.');
+      }
+      const data = String(result.data ?? '');
+      const bytes = Buffer.from(data, 'base64');
+      if (bytes.toString('base64') !== data || bytes.length !== result.byteLength) {
+        throw new Error('Artifact chunk contains invalid base64 data.');
+      }
+      chunks.push(bytes);
+      if (result.nextOffset === null) break;
+      if (typeof result.nextOffset !== 'number' || result.nextOffset <= offset) {
+        throw new Error('Artifact chunk did not advance the read offset.');
+      }
+      offset = result.nextOffset;
+    }
+    const output = Buffer.concat(chunks);
+    const sha256 = createHash('sha256').update(output).digest('hex');
+    if (output.length !== artifact.byteLength || sha256 !== artifact.sha256) {
+      throw new Error('Artifact length or checksum does not match the capture metadata.');
+    }
+    return output;
+  } finally {
+    await requestBridge(
+      client,
+      'artifact.delete',
+      { artifactId: artifact.artifactId },
+      { source: REQUEST_SOURCE }
+    ).catch(() => {});
+  }
+}
+
+/** @param {Buffer} bytes */
+function assertValidHarBytes(bytes) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(bytes)) {
+    throw new Error('HAR artifact is not valid UTF-8 JSON.');
+  }
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    throw new Error('HAR artifact is not valid JSON.');
+  }
+  assertValidHarDocument(document);
+}
+
+/** @param {unknown} document */
+function assertValidHarDocument(document) {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error('HAR response does not contain an inline HAR object.');
+  }
+  if (!isHarDocument(document)) {
+    throw new Error('HAR response does not contain a valid HAR 1.2 document.');
+  }
+}
+
+/**
+ * Replace this invocation with a fresh Node process after npm has replaced the
+ * package on disk. Child stdio is inherited so command output remains stable.
+ *
+ * @returns {void}
+ */
+function relaunchCli() {
+  const result = spawnSync(
+    process.execPath,
+    [fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+    {
+      stdio: 'inherit',
+      env: process.env,
+    }
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  process.exitCode = result.status ?? 1;
 }
 
 /**

package/packages/agent-client/src/client.js

@@ -12,6 +12,10 @@ import {
   DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
   ERROR_CODES,
   getProtocolVersion,
+  isBatchSafeBridgeCall,
+  isBridgeMethod,
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   parseJsonLines,
   setProtocolPackageVersion,
 } from '../../protocol/src/index.js';
@@ -23,6 +27,12 @@ import {
 } from '../../native-host/src/config.js';
 import { normalizeBridgeAuthToken, readBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+import {
+  comparePackageVersions,
+  NpmPackageUpdatedError,
+  parseStableVersion,
+  updateCompatibleNpmPackage,
+} from './npm-self-update.js';
 
 /** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
@@ -32,7 +42,8 @@ import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 /** @typedef {import('./types.js').PendingRequest} PendingRequest */
 /** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
-setProtocolPackageVersion(loadPackageVersion());
+const CLIENT_PACKAGE_VERSION = loadPackageVersion();
+setProtocolPackageVersion(CLIENT_PACKAGE_VERSION);
 
 /**
  * @returns {string | null}
@@ -119,6 +130,9 @@ export class BridgeClient extends EventEmitter {
     checkProtocolOnConnect = true,
     restartDaemonOnVersionMismatch = shouldAutoRestartDaemonOnVersionMismatch(),
     restartDaemonFn = restartBridgeDaemon,
+    updateNpmOnCompatibleVersion = false,
+    exitProcessOnNpmUpdate = false,
+    updateCompatibleNpmPackageFn = updateCompatibleNpmPackage,
     authToken = undefined,
   } = {}) {
     super();
@@ -131,6 +145,9 @@ export class BridgeClient extends EventEmitter {
     this.checkProtocolOnConnect = checkProtocolOnConnect;
     this.restartDaemonOnVersionMismatch = restartDaemonOnVersionMismatch;
     this.restartDaemonFn = restartDaemonFn;
+    this.updateNpmOnCompatibleVersion = updateNpmOnCompatibleVersion;
+    this.exitProcessOnNpmUpdate = exitProcessOnNpmUpdate;
+    this.updateCompatibleNpmPackageFn = updateCompatibleNpmPackageFn;
     this.authToken = authToken;
     this.socket = null;
     this.connected = false;
@@ -140,6 +157,9 @@ export class BridgeClient extends EventEmitter {
     this.waiting = new Map();
     this._reconnecting = false;
     this._attemptedVersionMismatchRestart = false;
+    this._attemptedNpmUpdate = false;
+    /** @type {import('./types.js').NpmUpdateResult | null} */
+    this.npmUpdateResult = null;
   }
 
   /**
@@ -280,6 +300,9 @@ export class BridgeClient extends EventEmitter {
     if (this.protocolCompatibility.compatible) {
       this._attemptedVersionMismatchRestart = false;
     }
+    if (await this.tryCompatibleNpmUpdate(healthResult)) {
+      return;
+    }
     if (this.shouldRestartDaemonForProtocolMismatch(healthResult)) {
       this._attemptedVersionMismatchRestart = true;
       await this.disconnectForDaemonRestart();
@@ -288,6 +311,95 @@ export class BridgeClient extends EventEmitter {
     }
   }
 
+  /**
+   * @param {ProtocolHealthResult} healthResult
+   * @returns {Promise<boolean>}
+   */
+  async tryCompatibleNpmUpdate(healthResult) {
+    const extensionVersion = healthResult.extensionVersion;
+    const processVersion = CLIENT_PACKAGE_VERSION;
+    const extensionVersions = Array.isArray(healthResult.extension_supported_versions)
+      ? healthResult.extension_supported_versions
+      : healthResult.extensionConnected === true && Array.isArray(healthResult.supported_versions)
+        ? healthResult.supported_versions
+        : [];
+    if (
+      !this.updateNpmOnCompatibleVersion ||
+      this._attemptedNpmUpdate ||
+      healthResult.extensionConnected !== true ||
+      typeof extensionVersion !== 'string' ||
+      !parseStableVersion(extensionVersion) ||
+      typeof processVersion !== 'string' ||
+      !parseStableVersion(processVersion) ||
+      comparePackageVersions(extensionVersion, processVersion) <= 0 ||
+      extensionVersions.length === 0
+    ) {
+      return false;
+    }
+
+    this._attemptedNpmUpdate = true;
+    const previousAutoReconnect = this.autoReconnect;
+    this.autoReconnect = false;
+    try {
+      this.npmUpdateResult = await this.updateCompatibleNpmPackageFn({
+        extensionVersion,
+        supportedVersions: extensionVersions,
+      });
+      if (!this.npmUpdateResult.updated) {
+        if (
+          typeof this.npmUpdateResult.previousVersion === 'string' &&
+          parseStableVersion(this.npmUpdateResult.previousVersion) &&
+          comparePackageVersions(this.npmUpdateResult.previousVersion, processVersion) > 0
+        ) {
+          this.requireFreshProcess(this.npmUpdateResult.previousVersion);
+        }
+        if (this.npmUpdateResult.reason === 'not_global_install') {
+          this.setProtocolWarning(
+            'Automatic npm update skipped because this Browser Bridge client is not running from the global npm installation.'
+          );
+        }
+        return false;
+      }
+
+      this.requireFreshProcess(this.npmUpdateResult.version || extensionVersion);
+    } catch (error) {
+      if (error instanceof NpmPackageUpdatedError || this.npmUpdateResult?.updated) {
+        throw error;
+      }
+      this.setProtocolWarning(
+        `Automatic Browser Bridge npm update failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return false;
+    } finally {
+      this.autoReconnect = previousAutoReconnect;
+    }
+  }
+
+  /**
+   * @param {string} version
+   * @returns {never}
+   */
+  requireFreshProcess(version) {
+    if (this.exitProcessOnNpmUpdate) {
+      setTimeout(() => process.exit(0), 250).unref();
+    }
+    throw new NpmPackageUpdatedError(version);
+  }
+
+  /**
+   * @param {string} warning
+   * @returns {void}
+   */
+  setProtocolWarning(warning) {
+    this.protocolWarning = this.protocolWarning ? `${this.protocolWarning} ${warning}` : warning;
+    if (this.protocolCompatibility) {
+      this.protocolCompatibility = {
+        ...this.protocolCompatibility,
+        warning: this.protocolWarning,
+      };
+    }
+  }
+
   /**
    * @param {{
    *   method: BridgeMethod,
@@ -456,7 +568,7 @@ export class BridgeClient extends EventEmitter {
   }
 
   /**
-   * Send multiple bridge requests without waiting for each response serially.
+   * Send up to 20 read-only bridge requests with bounded concurrency.
    *
    * @param {Array<{
    *   method: BridgeMethod,
@@ -471,8 +583,27 @@ export class BridgeClient extends EventEmitter {
     if (!Array.isArray(calls)) {
       throw new TypeError('BridgeClient.batch expects an array of request objects.');
     }
+    if (calls.length === 0 || calls.length > MAX_BATCH_CALLS) {
+      throw new RangeError(
+        `BridgeClient.batch expects between 1 and ${MAX_BATCH_CALLS} request objects.`
+      );
+    }
+    for (const [index, call] of calls.entries()) {
+      if (!call || typeof call !== 'object' || !isBridgeMethod(call.method)) {
+        throw new TypeError(`BridgeClient.batch calls[${index}] needs a known bridge method.`);
+      }
+      const params = call.params ?? {};
+      if (!params || typeof params !== 'object' || Array.isArray(params)) {
+        throw new TypeError(`BridgeClient.batch calls[${index}].params must be an object.`);
+      }
+      if (!isBatchSafeBridgeCall(call.method, params)) {
+        throw new TypeError(
+          `${call.method} is not safe for BridgeClient.batch. Call it sequentially.`
+        );
+      }
+    }
 
-    return Promise.all(calls.map((call) => this.request(call)));
+    return mapWithConcurrency(calls, MAX_BATCH_CONCURRENCY, (call) => this.request(call));
   }
 
   /**
@@ -642,6 +773,28 @@ export class BridgeClient extends EventEmitter {
   }
 }
 
+/**
+ * @template T, R
+ * @param {T[]} values
+ * @param {number} concurrency
+ * @param {(value: T) => Promise<R>} callback
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(values, concurrency, callback) {
+  /** @type {R[]} */
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await callback(values[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
 /**
  * @param {unknown} result
  * @returns {{ html: string, truncated: boolean, omitted: number }}