@juno-ai/bind 2.0.0 → 3.0.0

package/routing/circuit-breaker.d.ts

@@ -1,5 +1,5 @@
-import type { ProviderId } from "./canonical-model";
-import type { CredentialSource } from "./plan";
+import type { ProviderId } from "./canonical-model.js";
+import type { CredentialSource } from "./plan.js";
 /**
  * Circuit-breaker state is keyed by (provider, invocation model, credential
  * source) — LLM Provider Routing PRD §7.2. State is process-local in v1;

package/routing/errors.d.ts

@@ -1,4 +1,4 @@
-import type { CanonicalModelId, ProviderId } from "./canonical-model";
+import type { CanonicalModelId, ProviderId } from "./canonical-model.js";
 /**
  * The normative attempt-order cursor (LLM Provider Routing PRD §5.2):
  * structured-output attempt → model stage → provider candidate → same-endpoint

package/routing/executor.d.ts

@@ -1,6 +1,6 @@
-import type { RouteCandidate, RoutePlan } from "./plan";
-import { type InferenceAttemptError, type RouteAttemptCursor } from "./errors";
-import type { RouteCircuitBreaker } from "./circuit-breaker";
+import type { RouteCandidate, RoutePlan } from "./plan.js";
+import { type InferenceAttemptError, type RouteAttemptCursor } from "./errors.js";
+import type { RouteCircuitBreaker } from "./circuit-breaker.js";
 export type AttemptOutcome<T> = Readonly<{
     kind: "success";
     value: T;

package/routing/executor.js

@@ -1,4 +1,4 @@
-import { failureDisposition, isRetriableAttemptError, } from "./errors";
+import { failureDisposition, isRetriableAttemptError, } from "./errors.js";
 /**
  * Drive one structured-output attempt over a frozen route plan with the
  * normative loop nesting (PRD §5.2): model stage → provider candidate →

package/routing/index.d.ts

@@ -1,9 +1,11 @@
-export { canonicalModelIdSchema, providerIdSchema, type CanonicalModelId, type ProviderId, } from "./canonical-model";
-export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, type RoutePolicyVersion, type ProviderPolicy, type ModelRouteRegistry, } from "./policy";
-export { INFERENCE_CAPABILITIES, planIsEmpty, type InferenceCapability, type CredentialSource, type InferenceRequirements, type CachedTokenSemantics, type ProviderPricingBasis, type RouteCandidate, type RouteStage, type RoutePlan, type RouteSkip, } from "./plan";
-export { type TransportAvailability, type CandidateResolution, type PlannerTransport, } from "./transport";
-export { buildRoutePlan, type RoutePlanRequest, type RoutePlanResult } from "./planner";
-export { fallbackKindOfCursor } from "./executor";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors";
-export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker";
-export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor";
+export { canonicalModelIdSchema, providerIdSchema, type CanonicalModelId, type ProviderId, } from "./canonical-model.js";
+export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, type RoutePolicyVersion, type ProviderPolicy, type ModelRouteRegistry, } from "./policy.js";
+export { INFERENCE_CAPABILITIES, planIsEmpty, type InferenceCapability, type CredentialSource, type InferenceRequirements, type CachedTokenSemantics, type ProviderPricingBasis, type RouteCandidate, type RouteStage, type RoutePlan, type RouteSkip, } from "./plan.js";
+export { type TransportAvailability, type CandidateResolution, type PlannerTransport, } from "./transport.js";
+export { buildRoutePlan, type RoutePlanRequest, type RoutePlanResult } from "./planner.js";
+export { buildRoutePlanWithConfigDegradation, type DegradedStage, type DegradedPlanResult, } from "./plan-degradation.js";
+export { computeConfiguredRatesCostCents, type BillingBasisUsage, type BillingBasisResult, } from "./billing-basis.js";
+export { fallbackKindOfCursor } from "./executor.js";
+export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
+export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker.js";
+export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor.js";

package/routing/index.js

@@ -1,9 +1,11 @@
-export { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model";
-export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, } from "./policy";
-export { INFERENCE_CAPABILITIES, planIsEmpty, } from "./plan";
-export {} from "./transport";
-export { buildRoutePlan } from "./planner";
-export { fallbackKindOfCursor } from "./executor";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors";
-export { createCircuitBreaker, } from "./circuit-breaker";
-export { executeRoutePlan, } from "./executor";
+export { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model.js";
+export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, } from "./policy.js";
+export { INFERENCE_CAPABILITIES, planIsEmpty, } from "./plan.js";
+export {} from "./transport.js";
+export { buildRoutePlan } from "./planner.js";
+export { buildRoutePlanWithConfigDegradation, } from "./plan-degradation.js";
+export { computeConfiguredRatesCostCents, } from "./billing-basis.js";
+export { fallbackKindOfCursor } from "./executor.js";
+export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
+export { createCircuitBreaker, } from "./circuit-breaker.js";
+export { executeRoutePlan, } from "./executor.js";

package/routing/plan-degradation.d.ts

@@ -0,0 +1,34 @@
+import type { CanonicalModelId } from "./canonical-model.js";
+import type { RouteSkip } from "./plan.js";
+import { type RoutePlanRequest, type RoutePlanResult } from "./planner.js";
+import { type ProviderPolicy } from "./policy.js";
+/**
+ * Configuration-degradation wrapper around the harness planner.
+ *
+ * Policy: even when a provider has priority over the default (an explicit
+ * `only` fence or an ordered policy naming it first), **missing keys or
+ * configuration must never make inference unavailable** — the call degrades
+ * to the default provider and the caller logs an error. This keeps
+ * development environments that hold only an OpenRouter key fully working
+ * while a checked-in policy prioritizes (say) Azure, and keeps production
+ * serving through a provider-config regression instead of hard-failing.
+ *
+ * Scope: PLAN-TIME emptiness only — a stage with zero attemptable candidates
+ * (transport unconfigured/invalid, no binding for the model, capability
+ * mismatch). Runtime failures keep the fence semantics: a configured `only`
+ * provider that errors at request time is never retried through another
+ * provider; the executor's cross-provider traversal applies only
+ * within the plan the policy allowed.
+ */
+export interface DegradedStage {
+    readonly model: CanonicalModelId;
+    /** The policy that produced an empty stage. */
+    readonly fromPolicy: ProviderPolicy;
+    /** Plan skips recorded for this model under the original policy. */
+    readonly skips: readonly RouteSkip[];
+}
+export interface DegradedPlanResult extends RoutePlanResult {
+    /** Stages rebuilt under the degraded default; empty when nothing degraded. */
+    readonly degraded: readonly DegradedStage[];
+}
+export declare function buildRoutePlanWithConfigDegradation(request: RoutePlanRequest, degradedPolicy: ProviderPolicy): DegradedPlanResult;

