@juno-ai/bind 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juno AI Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# bind
+
+**`@juno-ai/bind` — an agent harness.**
+
+The agent loop is a bind chain: each turn sequences a model completion into
+tool effects into the next turn's context. `bind` is the harness that runs
+that chain — the runtime-agnostic core of a production agent loop, extracted
+from [Monad](https://onmonad.ai).
+
+## Status
+
+Early. The package currently ships the **deterministic LLM provider-routing
+core**; the turn kernel, tool/skill contracts, and the `runAgent` /
+`advanceTurn` drivers are being extracted next. Expect breaking changes in
+any release.
+
+**Versioning is not semver.** Each published release increments the major and
+resets the rest — `1.0.0`, `2.0.0`, `3.0.0` — so the major is a release
+counter, not a compatibility signal, and a bump does not by itself mean the
+surface changed. Pin an exact version and read the changes between releases
+until this stabilizes.
+
+## What's here today: provider routing
+
+Expand one canonical model selection (OpenRouter-style `vendor/model-slug`
+ids) into an ordered, immutable, secret-free **route plan** across providers,
+then drive attempts over it with a normative failure policy:
+
+- **`ProviderPolicy`** — ordered provider preference per model, or a hard
+  `only` fence that pins a model to a single provider (useful for evals and
+  compliance).
+- **`buildRoutePlan`** — deterministic planner: policy order is the only
+  ordering input; capability mismatches and configuration gaps become
+  recorded skips, never network attempts.
+- **`executeRoutePlan`** — the attempt loop: model stage → provider candidate
+  → bounded same-endpoint retries, with an exhaustive failure-disposition
+  matrix (`failureDisposition`) deciding retry / next-provider /
+  fallback-model / propagate.
+- **Circuit breaker** — per `(provider, invocation model, credential source)`
+  endpoint, with half-open probes, bounded Retry-After cooldowns, and an
+  injectable clock.
+
+Transports (the actual HTTP clients), credentials, pricing policy, and
+persistence stay with the host application — the harness never reads the
+environment, never touches a filesystem, and holds no secrets, which is what
+keeps it portable across Bun, Node, and edge runtimes such as Cloudflare
+workerd.
+
+```ts
+import {
+  buildRoutePlan,
+  executeRoutePlan,
+  createCircuitBreaker,
+  canonicalModelIdSchema,
+} from "@juno-ai/bind/routing";
+
+const { plan, skips } = buildRoutePlan({
+  primaryModel: canonicalModelIdSchema.parse("openai/gpt-example"),
+  fallbackModel: null,
+  requirements: { capabilities: new Set(["chat_completions", "streaming"]), requestedMaxCompletionTokens: null },
+  policyFor: (model) => resolveMyPolicy(model),
+  transports: myTransportMap, // availability + endpoint resolution per provider
+});
+
+const result = await executeRoutePlan({
+  plan,
+  breaker: createCircuitBreaker(),
+  attempt: async (candidate, cursor) => myTransportAttempt(candidate, cursor),
+});
+```
+
+## Design rules
+
+- **Pure by construction.** No `process`, no Node builtins, no framework
+  imports, no I/O except through injected functions. Enforced by lint in the
+  source-of-truth repository.
+- **Deterministic.** Identical inputs produce identical plans; nothing about
+  registration order, map iteration, or wall-clock time reorders candidates.
+- **Explicit failure policy.** Every classified failure maps through one
+  exhaustive disposition table; transports classify facts, they never decide
+  route order.
+- **zod is a peer dependency** — bring your own instance (v4+).
+
+## Development
+
+This repository is a read-only **archive mirror** of the `packages/bind`
+workspace in Monad's canonical repository, exported via Copybara. npm
+releases of `@juno-ai/bind` are published from the canonical repository, not
+from here — the manifest here stays `"private": true` so it cannot be
+published by accident, though the version it carries is the one the matching
+npm release has. Issues are welcome here; code changes land in the canonical
+repo and flow out with the next export.
+
+Run the tests with [Bun](https://bun.sh):
+
+```sh
+bun test
+```
+
+## License
+
+[MIT](./LICENSE)

package/contracts/index.d.ts

@@ -0,0 +1 @@
+export { emptyRunStats, accumulateTurn, accumulateToolCall, type TranscriptMessage, type AssistantTurnMessage, type WireToolDefinition, type WireToolCall, type TurnTimings, type TurnUsage, type ModelTurnResult, type TurnFn, type StopReason, type RunStats, } from "./turn";

package/contracts/index.js

@@ -0,0 +1 @@
+export { emptyRunStats, accumulateTurn, accumulateToolCall, } from "./turn";

package/contracts/turn.d.ts

@@ -0,0 +1,79 @@
+import type OpenAI from "openai";
+/**
+ * Turn vocabulary — the shared language between the turn kernel (arriving in
+ * a later extraction phase), LLM transports, and hosts.
+ *
+ * The declared wire format is the OpenAI chat-completions message shape,
+ * consumed as **types only** (`openai` is a peer used purely for its type
+ * declarations here; no runtime import). Hosts on other client stacks (e.g.
+ * the Vercel AI SDK) adapt at the turn-function boundary.
+ *
+ * NOTE: `ToolPlugin` / tool-context contracts deliberately do NOT live here
+ * yet — they are being reshaped by the single-agent consolidation work in
+ * the host repo and move here once that lands.
+ */
+export type TranscriptMessage = OpenAI.ChatCompletionMessageParam;
+export type AssistantTurnMessage = OpenAI.ChatCompletionMessage;
+export type WireToolDefinition = OpenAI.ChatCompletionTool;
+export type WireToolCall = OpenAI.ChatCompletionMessageToolCall;
+/**
+ * Per-turn latency/throughput measurements. Field shapes deliberately match
+ * the metrics the AA/StirrupJS harness reports (`speedStats`) so numbers are
+ * directly comparable with published benchmark methodology:
+ * time-to-first-token, generation wall time, and output tokens/second —
+ * plus the model-time vs tool-time split that per-task wall-clock hides.
+ */
+export interface TurnTimings {
+    /** ms from request start to the first streamed token, if streaming. */
+    readonly ttftMs: number | null;
+    /** ms from request start to the completed response. */
+    readonly generationMs: number;
+}
+export interface TurnUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Provider-reported cached input tokens, when available. */
+    readonly cachedInputTokens: number | null;
+    /** Billing-basis cost in USD cents, when the transport can report it. */
+    readonly costCents: number | null;
+}
+/** One model completion's message + usage + timings. */
+export interface ModelTurnResult {
+    readonly message: AssistantTurnMessage;
+    readonly usage: TurnUsage;
+    readonly timings: TurnTimings;
+}
+/**
+ * The turn function — the seam between the loop and any LLM client. The
+ * kernel never imports an LLM client; it calls this. Implementations own
+ * retries, provider routing, and streaming internally and return one
+ * completed assistant turn.
+ */
+export type TurnFn = (messages: readonly TranscriptMessage[], tools: readonly WireToolDefinition[] | undefined, signal: AbortSignal | undefined) => Promise<ModelTurnResult>;
+/** Why a run stopped. `suspended` = a tool intentionally paused the run. */
+export type StopReason = "done" | "suspended" | "iteration_limit" | "deadline" | "aborted";
+/**
+ * Cumulative run accounting: model-time and tool-time reported separately —
+ * task wall-clock conflates provider inference speed with tool execution,
+ * and consumers comparing models need the model's contribution isolated.
+ */
+export interface RunStats {
+    readonly turns: number;
+    readonly toolCalls: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costCents: number;
+    /** Sum of model `generationMs` across turns. */
+    readonly modelTimeMs: number;
+    /** Sum of tool execution durations across dispatched calls. */
+    readonly toolTimeMs: number;
+    /** Output tokens per second of model time, null before any output. */
+    readonly outputTokensPerSecond: number | null;
+    /** Per-tool total execution ms, keyed by tool name. */
+    readonly toolTimeBreakdownMs: Readonly<Record<string, number>>;
+}
+export declare function emptyRunStats(): RunStats;
+/** Fold one completed model turn into cumulative run stats. */
+export declare function accumulateTurn(stats: RunStats, turn: ModelTurnResult): RunStats;
+/** Fold one dispatched tool call's duration into cumulative run stats. */
+export declare function accumulateToolCall(stats: RunStats, toolName: string, durationMs: number): RunStats;

package/contracts/turn.js

@@ -0,0 +1,39 @@
+export function emptyRunStats() {
+    return {
+        turns: 0,
+        toolCalls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costCents: 0,
+        modelTimeMs: 0,
+        toolTimeMs: 0,
+        outputTokensPerSecond: null,
+        toolTimeBreakdownMs: {},
+    };
+}
+/** Fold one completed model turn into cumulative run stats. */
+export function accumulateTurn(stats, turn) {
+    const outputTokens = stats.outputTokens + turn.usage.outputTokens;
+    const modelTimeMs = stats.modelTimeMs + turn.timings.generationMs;
+    return {
+        ...stats,
+        turns: stats.turns + 1,
+        inputTokens: stats.inputTokens + turn.usage.inputTokens,
+        outputTokens,
+        costCents: stats.costCents + (turn.usage.costCents ?? 0),
+        modelTimeMs,
+        outputTokensPerSecond: modelTimeMs > 0 ? (outputTokens / modelTimeMs) * 1000 : null,
+    };
+}
+/** Fold one dispatched tool call's duration into cumulative run stats. */
+export function accumulateToolCall(stats, toolName, durationMs) {
+    return {
+        ...stats,
+        toolCalls: stats.toolCalls + 1,
+        toolTimeMs: stats.toolTimeMs + durationMs,
+        toolTimeBreakdownMs: {
+            ...stats.toolTimeBreakdownMs,
+            [toolName]: (stats.toolTimeBreakdownMs[toolName] ?? 0) + durationMs,
+        },
+    };
+}

package/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @juno-ai/bind — the agent harness.
+ *
+ * Why "bind": the agent loop is a bind chain — each turn sequences a model
+ * completion into tool effects into the next turn's context. This package is
+ * the harness that runs that chain.
+ *
+ * Current surface: the deterministic LLM provider-routing core (see
+ * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
+ * contracts move here in later extraction phases.
+ */
+export * from "./routing/index";
+export * from "./contracts/index";

package/index.js

@@ -0,0 +1,13 @@
+/**
+ * @juno-ai/bind — the agent harness.
+ *
+ * Why "bind": the agent loop is a bind chain — each turn sequences a model
+ * completion into tool effects into the next turn's context. This package is
+ * the harness that runs that chain.
+ *
+ * Current surface: the deterministic LLM provider-routing core (see
+ * `docs/bind.md` and the LLM Provider Routing PRD). The turn kernel and tool
+ * contracts move here in later extraction phases.
+ */
+export * from "./routing/index";
+export * from "./contracts/index";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@juno-ai/bind",
+  "version": "1.0.0",
+  "description": "Agent harness: deterministic LLM provider routing core and turn contracts (turn kernel arrives in later phases). MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./routing": {
+      "types": "./routing/index.d.ts",
+      "import": "./routing/index.js"
+    },
+    "./contracts": {
+      "types": "./contracts/index.d.ts",
+      "import": "./contracts/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "openai": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juno-ai-labs/agent-harness.git"
+  },
+  "keywords": [
+    "agent",
+    "harness",
+    "agent-loop",
+    "llm",
+    "routing"
+  ]
+}

package/routing/canonical-model.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Canonical model identity is the OpenRouter-style `vendor/model-slug` id
+ * (LLM Provider Routing PRD §4.1). Provider invocation ids (e.g. an Azure
+ * deployment name) are a separate concept and must never be parsed with this
+ * schema — the regex rejects them because they carry no `/` segment.
+ */
+export declare const canonicalModelIdSchema: z.core.$ZodBranded<z.ZodString, "CanonicalModelId", "out">;
+export type CanonicalModelId = z.infer<typeof canonicalModelIdSchema>;
+/**
+ * Provider ids are lower-case slugs (`openrouter`, `azure`, …). The harness
+ * is generic over the set of providers; the host narrows it by which
+ * transports it registers. Policy validation rejects ids that name no
+ * registered transport at plan time, not here.
+ */
+export declare const providerIdSchema: z.core.$ZodBranded<z.ZodString, "ProviderId", "out">;
+export type ProviderId = z.infer<typeof providerIdSchema>;

package/routing/canonical-model.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/**
+ * Canonical model identity is the OpenRouter-style `vendor/model-slug` id
+ * (LLM Provider Routing PRD §4.1). Provider invocation ids (e.g. an Azure
+ * deployment name) are a separate concept and must never be parsed with this
+ * schema — the regex rejects them because they carry no `/` segment.
+ */
+export const canonicalModelIdSchema = z
+    .string()
+    .trim()
+    .regex(/^[^/\s]+\/[^/\s]+$/, "expected an OpenRouter-style vendor/model id")
+    .brand("CanonicalModelId");
+/**
+ * Provider ids are lower-case slugs (`openrouter`, `azure`, …). The harness
+ * is generic over the set of providers; the host narrows it by which
+ * transports it registers. Policy validation rejects ids that name no
+ * registered transport at plan time, not here.
+ */
+export const providerIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]*$/, "provider ids are lower-case slugs")
+    .brand("ProviderId");

