@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/auth/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * M42 — shared auth contract types. A LEAF module: pure type declarations, NO runtime imports (no zod, no
+ * node:fs). Every auth module (`credential-store`, `oauth-engine`, `oauth-device`, `resolve-credential`)
+ * imports its cross-module types from here so the barrel's rollup-plugin-dts bundle sees a single canonical
+ * origin — the codebase's established "leaf-type-only deps" pattern (see tsup.config.ts), which sidesteps
+ * the rollup-dts cross-module resolution limitation that a value-module type export trips.
+ *
+ * Every type here is re-exported from `@theokit/sdk/auth` and is therefore PUBLIC, under semver.
+ *
+ * This block sits directly above `CredentialStoreConfig` with no statement between them, so it is
+ * one of that declaration's leading comment ranges — an internal-visibility tag written here is
+ * scanned by `stripInternal` and deletes the interface from the emitted `.d.ts`. That is exactly
+ * what happened, and it is the same trap recorded in `src/auth/index.ts`
+ * (usetheodev/theokit-sdk#283). Do not name that tag anywhere in this file.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Where the credential store lives — the three path segments, plus an optional environment
+ * override.
+ *
+ * The store directory is `join(home, dirName)` and the file is `fileName` inside it. When
+ * `homeEnvVar` is set AND the caller's `env` map holds that variable non-blank, its trimmed value
+ * REPLACES the whole directory: `dirName` is not appended to it, mirroring how `CODEX_HOME` works.
+ * A blank or absent variable falls back to `join(home, dirName)`.
+ *
+ * `env` is always a parameter on the functions that take this config, never an ambient
+ * `process.env` read, and it defaults to an empty map — so a caller that forgets to pass it gets
+ * the non-overridden path rather than whatever the process happens to have.
+ *
+ * Nothing here is validated or created. A relative `home` stays relative to the process cwd, and
+ * the directory is created on first write, at mode 0700.
+ *
+ * The store this addresses holds live credentials in plaintext, so `dirName` should be a directory
+ * the SDK owns rather than one shared with unrelated state: reads enforce 0700 on the directory
+ * and 0600 on the file, and refuse when either is looser.
+ */
+export interface CredentialStoreConfig {
+    /** Base home directory (e.g. `os.homedir()`). */
+    home: string;
+    /** The store subdirectory under `home` (e.g. `.agent-builder`, `.codex`). */
+    dirName: string;
+    /** The credential file name inside the store dir (e.g. `auth.json`). */
+    fileName: string;
+    /** Optional env var name that, when set + non-blank, overrides the full store dir. */
+    homeEnvVar?: string;
+}
+/**
+ * The flat bearer surface every consumer holds. `kind:'api'` is the classic API-key path; `kind:'oauth'` is
+ * an OAuth session whose `apiKey` is the CURRENT access token, so consumers keep passing a flat bearer
+ * string unchanged. `provider` is an open string (any registered provider name).
+ */
+export interface ResolvedCredential {
+    kind: "api" | "oauth";
+    provider: string;
+    /** The effective BEARER the transport sends — an API key, or (oauth) the current access token. */
+    apiKey: string;
+    /** Where it came from — an env var NAME or a file path. Never the value. */
+    source: string;
+    /** True when the provider was derived rather than declared. */
+    inferred: boolean;
+    /** oauth only: epoch ms the access token expires. Drives the refresh in the oauth engine. */
+    expiresAt?: number;
+}
+/**
+ * The API-key variant of the credential file, as it sits on disk.
+ *
+ * `api_key` is the key in PLAINTEXT. Nothing in this SDK encrypts, hashes or otherwise obscures
+ * it; the protection is filesystem permissions alone — `writeCredential` persists the file at
+ * mode 0600 inside a 0700 directory, and `readAuthFile` refuses to read a file readable by other
+ * users or a directory writable by them. On Windows that gate is skipped entirely, because the
+ * mode bits Node reports there do not describe the real ACLs.
+ *
+ * `type` and `provider` are both optional so that a legacy file written before the union existed
+ * — a bare `{ "provider": ..., "api_key": ... }` — still parses as this variant with no
+ * migration. `type` is never written: the api variant is persisted without the discriminant, and
+ * absence of `type` is what identifies it on the next read.
+ *
+ * The file schema is strict, so an unknown key makes the whole file fail to parse with a
+ * `CredentialError` naming the offending path.
+ */
+export interface StoredApiCredential {
+    type?: "api";
+    provider?: string;
+    api_key: string;
+}
+/**
+ * The OAuth variant of the credential file, as it sits on disk.
+ *
+ * `access` and `refresh` are both stored in PLAINTEXT, under the same 0600 file / 0700 directory
+ * gate as the API-key variant and with no additional protection. The refresh token is the more
+ * durable of the two — an expired `access` is worth little, a leaked `refresh` mints new ones —
+ * and it is why `readStoredOAuth` is the only path that hands this shape out: the resolved
+ * credential every other consumer sees carries the access token and nothing else.
+ *
+ * `type: "oauth"` is the discriminant and is always written; a file without it reads back as the
+ * API-key variant. `provider`, `access` and `refresh` must be non-empty — `writeCredential`
+ * refuses an empty access or refresh token, and the read schema rejects empty strings.
+ *
+ * `expires` is epoch milliseconds for the ACCESS token only. Nothing here records when the
+ * refresh token expires, so a refresh failing because the grant itself lapsed is only observable
+ * at the token endpoint.
+ */
+export interface StoredOAuthCredential {
+    type: "oauth";
+    provider: string;
+    access: string;
+    refresh: string;
+    /** Epoch ms the access token expires. */
+    expires: number;
+    account_id?: string;
+}
+/**
+ * Whatever the credential file turned out to hold — the two variants are discriminated by `type`.
+ *
+ * Narrow with `stored.type === "oauth"`, not by probing for a field. The API-key variant leaves
+ * `type` undefined rather than setting it to `"api"`, so `type !== "oauth"` is the reliable test
+ * for the API-key side and `type === "api"` misses every legacy file.
+ *
+ * Reading a file is what produces this value, and both variants carry a live secret in plaintext.
+ * Treat it as one: it should not be logged, serialized into telemetry, or put in an error message.
+ */
+export type StoredCredential = StoredApiCredential | StoredOAuthCredential;
+/** A provider's OAuth endpoints + client identity. Passed in (provider-agnostic). */
+export interface OAuthProviderConfig {
+    provider: string;
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    scopes: readonly string[];
+    redirectUri: string;
+}
+/** The token triple persisted to the store's oauth variant. */
+export interface OAuthTokens {
+    access: string;
+    refresh: string;
+    /** Epoch ms the access token expires. */
+    expires: number;
+    accountId?: string;
+}
+/** Injected HTTP + clock effects — deterministic in tests, real in production. */
+export interface HttpDeps {
+    fetch: typeof fetch;
+    now: () => number;
+}
+/** A device-grant config: the OAuth config plus the RFC 8628 device authorization endpoint. */
+export interface DeviceOAuthConfig extends OAuthProviderConfig {
+    /** RFC 8628 device authorization endpoint — returns device_code + user_code + verification_uri. */
+    deviceCodeEndpoint: string;
+}
+/** The device authorization the user acts on. Times/interval are SECONDS (RFC 8628). */
+export interface DeviceCodeGrant {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** Seconds between token polls (server-mandated minimum). */
+    interval: number;
+    /** Seconds until the device_code expires. */
+    expiresIn: number;
+}
+/** Injected effects for the device flow — deterministic in tests, real in production. */
+export interface DeviceDeps {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+/** The OpenAI two-step device config: usercode + poll endpoints return an authorization_code (not tokens). */
+export interface OpenAIDeviceConfig extends OAuthProviderConfig {
+    /** POST `{client_id}` here → `{device_auth_id, user_code, interval}`. */
+    deviceUsercodeEndpoint: string;
+    /** Poll `{device_auth_id, user_code}` here → 200 `{authorization_code, code_verifier}`; 403/404 = pending. */
+    devicePollEndpoint: string;
+    /** Verification URL the user opens to enter the code. */
+    verificationUri: string;
+}

package/dist/internal/base-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `THEOKIT_API_BASE_URL`, read in one place.
+ *
+ * A leaf on purpose: `internal/http.ts` resolves the SDK's endpoint from it, and so do the cloud
+ * agent and `internal/agent/helpers.ts`. It used to live in `runtime/fixtures/fixture-mode.ts`,
+ * which meant a production HTTP module resolved its base URL out of a module named for test
+ * fixtures. `fixture-mode.ts` is now one of its four consumers rather than its owner — it needs the
+ * value because an explicitly configured base URL short-circuits fixture mode.
+ *
+ * Nothing is imported here beyond the environment, so no consumer risks a cycle through it.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/budget/compute-cost.d.ts

@@ -0,0 +1,28 @@
+/**
+ * computeCost — apply pricing entries to a TokenUsage and produce a
+ * CostBreakdown (ADRs D377, D378).
+ *
+ * Edge cases absorbed:
+ *   - EC-13: negative pricing → status="unknown" + note.
+ *   - EC-14: reasoning tokens fall back to outputCostPerMillion when
+ *     dedicated reasoning rate is undefined.
+ *   - EC-12: money precision via microcent normalization (× 1e6).
+ *   - "subscription_included" routes (Codex CLI, future Claude Pro) →
+ *     return $0 with status="included".
+ *   - Provider unknown / pricing missing → status="unknown" with
+ *     undefined amountUsd (does NOT return a false 0).
+ *
+ * @internal
+ */
+interface ComputeArgs {
+    readonly usage: TokenUsage;
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Returns CostBreakdown with `status="estimated"`, `"unknown"`, or
+ * `"included"`. Never throws; never returns 0 when pricing is missing.
+ */
+export declare function computeCost(args: ComputeArgs): CostBreakdown;
+export {};

package/dist/internal/budget/pricing-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pricing registry — bundled snapshot of LiteLLM JSON (ADR D379) with
+ * lazy load + alias normalization (EC-2).
+ *
+ * Snapshot lives in `pricing-data.json` (hand-curated 2026-05; refresh
+ * via `scripts/refresh-pricing.mjs`). All rates in USD per 1_000_000
+ * tokens (D378).
+ *
+ * Lookup precedence (EC-2):
+ *   1. Direct `provider/model` key
+ *   2. Strip date suffix (-YYYYMMDD or -YYYY-MM-DD)
+ *   3. Anthropic dot-to-dash normalization (claude-opus-4.7 → claude-opus-4-7)
+ *   4. Strip `openrouter/` prefix
+ *
+ * @internal
+ */
+export interface PricingEntry {
+    readonly provider: string;
+    readonly model: string;
+    readonly inputCostPerMillion: number;
+    readonly outputCostPerMillion: number;
+    readonly cacheReadCostPerMillion?: number;
+    readonly cacheWriteCostPerMillion?: number;
+    readonly reasoningCostPerMillion?: number;
+    readonly pricingVersion: string;
+}
+/**
+ * Returns the pricing entry for a given `{provider, model}` route.
+ * Tries direct lookup, then 3 alias normalizations (EC-2).
+ */
+export declare function getPricingEntry(opts: {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+}): PricingEntry | undefined;
+export declare function pricingVersion(): string;

package/dist/internal/budget/tracker/budget-tracker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `BudgetTracker` and companion contract types.
+ *
+ * The contract now lives in the domain `types/` layer (SE46 DIP direction):
+ * `types/budget-tracker.ts` owns the interfaces; this application-layer module
+ * re-exports them so existing importers (agent-loop, counter impl, index.ts)
+ * keep resolving the same names.
+ *
+ * @public — surface-level interface; impl is internal-but-replaceable.
+ */
+export type { BudgetCheck, BudgetTotal, BudgetTracker, BudgetUsageEvent, } from "../../../types/budget-tracker.js";

package/dist/internal/budget/tracker/budget.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Iteration budget for the agent loop (T2.1, ADRs D90-D91).
+ *
+ * Tracks remaining iterations + compression attempts + grace-call usage.
+ * Caps prevent the 4 compression death spirals Hermes shipped:
+ *   - v0.4 #1723: `compression_attempts` never reset
+ *   - v0.7 #4750: compression triggers → fails → triggers again
+ *   - v0.11 #10065: stale agent timeout, empty response after tools
+ *   - v0.11 #10472: empty-tools after tools, premature loop exit
+ *
+ * Default: max 8 iterations, max 3 compressions per session, 1 grace call.
+ *
+ * NOTE on caller-supplied huge maxIterations (EC-12): `Number.MAX_SAFE_INTEGER`
+ * is honored — caller is responsible for picking a reasonable cap. Recommended
+ * ≤32 for production workloads.
+ *
+ * NOTE on per-send reset (EC-14): each `Agent.send` should construct a fresh
+ * `IterationBudget`. This is intentional — every send is its own iteration
+ * round, not a long-running budget shared across sends.
+ *
+ * NOTE on how exhaustion is signalled (B-140): by RETURN VALUE, never by
+ * throwing — `recordCompression()` answers `{ allowed: false, reason }` and
+ * `shouldContinue()` answers `false`. Running out of budget is an expected
+ * outcome of the loop, not an exceptional one, so it is not an exception
+ * (`rules/error-handling.md` § 2: never use exceptions for control flow).
+ * Three exported error classes for these cases (`IterationBudgetExhaustedError`,
+ * `CompressionExhaustedError`, `CompressionIneffectiveError`) survived here from
+ * an earlier design and were thrown by nothing; removed 2026-08-20. If you find
+ * yourself re-adding one, the question to settle first is whether the caller can
+ * act on the difference — because today it reads a reason string instead.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/budget/usage-accumulator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * UsageAccumulator — aggregate multi-step `LlmFinish` token counts
+ * into a canonical `TokenUsage` (ADR D376, mirror a peer SDK
+ * `Usage.add`).
+ *
+ * Each `add(step)` merges in a per-step finish; `toTokenUsage()`
+ * produces the aggregated public shape with `requests[]` populated
+ * when there were ≥2 steps.
+ *
+ * @internal
+ */
+interface StepUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * Sums the per-step token counts of a multi-step run into one `TokenUsage`.
+ *
+ * Call `add` once per LLM finish, in any order, then `toTokenUsage` to read the total. The instance
+ * is a running sum, not a snapshot: `toTokenUsage` may be called repeatedly and reflects everything
+ * added so far, and there is no reset — start a new accumulator per run.
+ *
+ * Two shaping rules to expect in the output. The optional counters (cache read, cache write,
+ * reasoning) are omitted entirely when they sum to zero rather than reported as `0`. And the
+ * per-step `requests` array appears only when at least TWO steps were added, so a single-step run
+ * carries totals alone.
+ *
+ * `totalTokens` is input plus output only — cache and reasoning counts are reported separately and
+ * are not folded into it.
+ */
+export declare class UsageAccumulator {
+    private input;
+    private output;
+    private cacheRead;
+    private cacheWrite;
+    private reasoning;
+    private readonly requests;
+    add(step: StepUsage): void;
+    /** Did we observe any usage at all? */
+    hasAny(): boolean;
+    toTokenUsage(): TokenUsage;
+}
+export {};

package/dist/internal/cloud-agent/cloud-agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/cloud-agent/cloud-config-serializer.d.ts

@@ -0,0 +1,3 @@
+import type { AgentOptions } from "../../types/agent.js";
+import type { CloudAgentPayload } from "./types.js";
+export declare function serializeCloudAgentConfig(options: AgentOptions): CloudAgentPayload;

package/dist/internal/cloud-agent/cloud-run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/cloud-agent/cloud-tool-parity.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/cloud-agent/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Barrel for the cloud runtime agent (SE43 DoD#1 — promoted out of
+ * `internal/runtime/` to reduce that package's blast radius). External
+ * consumers import the cloud surface through this barrel, not deep paths.
+ */
+export { CloudAgent } from "./cloud-agent.js";
+export { validateCloudToolParity } from "./cloud-tool-parity.js";

package/dist/internal/cloud-agent/real-cloud-run.d.ts

@@ -0,0 +1,2 @@
+import type { Run } from "../../types/run.js";
+export declare function createRealCloudRun(options: CreateRealCloudRunOptions): Run;

package/dist/internal/cloud-agent/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Canonical JSON contract that the SDK posts to TheoCloud at
+ * `POST /v1/agents/{id}/runs`. PaaS reads this to reconstruct the agent's
+ * tool catalog server-side (skills, plugins, hooks rules, MCP HTTP servers,
+ * subagents, providers, memory, context).
+ *
+ * Locked at `schemaVersion: "1.0"`. Adding fields is forward-compatible;
+ * removing or renaming requires a v2 ADR (see ADR D15).
+ *
+ * @internal
+ */
+export interface CloudPayloadCloud {
+    repos: ReadonlyArray<{
+        url: string;
+        startingRef?: string;
+    }>;
+    autoCreatePR?: boolean;
+}
+export interface HookRule {
+    event: string;
+    command?: string;
+    reject?: string;
+}
+export interface McpHttpRedacted {
+    type: "http";
+    url: string;
+}
+export interface McpStdioRedacted {
+    type: "stdio";
+    command: string;
+    args?: ReadonlyArray<string>;
+}
+export interface SubagentRef {
+    description?: string;
+    systemPrompt?: string;
+    model?: {
+        id: string;
+    };
+}
+export interface ProvidersRedacted {
+    routes?: ReadonlyArray<{
+        provider: string;
+        model?: string;
+    }>;
+    fallback?: ReadonlyArray<string>;
+}
+export interface MemoryPayload {
+    enabled: boolean;
+    index?: {
+        backend: "sqlite-vec" | "lance";
+        embedding?: {
+            provider: string;
+            model?: string;
+        };
+    };
+}

package/dist/internal/concurrency/abort-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `AbortSignal` composition helpers (Production-Readiness #5 / EC-5, ADR D324).
+ *
+ * `AbortSignal.any` is available in Node 22+ and Cloudflare Workers, but
+ * some runtime environments (a peer vendor Edge subset, older Bun, embedded shells)
+ * still lag. The ponyfill mirrors the spec semantics — abort on first signal,
+ * propagate `reason` — without depending on the host symbol.
+ *
+ * @internal
+ */
+/**
+ * `true` when the given (possibly undefined) signal has aborted. `undefined`
+ * signal counts as not aborted (no-signal semantics).
+ */
+export declare function isAborted(signal: AbortSignal | undefined): boolean;
+/**
+ * Extract the abort reason as an `Error` for wrapping into `AgentRunError`.
+ * Spec: `signal.reason` is `unknown` — wrap non-Error values into a generic
+ * error so callers always have a `.message` to inspect.
+ */
+export declare function abortReasonAsError(signal: AbortSignal): Error;

package/dist/internal/concurrency/async-local-storage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-fork tool whitelist via `AsyncLocalStorage` (ADR D111).
+ *
+ * Forked agents (background review, curator, judge) need a tool subset
+ * distinct from the parent's. A global mutable `let _whitelist` would
+ * corrupt state when two forks run in parallel. `AsyncLocalStorage`
+ * propagates the whitelist through the async chain so each fork sees its
+ * own — no cross-fork bleed.
+ *
+ * Outside a `withToolWhitelist(...)` scope, `currentToolWhitelist()`
+ * returns `undefined` and `checkToolWhitelist` allows every tool — the
+ * parent agent is unaffected.
+ *
+ * Wire site: `internal/agent-loop/tool-dispatch.ts:dispatchSingleCall`
+ * calls `checkToolWhitelist` after the repair middleware and before
+ * `tools.find`.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/concurrency/async-semaphore.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Async-aware counting semaphore (ADR D135).
+ *
+ * N-permit gate for cooperative concurrency control inside a single
+ * Node process. Used by `Agent.batch` to bound parallel agent count
+ * without pulling in `p-limit` or `p-queue` (~30 LoC in-house).
+ *
+ * Contract: `acquire()` returns a release function. Caller MUST call
+ * release exactly once when done — typically in a `finally` block.
+ * Release is idempotent (multiple calls are no-ops after the first)
+ * for defense against caller bugs, but leaking the release function
+ * permanently consumes one permit (EC-G — caller responsibility).
+ *
+ * @internal
+ */
+export interface AsyncSemaphore {
+    /** Acquire a permit. Returns the release function (call once). */
+    acquire(): Promise<() => void>;
+    /** Permits currently held in flight. */
+    inFlight(): number;
+    /** Total: in-flight + queued waiters. */
+    pending(): number;
+}
+export declare function createSemaphore(permits: number): AsyncSemaphore;

package/dist/internal/concurrency/delegation-depth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * #364 — how deep the current delegation chain already is, delivered through the CALL.
+ *
+ * ## The bug this replaces
+ *
+ * `maxDelegationDepth` was checked once, at tool-CONSTRUCTION time, against a `_parentDepth`
+ * argument that nothing in the SDK ever incremented. Constructing a tool says nothing about how
+ * deep it will later be invoked, so with the documented call — `SubAgent.create(spec)` — the test
+ * was `1 > maxDepth`, false for every spec that did not ask for depth 0. A subagent whose tools
+ * include another subagent recursed unbounded, which is precisely what the guard exists to stop.
+ * The only path that ever tripped it was a caller threading the number by hand.
+ *
+ * ## Why the async scope closes it
+ *
+ * Depth is a property of the RUN, not of the object. A child's run loop — and therefore every tool
+ * it dispatches — executes inside the async continuation of its parent's handler, so a value
+ * published on that context is exactly what a nested dispatch needs to read. This is the same seam
+ * `subagent-credentials.ts` uses, and for the same reason: what survives every layer that rebuilds
+ * a tool object is the call, never the object.
+ *
+ * It is kept in its own module rather than folded into the credentials payload because depth is a
+ * separate concern with a separate lifetime — the credentials scope is opened once per run by the
+ * run loop, while depth is opened per delegation by the dispatching tool.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/concurrency/map-with-concurrency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ordered, bounded-concurrency parallel map (plan m0-foundation-expose-primitives, M0-2).
+ *
+ * Runs `fn` over `items` with at most `concurrency` invocations in flight at
+ * once, preserving input order in the result array. Fail-fast: rejects with the
+ * first error a task throws (matching the in-house `boundedParallel`/`runBatches`
+ * clones this consolidates). Backed by the in-house {@link createSemaphore}
+ * (ADR D135 — no `p-limit`/`p-map` dependency).
+ *
+ * @internal — public via `@theokit/sdk/concurrency`
+ */
+/**
+ * Map `fn` over `items` with bounded concurrency, preserving order.
+ *
+ * @param items - inputs to process
+ * @param concurrency - max in-flight invocations (positive integer; validated)
+ * @param fn - async mapper; receives the item, its index, and an abort signal
+ * @param options.signal - optional abort signal; once aborted, no new `fn`
+ *   invocation is started (in-flight ones are not force-cancelled)
+ * @returns results in the same order as `items`
+ * @throws ConfigurationError when `concurrency` is not a positive integer
+ *
+ * @example
+ *   await mapWithConcurrency([1, 2, 3], 2, async (n) => n * 2); // [2, 4, 6]
+ */
+export declare function mapWithConcurrency<T, R>(items: ReadonlyArray<T>, concurrency: number, fn: (item: T, index: number, signal: AbortSignal) => Promise<R>, options?: {
+    signal?: AbortSignal;
+}): Promise<R[]>;