package/routing/plan-degradation.js

@@ -0,0 +1,38 @@
+import { buildRoutePlan, } from "./planner.js";
+import { policyProviderOrder } from "./policy.js";
+function policiesEqual(a, b) {
+    const aOrder = policyProviderOrder(a);
+    const bOrder = policyProviderOrder(b);
+    return (a.mode === b.mode &&
+        aOrder.length === bOrder.length &&
+        aOrder.every((provider, index) => provider === bOrder[index]));
+}
+export function buildRoutePlanWithConfigDegradation(request, degradedPolicy) {
+    const first = buildRoutePlan(request);
+    const emptyStagePolicies = new Map();
+    for (const stage of first.plan.stages) {
+        if (stage.candidates.length === 0 &&
+            !policiesEqual(stage.policy, degradedPolicy)) {
+            emptyStagePolicies.set(stage.canonicalModelId, stage.policy);
+        }
+    }
+    if (emptyStagePolicies.size === 0) {
+        return { plan: first.plan, skips: first.skips, degraded: [] };
+    }
+    // Deterministic rebuild: identical inputs except the empty stages' models
+    // now resolve to the degraded default policy. If the default provider is
+    // ALSO unavailable (e.g. no OpenRouter key at all) the rebuilt stage stays
+    // empty and the caller's no-viable-endpoint handling applies unchanged.
+    const second = buildRoutePlan({
+        ...request,
+        policyFor: (model) => emptyStagePolicies.get(model) !== undefined
+            ? degradedPolicy
+            : request.policyFor(model),
+    });
+    const degraded = [...emptyStagePolicies.entries()].map(([model, fromPolicy]) => ({
+        model,
+        fromPolicy,
+        skips: first.skips.filter((skip) => skip.canonicalModelId === model),
+    }));
+    return { plan: second.plan, skips: second.skips, degraded };
+}

package/routing/plan.d.ts