package/routing/circuit-breaker.d.ts

@@ -0,0 +1,67 @@
+import type { ProviderId } from "./canonical-model";
+import type { CredentialSource } from "./plan";
+/**
+ * Circuit-breaker state is keyed by (provider, invocation model, credential
+ * source) — LLM Provider Routing PRD §7.2. State is process-local in v1;
+ * deterministic routing and provider telemetry make replica differences
+ * observable.
+ */
+export interface BreakerKey {
+    readonly providerId: ProviderId;
+    readonly invocationModel: string;
+    readonly credentialSource: CredentialSource;
+    /**
+     * Optional non-secret credential identity (e.g. an opaque per-tenant tag)
+     * that further scopes the endpoint state. Without it, one tenant's revoked
+     * BYOK key would open the circuit for every tenant whose calls share
+     * `credentialSource: "tenant"` on this process. Never put key material here
+     * — the value lands in breaker state keys.
+     */
+    readonly credentialScope?: string;
+}
+export interface CircuitBreakerOptions {
+    /** Consecutive fallbackable failures before the circuit opens. Default 3. */
+    readonly failureThreshold?: number;
+    /** Default cooldown once open, in ms. Default 60_000. */
+    readonly cooldownMs?: number;
+    /** Upper bound on any cooldown, including Retry-After extensions. Default 60_000. */
+    readonly maxCooldownMs?: number;
+    /** Injectable clock for tests. Defaults to Date.now. */
+    readonly now?: () => number;
+}
+export type EndpointAdmission = Readonly<{
+    admitted: true;
+    halfOpenProbe: boolean;
+}> | Readonly<{
+    admitted: false;
+    retryAtMs: number;
+}>;
+export interface RecordFailureOptions {
+    /**
+     * Open immediately regardless of the consecutive count — used for
+     * credential/credit failures, which repeated requests cannot repair.
+     */
+    readonly openImmediately?: boolean;
+    /** Bounded Retry-After hint; extends the cooldown up to `maxCooldownMs`. */
+    readonly retryAfterMs?: number | null;
+}
+export interface RouteCircuitBreaker {
+    /**
+     * Ask to attempt an endpoint. Closed circuits admit; open circuits refuse
+     * until cooldown elapses; after cooldown exactly one caller is admitted as
+     * a half-open probe while others keep being refused until the probe
+     * resolves via `recordSuccess`/`recordFailure`.
+     */
+    admit(key: BreakerKey): EndpointAdmission;
+    recordSuccess(key: BreakerKey): void;
+    recordFailure(key: BreakerKey, options?: RecordFailureOptions): void;
+    /**
+     * Resolve a half-open probe that ended without a success or a
+     * breaker-recordable failure (an abort, a propagated client error). The
+     * probe slot is freed and the cooldown re-armed, so the next admit after
+     * cooldown runs a fresh probe instead of refusing forever. No-op when no
+     * probe is in flight.
+     */
+    releaseProbe(key: BreakerKey): void;
+}
+export declare function createCircuitBreaker(options?: CircuitBreakerOptions): RouteCircuitBreaker;

