@cursor/bdk 0.2.1

package/src/internal/as-of.ts

@@ -0,0 +1,257 @@
+const TIMEZONE_SUFFIX = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+
+export class InvalidAsOfError extends Error {
+  constructor(value: string) {
+    super(
+      `asOf must be an ISO-8601 instant with a timezone (e.g. ` +
+        `2026-08-31T12:00:00Z); received ${JSON.stringify(value)}.`,
+    );
+    this.name = "InvalidAsOfError";
+  }
+}
+
+function parseInstant(value: string): Date | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "" || !TIMEZONE_SUFFIX.test(trimmed)) {
+    return undefined;
+  }
+  const instant = new Date(trimmed);
+  return Number.isNaN(instant.getTime()) ? undefined : instant;
+}
+
+export function normalizeAsOf(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const instant = parseInstant(value);
+  if (instant === undefined) {
+    throw new InvalidAsOfError(value);
+  }
+  return instant.toISOString();
+}
+
+export function sessionClock(asOf: string | undefined): () => Date {
+  if (asOf === undefined) {
+    return () => new Date();
+  }
+  const frozen = new Date(asOf).getTime();
+  return () => new Date(frozen);
+}
+
+export class VacuousTimeArgsError extends Error {
+  constructor(toolName: string, missing: readonly string[]) {
+    super(
+      `Tool "${toolName}" declares timeArgs ` +
+        `${JSON.stringify(missing)} that its input schema does not define, ` +
+        `so bounding would silently check nothing. Make the declaration ` +
+        `match the schema's property names.`,
+    );
+    this.name = "VacuousTimeArgsError";
+  }
+}
+
+export function assertTimeArgs(
+  tools: readonly {
+    name: string;
+    definition: { timeArgs?: readonly string[] };
+    inputSchema?: { properties?: Record<string, unknown> };
+  }[],
+  asOf: string | undefined,
+): void {
+  if (asOf === undefined) {
+    return;
+  }
+  for (const tool of tools) {
+    const declared = tool.definition.timeArgs;
+    if (declared === undefined || declared.length === 0) {
+      continue;
+    }
+    const properties = tool.inputSchema?.properties ?? {};
+    const missing = declared.filter(name => !(name in properties));
+    if (missing.length > 0) {
+      throw new VacuousTimeArgsError(tool.name, missing);
+    }
+  }
+}
+
+export function timeArgViolation(
+  input: unknown,
+  timeArgs: readonly string[],
+  asOf: string,
+): string | undefined {
+  const record =
+    typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+  const frozen = new Date(asOf).getTime();
+  for (const name of timeArgs) {
+    const value = record[name];
+    const instant = typeof value === "string" ? parseInstant(value) : undefined;
+    if (instant === undefined) {
+      return (
+        `Time argument "${name}" must be an absolute ISO-8601 instant with ` +
+        `a timezone (e.g. ${asOf}); received ${JSON.stringify(value)}. This ` +
+        `session reads the world as of ${asOf} — supply absolute bounds at ` +
+        `or before that instant and retry.`
+      );
+    }
+    if (instant.getTime() > frozen) {
+      return (
+        `Time argument "${name}" (${JSON.stringify(value)}) is later than ` +
+        `the instant this session reads the world as of (${asOf}). Supply ` +
+        `bounds at or before that instant and retry.`
+      );
+    }
+  }
+  return undefined;
+}
+
+// Whole-string only: a query that merely contains "now" is not a bound.
+// Duration-only strings (`30m`, `2h`) and last/this plus a non-window word
+// (`last modified`) are not time bounds. Calendar-aligned `now/d` is.
+const TIME_UNIT =
+  "(?:s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks|mo|month|months|y|yr|yrs|year|years)";
+const WINDOW_WORD =
+  "(?:second|seconds|minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years|quarter|quarters|weekend|monday|tuesday|wednesday|thursday|friday|saturday|sunday|morning|afternoon|evening|night)";
+const RELATIVE_TIME_EXPRESSION = new RegExp(
+  `^(?:now(?:\\s*[+-]\\s*\\d+\\s*${TIME_UNIT}\\b.*|/[a-zA-Z]+.*)?|[+-]\\d+\\s*${TIME_UNIT}|today|yesterday|tomorrow|(?:last|this)\\s+${WINDOW_WORD})$`,
+  "i",
+);
+
+function forwardTimeReason(value: unknown, asOf: string, frozenMs: number): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  if (RELATIVE_TIME_EXPRESSION.test(trimmed)) {
+    return (
+      `Argument ${JSON.stringify(value)} is a relative time expression, ` +
+      `which reads against the real present. This session reads the world ` +
+      `as of ${asOf}; supply an absolute ISO-8601 instant with a timezone ` +
+      `at or before that instant and retry.`
+    );
+  }
+  const instant = parseInstant(trimmed);
+  if (instant !== undefined && instant.getTime() > frozenMs) {
+    return (
+      `Argument ${JSON.stringify(value)} is later than the instant this ` +
+      `session reads the world as of (${asOf}). Supply a bound at or before ` +
+      `that instant and retry.`
+    );
+  }
+  return undefined;
+}
+
+/** Relative expressions or instants after `asOf`. Numeric epochs need `timeArgs`. */
+export function forwardTimeArgument(input: unknown, asOf: string): string | undefined {
+  const frozenMs = new Date(asOf).getTime();
+  const seen = new Set<unknown>();
+  const walk = (value: unknown, depth: number): string | undefined => {
+    if (depth > 8) {
+      return undefined;
+    }
+    const reason = forwardTimeReason(value, asOf, frozenMs);
+    if (reason !== undefined) {
+      return reason;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const found = walk(item, depth + 1);
+        if (found !== undefined) {
+          return found;
+        }
+      }
+      return undefined;
+    }
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return undefined;
+      }
+      seen.add(value);
+      for (const item of Object.values(value as Record<string, unknown>)) {
+        const found = walk(item, depth + 1);
+        if (found !== undefined) {
+          return found;
+        }
+      }
+    }
+    return undefined;
+  };
+  return walk(input, 0);
+}
+
+/**
+ * Property names that carry a query's time window when a vendor schema
+ * declares them. Deliberately narrower than the embedded-filter key list:
+ * these must be safe to *require*, so only unambiguous window names — never
+ * `timestamp`/`date`, which name data fields more often than bounds.
+ */
+const TIME_WINDOW_KEYS = new Set([
+  "from",
+  "to",
+  "since",
+  "until",
+  "start",
+  "end",
+  "start_time",
+  "end_time",
+  "starttime",
+  "endtime",
+]);
+
+/**
+ * The string-typed time-window properties a tool's input schema declares.
+ * String-typed only: a numeric `from` is a pagination offset more often than
+ * an instant, and requiring an ISO value there would break the call.
+ */
+export function schemaTimeWindowKeys(
+  inputSchema: { properties?: Record<string, unknown> } | undefined,
+): string[] {
+  const properties = inputSchema?.properties;
+  if (properties === undefined) {
+    return [];
+  }
+  const keys: string[] = [];
+  for (const [name, spec] of Object.entries(properties)) {
+    if (!TIME_WINDOW_KEYS.has(name.toLowerCase())) {
+      continue;
+    }
+    const type =
+      typeof spec === "object" && spec !== null ? (spec as { type?: unknown }).type : undefined;
+    const types = Array.isArray(type) ? type : [type];
+    if (types.includes("string")) {
+      keys.push(name);
+    }
+  }
+  return keys;
+}
+
+/**
+ * An omitted time window on a vendor tool is not "no window" — the vendor
+ * fills it with a live default (Datadog: `now-1h`..`now`), which the walker
+ * cannot see because the value is never present. In a frozen session a call
+ * that omits a schema-declared window key is refused so the model supplies
+ * the bound explicitly, where {@link forwardTimeArgument} then checks it.
+ */
+export function missingTimeWindow(
+  input: unknown,
+  windowKeys: readonly string[],
+  asOf: string,
+): string | undefined {
+  if (windowKeys.length === 0) {
+    return undefined;
+  }
+  const record =
+    typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+  const missing = windowKeys.filter(key => record[key] === undefined);
+  if (missing.length === 0) {
+    return undefined;
+  }
+  return (
+    `This tool fills omitted time bounds (${missing.join(", ")}) with a ` +
+    `live default window, which reads the real present. This session reads ` +
+    `the world as of ${asOf}; supply each bound explicitly as an absolute ` +
+    `ISO-8601 instant with a timezone at or before that instant and retry.`
+  );
+}