@@ -1,5 +1,5 @@
-import type { CanonicalModelId, ProviderId } from "./canonical-model";
-import type { ProviderPolicy, RoutePolicyVersion } from "./policy";
+import type { CanonicalModelId, ProviderId } from "./canonical-model.js";
+import type { ProviderPolicy, RoutePolicyVersion } from "./policy.js";
 /**
  * Capabilities the planner checks before any network request (LLM Provider
  * Routing PRD §5.1/§5.3). `max_completion_tokens` is modeled as a capability

package/routing/planner.d.ts

@@ -1,7 +1,7 @@
-import type { CanonicalModelId, ProviderId } from "./canonical-model";
-import { type ProviderPolicy } from "./policy";
-import type { InferenceRequirements, RoutePlan, RouteSkip } from "./plan";
-import type { PlannerTransport } from "./transport";
+import type { CanonicalModelId, ProviderId } from "./canonical-model.js";
+import { type ProviderPolicy } from "./policy.js";
+import type { InferenceRequirements, RoutePlan, RouteSkip } from "./plan.js";
+import type { PlannerTransport } from "./transport.js";
 export interface RoutePlanRequest {
     readonly primaryModel: CanonicalModelId;
     /** A distinct fallback canonical model, or null. Equal to primary is ignored. */

package/routing/planner.js