package/routing/circuit-breaker.js

@@ -0,0 +1,75 @@
+function keyString(key) {
+    return `${key.providerId} ${key.invocationModel} ${key.credentialSource} ${key.credentialScope ?? ""}`;
+}
+export function createCircuitBreaker(options = {}) {
+    const failureThreshold = options.failureThreshold ?? 3;
+    const cooldownMs = options.cooldownMs ?? 60_000;
+    const maxCooldownMs = options.maxCooldownMs ?? 60_000;
+    const now = options.now ?? (() => Date.now());
+    const states = new Map();
+    function stateFor(key) {
+        const k = keyString(key);
+        const existing = states.get(k);
+        if (existing !== undefined)
+            return existing;
+        const created = {
+            consecutiveFailures: 0,
+            openUntilMs: 0,
+            probeInFlight: false,
+        };
+        states.set(k, created);
+        return created;
+    }
+    function open(state, retryAfterMs) {
+        const extension = Math.max(cooldownMs, retryAfterMs ?? 0);
+        state.openUntilMs = now() + Math.min(extension, maxCooldownMs);
+        state.probeInFlight = false;
+    }
+    return {
+        admit(key) {
+            // No stored state = healthy endpoint. Don't allocate on the happy
+            // path: keys include an unbounded per-tenant scope, and inserting on
+            // every admit would grow the map monotonically for the process
+            // lifetime (three reviewers independently flagged the leak).
+            const existing = states.get(keyString(key));
+            if (existing === undefined)
+                return { admitted: true, halfOpenProbe: false };
+            const state = existing;
+            if (state.openUntilMs === 0)
+                return { admitted: true, halfOpenProbe: false };
+            const at = now();
+            if (at < state.openUntilMs)
+                return { admitted: false, retryAtMs: state.openUntilMs };
+            // Probe in flight past cooldown: the stored deadline is already in the
+            // past, so report "try again now-ish" rather than a stale timestamp.
+            if (state.probeInFlight) {
+                return { admitted: false, retryAtMs: Math.max(state.openUntilMs, at) };
+            }
+            state.probeInFlight = true;
+            return { admitted: true, halfOpenProbe: true };
+        },
+        recordSuccess(key) {
+            // A clean endpoint needs no state — drop the entry so the map only
+            // ever holds currently-failing/cooling endpoints.
+            states.delete(keyString(key));
+        },
+        recordFailure(key, failureOptions = {}) {
+            const state = stateFor(key);
+            state.consecutiveFailures += 1;
+            const shouldOpen = failureOptions.openImmediately === true ||
+                state.consecutiveFailures >= failureThreshold ||
+                // A failed half-open probe reopens regardless of the counter.
+                state.probeInFlight;
+            if (shouldOpen)
+                open(state, failureOptions.retryAfterMs);
+        },
+        releaseProbe(key) {
+            const state = stateFor(key);
+            if (!state.probeInFlight)
+                return;
+            // Re-arm the cooldown rather than closing: the probe told us nothing,
+            // and immediately admitting another caller would thrash the endpoint.
+            open(state, null);
+        },
+    };
+}