package/src/internal/auth.ts

@@ -0,0 +1,46 @@
+/**
+ * Auth helpers shared by the HTTP channel, session engine, and session store.
+ */
+
+import type { AuthContext } from "../types.js";
+
+/**
+ * Session ids must be a single path segment: no `..`, separators, or empty
+ * names. Generated ids use `ses_<24 hex>`; this also admits caller-provided
+ * safe keys without opening path traversal.
+ */
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export function isSafeSessionId(sessionId: string): boolean {
+  return (
+    SAFE_SESSION_ID.test(sessionId) &&
+    !sessionId.includes("..") &&
+    !sessionId.includes("/") &&
+    !sessionId.includes("\\")
+  );
+}
+
+/** Thrown when a send addresses a session owned by a different principal. */
+export class SessionAuthError extends Error {
+  constructor(sessionId: string) {
+    super(
+      `Session ${sessionId} belongs to a different principal; pass the original caller auth on follow-up`,
+    );
+    this.name = "SessionAuthError";
+  }
+}
+
+/** True when both sides identify the same principal (or both are null). */
+export function samePrincipal(a: AuthContext | null, b: AuthContext | null): boolean {
+  if (a === null && b === null) {
+    return true;
+  }
+  if (a === null || b === null) {
+    return false;
+  }
+  return (
+    a.authenticator === b.authenticator &&
+    a.principalId === b.principalId &&
+    a.principalType === b.principalType
+  );
+}