@@ -1,4 +1,4 @@
-import { ROUTE_POLICY_VERSION, policyProviderOrder, } from "./policy";
+import { ROUTE_POLICY_VERSION, policyProviderOrder, } from "./policy.js";
 /**
  * Deterministically expand a canonical primary/fallback selection into an
  * immutable, ordered route plan (LLM Provider Routing PRD §5.1). The only

package/routing/policy.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type CanonicalModelId, type ProviderId } from "./canonical-model";
+import { type CanonicalModelId, type ProviderId } from "./canonical-model.js";
 /**
  * Policy order and semantics are versioned; the version string travels into
  * telemetry (LLM Provider Routing PRD §4.2) so a routing-behavior change is

package/routing/policy.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model";
+import { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model.js";
 /**
  * Policy order and semantics are versioned; the version string travels into
  * telemetry (LLM Provider Routing PRD §4.2) so a routing-behavior change is

package/routing/transport.d.ts

@@ -1,5 +1,5 @@
-import type { CanonicalModelId, ProviderId } from "./canonical-model";
-import type { InferenceRequirements, RouteCandidate, RouteSkip } from "./plan";
+import type { CanonicalModelId, ProviderId } from "./canonical-model.js";
+import type { InferenceRequirements, RouteCandidate, RouteSkip } from "./plan.js";
 export type TransportAvailability = Readonly<{
     available: true;
 }> | Readonly<{

package/run/harness.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Cross-cutting run mechanics for an agent loop:
+ *
+ *   1. a **wall-clock deadline** that aborts a hung run (thread its signal into
+ *      every model and tool call, and re-check at the top of each iteration);
+ *   2. a **coalesced progress heartbeat** for hosts that record liveness;
+ *   3. a **failure classifier** mapping a thrown run to a terminal status
+ *      (`timed_out` vs `failed`).
+ *
+ * Any driver of the loop needs all three, and reimplementing them per driver
+ * is how one ends up unbounded: a loop whose abort signal never fires holds its
+ * worker slot until an external reaper notices, which is a stall the user sees
+ * as an agent that never answers.
+ *
+ * This module owns no persistence and makes no model calls — it is pure
+ * mechanics, so a small consumer can use it without pulling in a loop's
+ * transitive graph.
+ */
+/** Thrown by {@link RunDeadline.throwIfTimedOut} once the wall-clock budget is
+ *  exhausted. Distinct from a caller-driven cancellation so callers can map it
+ *  to a `timed_out` terminal status (or simply read {@link RunDeadline.timedOut}). */
+export declare class RunTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, label: string);
+}
+/**
+ * Call `unref()` on a timer when the runtime exposes it (Node/Bun) so a
+ * forgotten clear can't hold the event loop open; a no-op under the DOM `number`
+ * timer type. Feature-detected rather than `as`-cast to keep type safety.
+ */
+export declare function unrefTimer(timer: ReturnType<typeof setTimeout>): void;
+/**
+ * A wall-clock budget for a single run. Backed by an `AbortController` that
+ * fires after `timeoutMs`; `signal` is threaded into LLM/tool calls so an
+ * in-flight upstream request is actually torn down on timeout (not merely
+ * abandoned). `timedOut` reflects *this* deadline firing only — it stays false
+ * when a combined external (cancellation) signal aborts — so it is a reliable
+ * basis for classifying a `timed_out` outcome regardless of which error shape
+ * surfaced (a `RunTimeoutError` from {@link throwIfTimedOut} or an `AbortError`
+ * from a torn-down `callLLM` stream).
+ */
+export interface RunDeadline {
+    /** The deadline's own abort signal. Combine with a cancellation signal via
+     *  {@link withExternal} before handing to `callLLM`. */
+    readonly signal: AbortSignal;
+    /** True once this deadline's timer has fired. Unaffected by external signals. */
+    readonly timedOut: boolean;
+    /** Throw {@link RunTimeoutError} if the budget is exhausted; no-op otherwise.
+     *  Call at the top of each loop iteration. */
+    throwIfTimedOut(): void;
+    /** Combine this deadline with an optional external signal (e.g. a DB-backed
+     *  cancellation controller). Returns the deadline's own signal when no
+     *  external signal is given. */
+    withExternal(external?: AbortSignal | null): AbortSignal;
+    /** Clear the underlying timer. Idempotent; call in a `finally`. */
+    dispose(): void;
+}
+export declare function createRunDeadline(opts: {
+    timeoutMs: number;
+    label?: string;
+}): RunDeadline;
+/**
+ * Classify a run that ended by throwing into its terminal status. A run whose
+ * deadline fired — or whose error is a {@link RunTimeoutError} — is `timed_out`;
+ * anything else is `failed`. Checking the error too makes the result robust to
+ * the surfaced shape (an `AbortError` from a torn-down stream leaves
+ * `deadline.timedOut` true; a `RunTimeoutError` thrown between iterations is
+ * caught directly even if a combined-signal edge left `timedOut` unread).
+ *
+ * Caller-driven cancellation is a distinct outcome and must be handled *before*
+ * calling this (the executor special-cases `AgentRunCancelledError`); the
+ * one-off/onboarding path has no cancellation, so this split is complete there.
+ */
+export declare function classifyRunFailure(deadline: RunDeadline, error?: unknown): "timed_out" | "failed";
+/** A progress heartbeat that collapses bursts of calls into at most one flush
+ *  per `coalesceMs` window (a `force` beat always flushes). */
+export interface CoalescedHeartbeat {
+    beat(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Build a coalesced heartbeat. A run with N concurrent tool calls would
+ * otherwise fire N near-simultaneous run-row UPDATEs; coalescing collapses
+ * them to one per window while a `force: true` beat (used at the end of each
+ * iteration) guarantees a bump within the reaper's stale threshold. `flush`
+ * owns the actual write; a flush failure is reported to `onError` and
+ * swallowed so a transient DB hiccup never aborts the run.
+ */
+export declare function createCoalescedHeartbeat(opts: {
+    coalesceMs: number;
+    flush: () => Promise<void>;
+    onError?: (err: unknown) => void;
+}): CoalescedHeartbeat;

package/run/harness.js

@@ -0,0 +1,140 @@
+/**
+ * Cross-cutting run mechanics for an agent loop:
+ *
+ *   1. a **wall-clock deadline** that aborts a hung run (thread its signal into
+ *      every model and tool call, and re-check at the top of each iteration);
+ *   2. a **coalesced progress heartbeat** for hosts that record liveness;
+ *   3. a **failure classifier** mapping a thrown run to a terminal status
+ *      (`timed_out` vs `failed`).
+ *
+ * Any driver of the loop needs all three, and reimplementing them per driver
+ * is how one ends up unbounded: a loop whose abort signal never fires holds its
+ * worker slot until an external reaper notices, which is a stall the user sees
+ * as an agent that never answers.
+ *
+ * This module owns no persistence and makes no model calls — it is pure
+ * mechanics, so a small consumer can use it without pulling in a loop's
+ * transitive graph.
+ */
+/** Thrown by {@link RunDeadline.throwIfTimedOut} once the wall-clock budget is
+ *  exhausted. Distinct from a caller-driven cancellation so callers can map it
+ *  to a `timed_out` terminal status (or simply read {@link RunDeadline.timedOut}). */
+export class RunTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, label) {
+        super(`${label} exceeded ${formatDuration(timeoutMs)} timeout`);
+        this.timeoutMs = timeoutMs;
+        this.name = "RunTimeoutError";
+    }
+}
+function formatDuration(ms) {
+    if (ms % 60_000 === 0) {
+        const m = ms / 60_000;
+        return `${m} ${m === 1 ? "minute" : "minutes"}`;
+    }
+    // Floor at 1 so a sub-second budget (e.g. a 50ms test deadline) never reads
+    // "0 seconds".
+    const s = Math.max(1, Math.round(ms / 1000));
+    return `${s} ${s === 1 ? "second" : "seconds"}`;
+}
+/**
+ * Call `unref()` on a timer when the runtime exposes it (Node/Bun) so a
+ * forgotten clear can't hold the event loop open; a no-op under the DOM `number`
+ * timer type. Feature-detected rather than `as`-cast to keep type safety.
+ */
+export function unrefTimer(timer) {
+    if (typeof timer === "object" &&
+        timer !== null &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+export function createRunDeadline(opts) {
+    const label = opts.label ?? "agent run";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    // Unref so a forgotten dispose() (e.g. in a test) can't hold the event loop
+    // open; the timer is always cleared on the real run path.
+    unrefTimer(timer);
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return controller.signal.aborted;
+        },
+        throwIfTimedOut() {
+            if (controller.signal.aborted) {
+                throw new RunTimeoutError(opts.timeoutMs, label);
+            }
+        },
+        withExternal(external) {
+            if (!external)
+                return controller.signal;
+            return AbortSignal.any([external, controller.signal]);
+        },
+        dispose() {
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * Classify a run that ended by throwing into its terminal status. A run whose
+ * deadline fired — or whose error is a {@link RunTimeoutError} — is `timed_out`;
+ * anything else is `failed`. Checking the error too makes the result robust to
+ * the surfaced shape (an `AbortError` from a torn-down stream leaves
+ * `deadline.timedOut` true; a `RunTimeoutError` thrown between iterations is
+ * caught directly even if a combined-signal edge left `timedOut` unread).
+ *
+ * Caller-driven cancellation is a distinct outcome and must be handled *before*
+ * calling this (the executor special-cases `AgentRunCancelledError`); the
+ * one-off/onboarding path has no cancellation, so this split is complete there.
+ */
+export function classifyRunFailure(deadline, error) {
+    if (deadline.timedOut || error instanceof RunTimeoutError)
+        return "timed_out";
+    return "failed";
+}
+/**
+ * Build a coalesced heartbeat. A run with N concurrent tool calls would
+ * otherwise fire N near-simultaneous run-row UPDATEs; coalescing collapses
+ * them to one per window while a `force: true` beat (used at the end of each
+ * iteration) guarantees a bump within the reaper's stale threshold. `flush`
+ * owns the actual write; a flush failure is reported to `onError` and
+ * swallowed so a transient DB hiccup never aborts the run.
+ */
+export function createCoalescedHeartbeat(opts) {
+    let lastAt = 0;
+    let inFlight = null;
+    let queued = false;
+    // Drain queued flushes ONE AT A TIME, so a coalesced background beat and a
+    // forced end-of-iteration beat can never run `flush()` concurrently — two
+    // overlapping DB writes could otherwise resolve out of order and let an older
+    // token/cost snapshot overwrite a newer one. `flush` reads live state at call
+    // time, so each drained flush still writes the latest values, and a request
+    // enqueued during the prior await is picked up on the next loop turn.
+    const drain = async () => {
+        while (queued) {
+            queued = false;
+            try {
+                await opts.flush();
+            }
+            catch (err) {
+                opts.onError?.(err);
+            }
+        }
+        inFlight = null;
+    };
+    return {
+        async beat(o) {
+            const now = Date.now();
+            if (!o?.force && now - lastAt < opts.coalesceMs)
+                return;
+            lastAt = now;
+            queued = true;
+            if (!inFlight)
+                inFlight = drain();
+            // Await the drain so a forced beat returns only after the latest write has
+            // landed — the reaper-liveness / token-flush guarantee callers rely on.
+            await inFlight;
+        },
+    };
+}

package/run/index.d.ts

@@ -0,0 +1,2 @@
+export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
+export { runToolCallsPooledByTool } from "./tool-batch.js";

package/run/index.js

@@ -0,0 +1,2 @@
+export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
+export { runToolCallsPooledByTool } from "./tool-batch.js";

package/run/tool-batch.d.ts

@@ -0,0 +1,16 @@
+import type OpenAI from "openai";
+/**
+ * Run a batch of tool calls concurrently with per-tool-name pooling. Calls
+ * to different tools fan out fully; calls to the *same* tool are capped at
+ * `PER_TOOL_POOL_SIZE` so a batch of many calls to one downstream service does
+ * not overwhelm it. Results are
+ * returned in the same order as `calls`, each as a `PromiseSettledResult`
+ * so the caller can synthesize error tool messages for any rejections
+ * (every `tool_call_id` in the assistant message still needs a response).
+ *
+ * Generic over the per-call outcome: the pooling and ordering policy is
+ * harness-owned, while the shape a host derives from a completed call (which
+ * plugin activated, whether the run should compact, a suspend directive, …)
+ * stays with the host.
+ */
+export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>): Promise<PromiseSettledResult<TOutcome>[]>;

package/run/tool-batch.js

@@ -0,0 +1,83 @@
+// Per-tool concurrency ceiling inside a single LLM tool-call batch. A model
+// response can request many calls to the same tool; running them all at once
+// would hammer whatever it talks to (a search backend, a database, a
+// third-party API). Calls to *different* tools still fan out fully — the cap
+// is applied per tool name, not globally.
+const PER_TOOL_POOL_SIZE = 5;
+/**
+ * The name a batch pools on. `function` and `custom` tool calls both carry a
+ * name, on different fields; anything the wire union grows later falls back to
+ * its type, which pools all such calls together rather than guessing.
+ */
+function poolKey(call) {
+    switch (call.type) {
+        case "function":
+            return call.function.name;
+        case "custom":
+            return `__custom__:${call.custom.name}`;
+        default: {
+            // Not `never`: this union is a third party's, and a new member must not
+            // become a type error in a consumer that never sees one.
+            const unknownCall = call;
+            return `__${unknownCall.type ?? "unknown"}__`;
+        }
+    }
+}
+/**
+ * Run a batch of tool calls concurrently with per-tool-name pooling. Calls
+ * to different tools fan out fully; calls to the *same* tool are capped at
+ * `PER_TOOL_POOL_SIZE` so a batch of many calls to one downstream service does
+ * not overwhelm it. Results are
+ * returned in the same order as `calls`, each as a `PromiseSettledResult`
+ * so the caller can synthesize error tool messages for any rejections
+ * (every `tool_call_id` in the assistant message still needs a response).
+ *
+ * Generic over the per-call outcome: the pooling and ordering policy is
+ * harness-owned, while the shape a host derives from a completed call (which
+ * plugin activated, whether the run should compact, a suspend directive, …)
+ * stays with the host.
+ */
+export async function runToolCallsPooledByTool(calls, run) {
+    if (calls.length === 0)
+        return [];
+    const results = new Array(calls.length);
+    const groups = new Map();
+    for (let i = 0; i < calls.length; i++) {
+        const tc = calls[i];
+        // Pool key is the tool name, wherever the wire union puts it — `custom`
+        // tool calls carry theirs on a different field, and pooling every one of
+        // them together would serialize unrelated tools behind each other. A future
+        // variant with no name at all falls back to its type; the `__` fencing
+        // keeps either synthetic key from colliding with a real tool name.
+        const key = poolKey(tc);
+        let arr = groups.get(key);
+        if (!arr) {
+            arr = [];
+            groups.set(key, arr);
+        }
+        arr.push(i);
+    }
+    await Promise.all(Array.from(groups.values()).map(async (indices) => {
+        // `cursor++` in single-threaded JS is atomic between awaits — no lock
+        // needed. Workers race for the next index; when cursor exceeds the
+        // group size the worker returns.
+        let cursor = 0;
+        const workerCount = Math.min(PER_TOOL_POOL_SIZE, indices.length);
+        await Promise.all(Array.from({ length: workerCount }, async () => {
+            while (true) {
+                const pos = cursor++;
+                if (pos >= indices.length)
+                    return;
+                const callIdx = indices[pos];
+                try {
+                    const value = await run(calls[callIdx]);
+                    results[callIdx] = { status: "fulfilled", value };
+                }
+                catch (reason) {
+                    results[callIdx] = { status: "rejected", reason };
+                }
+            }
+        }));
+    }));
+    return results;
+}

package/tools/index.d.ts

@@ -0,0 +1 @@
+export { sanitizeToolSchema } from "./sanitize-schema.js";

package/tools/index.js

@@ -0,0 +1 @@
+export { sanitizeToolSchema } from "./sanitize-schema.js";