package/routing/errors.d.ts

@@ -0,0 +1,95 @@
+import type { CanonicalModelId, ProviderId } from "./canonical-model";
+/**
+ * The normative attempt-order cursor (LLM Provider Routing PRD §5.2):
+ * structured-output attempt → model stage → provider candidate → same-endpoint
+ * retry. No other ordering input exists.
+ */
+export interface RouteAttemptCursor {
+    /** 0 for the first result; 1..3 for structured-output parse retries. */
+    readonly structuredOutputAttempt: number;
+    /** Primary stage first, then the optional fallback-model stage. */
+    readonly stageIndex: number;
+    /** Provider order inside `RouteStage.candidates`. */
+    readonly candidateIndex: number;
+    /** 0 for the first request; 1..N for same-endpoint completion-defect retries. */
+    readonly endpointAttempt: number;
+}
+export interface AttemptTarget {
+    readonly cursor: RouteAttemptCursor;
+    readonly providerId: ProviderId;
+    readonly canonicalModelId: CanonicalModelId;
+    readonly providerInvocationModel: string;
+    readonly durationMs: number;
+}
+export type HttpFailureCategory = "timeout" | "rate_limit" | "server_error" | "credential" | "credits" | "provider_bad_request" | "client_error";
+/**
+ * Classified attempt failures (PRD §7.1). Transports classify facts; they do
+ * not decide route order — `failureDisposition` is the single ordering
+ * authority. `cause` stays in memory for logging/chaining and is never
+ * serialized into persistence.
+ */
+export type InferenceAttemptError = Readonly<{
+    kind: "aborted";
+    target: AttemptTarget;
+    cause: Error;
+}> | Readonly<{
+    kind: "completion_defect";
+    defect: "empty_completion" | "truncated_tool_call";
+    target: AttemptTarget;
+    cause: Error;
+}> | Readonly<{
+    kind: "network";
+    target: AttemptTarget;
+    cause: Error;
+}> | Readonly<{
+    kind: "http";
+    category: HttpFailureCategory;
+    statusCode: number;
+    retryAfterMs: number | null;
+    target: AttemptTarget;
+    cause: Error;
+}>;
+export type BreakerEffect = "none" | "record_failure" | "open_immediately";
+/**
+ * What the executor may do after a classified failure. All fields are
+ * required — this is a flags record, not an options bag — so the disposition
+ * matrix in the PRD (§7.1) is total and testable.
+ */
+export interface FailureDisposition {
+    /** Eligible for the same-endpoint completion-defect retry budget. */
+    readonly sameEndpointRetry: boolean;
+    /** May traverse to the next provider candidate for the same model. */
+    readonly nextProvider: boolean;
+    /** May traverse into the fallback-model stage. */
+    readonly fallbackModel: boolean;
+    readonly breaker: BreakerEffect;
+    /** Return to the caller immediately; no further traversal. */
+    readonly propagate: boolean;
+}
+/**
+ * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
+ * executor applies it, the circuit breaker consumes its `breaker` effect.
+ */
+export declare function failureDisposition(error: InferenceAttemptError): FailureDisposition;
+/**
+ * Default HTTP status → category mapping. A transport may override per
+ * provider (e.g. OpenRouter reports credit exhaustion as 402; another
+ * provider may use 403 with a body marker) — this is only the neutral
+ * baseline.
+ */
+export declare function categorizeHttpStatus(statusCode: number): HttpFailureCategory;
+/**
+ * Whether a FRESH ATTEMPT LATER could plausibly succeed — the caller-facing
+ * "retriable" used to pick the most useful error when a whole plan fails
+ * (PRD §5.2 step 6: prefer a retriable primary-path error over a
+ * non-retriable stale fallback binding, so the host's queue-level retry
+ * still fires).
+ *
+ * Deliberately NOT the same notion as route-traversal eligibility: a
+ * provider-specific 400 traverses to the next provider (a different provider
+ * may accept the request shape — `failureDisposition`), but retrying the
+ * same exhausted plan later won't fix it, so it is not caller-retriable.
+ * Credential/credit failures likewise traverse but need operator action, not
+ * time.
+ */
+export declare function isRetriableAttemptError(error: InferenceAttemptError): boolean;