package/src/internal/authored-alias-hooks.ts

@@ -0,0 +1,138 @@
+/**
+ * Node module-customization hooks for authored agent files (registered via
+ * node:module `register()` from authored-loaders.ts; runs on Node's loader
+ * thread — keep this module dependency-free).
+ *
+ * Authored files import the framework by bare specifier. On compiled runs the
+ * CLI pins `@cursor/bdk[/subpath]` onto its own entry files via
+ * `directAliases` so channel-option WeakMaps stay single-copy. Preferring a
+ * project's own `node_modules` (or tsx tsconfig paths that map onto this
+ * package's `src/`) would load a second module instance and break
+ * `getGitHubChannelOptions` / continuation stamping / hosted-delivery.
+ *
+ * A separate case is first-party factory agents that relative-import this
+ * package's `src/` from a monorepo checkout. Hosted engines `npm install`
+ * only the agent directory, so files under `packages/agent-serve/src` have
+ * no `node_modules`. Bare specifiers from that tree (`zod`, octokit, …)
+ * retry against the running `@cursor/bdk` package.json, which does.
+ */
+
+// Null-prototype copies so specifiers like "constructor" or "__proto__"
+// can never resolve to inherited Object.prototype members.
+let directAliases = toNullProtoMap({});
+let sourceFallbackAliases = toNullProtoMap({});
+let sourceTreeFallbackParentURL: string | undefined;
+
+export interface AuthoredAliasHookData {
+  directAliases: Record<string, string>;
+  /**
+   * Framework exports omitted from the running distribution. Resolve these
+   * against an authored project's `anysphere-source` package condition.
+   */
+  sourceFallbackAliases?: string[];
+  /**
+   * `file:` URL of the running `@cursor/bdk` package.json. Bare imports
+   * from monorepo `packages/agent-serve/` source retry against this parent
+   * when the source tree has no `node_modules` (hosted factory engines).
+   */
+  sourceTreeFallbackParentURL?: string;
+}
+
+function toNullProtoMap(source: Record<string, string>): Record<string, string> {
+  return Object.assign(Object.create(null) as Record<string, string>, source);
+}
+
+export function initialize(data: AuthoredAliasHookData): void {
+  directAliases = toNullProtoMap(data.directAliases);
+  sourceFallbackAliases = toNullProtoMap(
+    Object.fromEntries((data.sourceFallbackAliases ?? []).map(specifier => [specifier, "1"])),
+  );
+  const parent = data.sourceTreeFallbackParentURL;
+  sourceTreeFallbackParentURL = typeof parent === "string" && parent !== "" ? parent : undefined;
+}
+
+interface ResolveResult {
+  url: string;
+  shortCircuit?: boolean;
+  format?: string | null;
+}
+
+type NextResolve = (specifier: string, context: unknown) => ResolveResult | Promise<ResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: unknown,
+  nextResolve: NextResolve,
+): ResolveResult | Promise<ResolveResult> {
+  const direct = directAliases[specifier];
+  if (direct !== undefined) {
+    return { url: direct, shortCircuit: true };
+  }
+  if (sourceFallbackAliases[specifier] !== undefined) {
+    return nextResolve(specifier, withCondition(context, "anysphere-source"));
+  }
+  if (
+    sourceTreeFallbackParentURL !== undefined &&
+    isBarePackageSpecifier(specifier) &&
+    isMonorepoAgentServeSource(parentURLOf(context))
+  ) {
+    const retryParent = sourceTreeFallbackParentURL;
+    return Promise.resolve()
+      .then(() => nextResolve(specifier, context))
+      .catch(() => nextResolve(specifier, withParentURL(context, retryParent)));
+  }
+  // Not ours: pass through with no promise/try-catch overhead. This hook
+  // runs on every module resolution in the process.
+  return nextResolve(specifier, context);
+}
+
+function parentURLOf(context: unknown): string | undefined {
+  if (context === null || typeof context !== "object") {
+    return undefined;
+  }
+  const parentURL = (context as { parentURL?: unknown }).parentURL;
+  return typeof parentURL === "string" ? parentURL : undefined;
+}
+
+function withParentURL(context: unknown, parentURL: string): unknown {
+  if (context !== null && typeof context === "object") {
+    return { ...(context as Record<string, unknown>), parentURL };
+  }
+  return { parentURL };
+}
+
+function withCondition(context: unknown, condition: string): unknown {
+  const record =
+    context !== null && typeof context === "object" ? (context as Record<string, unknown>) : {};
+  const conditions = Array.isArray(record["conditions"])
+    ? record["conditions"].filter((value): value is string => typeof value === "string")
+    : [];
+  return {
+    ...record,
+    conditions: conditions.includes(condition) ? conditions : [...conditions, condition],
+  };
+}
+
+function isBarePackageSpecifier(specifier: string): boolean {
+  if (specifier.length === 0) {
+    return false;
+  }
+  const first = specifier[0];
+  if (first === "." || first === "/" || first === "\\") {
+    return false;
+  }
+  return !(
+    specifier.startsWith("node:") ||
+    specifier.startsWith("file:") ||
+    specifier.startsWith("data:") ||
+    specifier.startsWith("http:") ||
+    specifier.startsWith("https:")
+  );
+}
+
+function isMonorepoAgentServeSource(parentURL: string | undefined): boolean {
+  if (parentURL === undefined) {
+    return false;
+  }
+  return parentURL.includes("/packages/agent-serve/") && !parentURL.includes("/node_modules/");
+}

package/src/internal/authored-loaders.ts

@@ -0,0 +1,188 @@
+/**
+ * Process-wide module loaders for authored agent files.
+ *
+ * The CLI dynamically imports user TypeScript (`agent/agent.ts`,
+ * `agent/tools/*.ts`, `evals/**\/*.eval.ts`) at runtime, and plain Node
+ * cannot load `.ts` modules. Instead of requiring hosts to wrap the bin in
+ * `node --import tsx`, the bin (and programmatic `serve()`) registers tsx's
+ * ESM loader itself on startup.
+ *
+ * On compiled runs it additionally registers alias hooks so authored bare
+ * imports of the framework (`@cursor/bdk[/x]`) short-circuit to the same
+ * files the CLI loaded. Channel option WeakMaps
+ * (`getGitHubChannelOptions`, …) require that identity; letting tsx path-map
+ * or a second install win loads a duplicate module and breaks continuation /
+ * hosted-delivery lookups. Bare npm deps from monorepo `packages/agent-serve/`
+ * source still retry against this package (hosted factory engines).
+ * Source runs (tsx from the monorepo) skip both — the host loader and
+ * tsconfig paths already cover them.
+ */
+
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { register as registerModuleHooks } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { AuthoredAliasHookData } from "./authored-alias-hooks.js";
+import {
+  CLI_COMMAND_NAME,
+  frameworkAliases,
+  isCompiledDistribution,
+  packageRootDir,
+} from "./distribution.js";
+
+/**
+ * Cross-copy markers: a user project with its own `@cursor/bdk` install
+ * can load a second copy of this module in the same process; tsx and the
+ * alias hooks must only be registered once. The key strings are shared with
+ * already-published copies; renaming them would double-register.
+ */
+const TSX_REGISTERED_KEY = Symbol.for("cursor.agentkit.tsxRegistered");
+const ALIASES_REGISTERED_KEY = Symbol.for("cursor.agentkit.aliasesRegistered");
+
+/**
+ * ESM specifier for an authored agent/eval file.
+ *
+ * Node caches `import()` by URL for the life of the process, so a long-lived
+ * `agent-sdk dev` would otherwise keep serving the first load of eval files
+ * and agent modules. The mtime query string is ignored by the filesystem
+ * resolver and is the cache key.
+ *
+ * Truncate to an integer: vitest/esbuild treat the substring after the last
+ * `.` as a loader id, so `?mtime=1700000000000.4949` fails with
+ * `Invalid loader value: "4949"`. Named `mtime` rather than `t` so Vite does
+ * not treat it as its HMR timestamp and collapse the specifier to the path.
+ */
+export function authoredModuleSpecifier(absolutePath: string, mtimeMs: number): string {
+  const url = pathToFileURL(absolutePath);
+  url.searchParams.set("mtime", String(Math.trunc(mtimeMs)));
+  return url.href;
+}
+
+export function partitionFrameworkAliases(aliases: Record<string, string>): {
+  directAliases: Record<string, string>;
+  sourceFallbackAliases: string[];
+} {
+  const directAliases: Record<string, string> = {};
+  const sourceFallbackAliases: string[] = [];
+  for (const [specifier, url] of Object.entries(aliases)) {
+    if (existsSync(fileURLToPath(url))) {
+      directAliases[specifier] = url;
+    } else {
+      sourceFallbackAliases.push(specifier);
+    }
+  }
+  return { directAliases, sourceFallbackAliases };
+}
+
+/**
+ * Dynamically import an authored TypeScript/JavaScript module, re-reading it
+ * from disk when the file's mtime has changed since the last import.
+ */
+export async function importAuthoredModule(absolutePath: string): Promise<Record<string, unknown>> {
+  let mtimeMs = 0;
+  try {
+    mtimeMs = (await stat(absolutePath)).mtimeMs;
+  } catch {
+    // import() reports the real missing-file error.
+  }
+  const loaded: unknown = await import(authoredModuleSpecifier(absolutePath, mtimeMs));
+  if (typeof loaded !== "object" || loaded === null) {
+    throw new Error(`authored module is not an object: ${absolutePath}`);
+  }
+  return loaded as Record<string, unknown>;
+}
+
+let registration: Promise<void> | undefined;
+
+/**
+ * Install the runtime loaders for authored agent files. Idempotent; called
+ * from the CLI entry before any command runs, and from `serve()` and the
+ * discovery APIs for programmatic embedders. Concurrent callers share one
+ * registration and all wait for it to finish.
+ */
+export function registerAuthoredModuleLoaders(): Promise<void> {
+  if (!isCompiledDistribution()) {
+    return Promise.resolve();
+  }
+  registration ??= (async () => {
+    await registerTsxLoader();
+    registerFrameworkAliases();
+  })();
+  return registration;
+}
+
+async function registerTsxLoader(): Promise<void> {
+  // Escape hatch for hosts that precompile authored files to .js (or bring
+  // their own loader) and don't want tsx hooked into module resolution.
+  if (process.env.AGENT_SERVE_DISABLE_TSX === "1") {
+    return;
+  }
+  if (tsxAlreadyActive()) {
+    return;
+  }
+  try {
+    const tsx = (await import("tsx/esm/api")) as {
+      register: () => unknown;
+    };
+    if (typeof tsx.register !== "function") {
+      throw new Error("tsx/esm/api has no register export");
+    }
+    tsx.register();
+    (globalThis as Record<symbol, unknown>)[TSX_REGISTERED_KEY] = true;
+  } catch (error) {
+    process.stderr.write(
+      `[${CLI_COMMAND_NAME}] tsx loader unavailable (${
+        error instanceof Error ? error.message : String(error)
+      }); authored TypeScript files will not load — install tsx or precompile the agent to .js\n`,
+    );
+  }
+}
+
+/**
+ * Whether a tsx loader is already installed process-wide: by a previous call
+ * from another copy of this module, or by the host command line (the Docker
+ * flow still runs `node --import tsx dist/bin/agent-serve.js`).
+ */
+function tsxAlreadyActive(): boolean {
+  if ((globalThis as Record<symbol, unknown>)[TSX_REGISTERED_KEY] === true) {
+    return true;
+  }
+  const hostArgs = [...process.execArgv, ...(process.env.NODE_OPTIONS?.split(/\s+/) ?? [])];
+  for (let i = 0; i < hostArgs.length; i++) {
+    const arg = hostArgs[i];
+    if (arg === "--import" || arg === "--loader" || arg === "--require") {
+      const value = hostArgs[i + 1];
+      if (value === "tsx" || value?.startsWith("tsx/")) {
+        return true;
+      }
+    } else if (arg !== undefined && /^--(import|loader|require)=tsx(\/|$)/.test(arg)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function registerFrameworkAliases(): void {
+  const markers = globalThis as Record<symbol, unknown>;
+  if (markers[ALIASES_REGISTERED_KEY] === true) {
+    return;
+  }
+  const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
+  const { directAliases, sourceFallbackAliases } = partitionFrameworkAliases(frameworkAliases());
+  const data: AuthoredAliasHookData = {
+    directAliases,
+    // Internal-only exports stay out of the public package. When one is
+    // mounted by an agent in this source checkout, resolve that one import
+    // through the checkout's `anysphere-source` export instead.
+    sourceFallbackAliases,
+    // Hosted factory agents relative-import this package's src/ from a
+    // monorepo checkout while npm install ran only in the agent directory.
+    // Bare specifiers from that tree retry against this package.json.
+    sourceTreeFallbackParentURL: pathToFileURL(join(packageRootDir(), "package.json")).href,
+  };
+  // `node:module`'s register() is synchronous: it blocks until the hooks
+  // thread has initialized, so the aliases are active when it returns.
+  registerModuleHooks(hooksUrl, { data });
+  markers[ALIASES_REGISTERED_KEY] = true;
+}

package/src/internal/bounded-int.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared validation for optional config ceilings (playground windows, etc.).
+ */
+
+export function normalizePositiveInt(
+  value: unknown,
+  options: {
+    /** e.g. `evals.config.ts: maxPlaygroundRuns` */
+    label: string;
+    max: number;
+    /** Override the default "exceeds the hard limit" message body after the label. */
+    maxMessage?: string;
+  },
+): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(`${options.label} must be a positive integer (got ${String(value)})`);
+  }
+  if (value > options.max) {
+    throw new Error(
+      options.maxMessage ?? `${options.label} ${value} exceeds the hard limit of ${options.max}`,
+    );
+  }
+  return value;
+}

package/src/internal/bounded.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded-concurrency map, in input order. Local rather than
+ * `@anysphere/utils`: this published package cannot depend on monorepo
+ * internals.
+ */
+export async function mapBounded<T, R>(
+  items: readonly T[],
+  max: number,
+  run: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(max, items.length) }, async () => {
+    for (;;) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= items.length) {
+        return;
+      }
+      out[index] = await run(items[index] as T);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}