@juno-ai/bind 4.0.0 → 5.0.0

package/README.md

@@ -104,7 +104,7 @@ losing it.
 
 ### What stays with your application
 
-Transports' request construction and wire-error classification, credentials and
+Transports' request construction and your own error classes, credentials and
 environment parsing, your routing policy configuration, billing accounting
 (persistence and charging), inference logging, authorization, prompt rendering,
 and run orchestration — the queue a run is scheduled on, and the enqueuing and
@@ -379,6 +379,91 @@ should mint its own, so a turn is never unbounded. Handle caller-driven
 cancellation *before* calling `classifyRunFailure` — a cancellation is not a
 timeout, and `timedOut` stays false when only a combined external signal fires.
 
+### How to stop a stalled stream from hanging forever
+
+Your SDK's `timeout` bounds establishing the request, not the gap between
+streamed chunks. Hand the watchdog's signal to the transport, tell it what each
+chunk carried, and ask it afterwards whether it was the one that tore the stream
+down.
+
+```ts
+import { createStreamWatchdog } from "@juno-ai/bind/completion";
+
+const watchdog = createStreamWatchdog({ external: cancellationSignal });
+try {
+  const stream = await client.chat.completions.create(body, { signal: watchdog.signal });
+  watchdog.open(); // arms the first-token budget and the absolute cap
+
+  for await (const chunk of stream) {
+    const delta = chunk.choices?.[0]?.delta;
+    // Only ANSWER output arms the tight inter-chunk budget. Reasoning deltas —
+    // and the pause between reasoning and the first answer token — must stay on
+    // the generous budget, or a reasoning model's normal think-then-answer gap
+    // fails healthy turns.
+    // Providers disagree on the reasoning field's name, and it is off-spec for
+    // the OpenAI types either way — read both spellings.
+    const reasoning = delta?.reasoning_content ?? delta?.reasoning;
+    watchdog.observedChunk(
+      delta?.content || delta?.refusal || delta?.tool_calls
+        ? "answer"
+        : reasoning
+          ? "reasoning"
+          : "none",
+    );
+    // …accumulate…
+  }
+} catch (error) {
+  const stall = watchdog.stall();
+  if (stall !== null) throw new MyRetriableError(describe(stall)); // your wording
+  throw error; // a caller abort, or a real transport failure
+} finally {
+  watchdog.dispose();
+}
+```
+
+`stall()` returns `null` when your own `external` signal aborted, so a
+cancellation is never reported as a retriable upstream stall. Call it in the
+`catch`, before `dispose()`. Budgets are validated at construction: a `NaN` or
+`Infinity` budget throws rather than silently tearing down every healthy stream
+(`setTimeout` coerces a non-finite delay to ~1ms — it does not disable the
+timer).
+
+### How to map your transport errors onto the routing taxonomy
+
+`failureDisposition` decides what the router does with a classified failure, but
+something has to produce the classification. Give `classifyAttemptError` two
+ports — one that recognizes your error class, one that overrides the neutral
+HTTP mapping where your provider disagrees with it — and it does the rest.
+
+```ts
+import { classifyAttemptError, type AttemptClassification } from "@juno-ai/bind/routing";
+
+const CLASSIFICATION: AttemptClassification = {
+  asTransportFailure: (error) =>
+    error instanceof MyLLMError
+      ? { kind: error.kind, statusCode: error.statusCode, retryAfterMs: error.retryAfterMs }
+      : null,
+  // This gateway answers 403 for moderation-flagged INPUT. The neutral mapping
+  // reads 403 as a credential failure and opens the circuit immediately —
+  // degrading a healthy shared endpoint for every tenant over one prompt.
+  categorizeStatus: (status, providerId) =>
+    status === 403 && providerId === MY_GATEWAY ? "provider_bad_request" : null,
+};
+
+// `target` is the `AttemptTarget` you assemble in your `attempt` callback from
+// the candidate and cursor it was handed — see the tutorial's step 4.
+const attemptError = classifyAttemptError(error, target, CLASSIFICATION);
+```
+
+An `AbortError` is classified first, whatever else is true of it. Anything
+`asTransportFailure` does not recognize becomes a propagating `client_error`: an
+error that escaped your transport without becoming one of its own is a bug, and
+retrying it against every provider and your fallback model arrives at the same
+exception having spent a whole plan. `retryAfterMsFromHeaders` lives alongside
+it and feeds the `retryAfterMs` the breaker uses to extend a cooldown — clamp
+it before using it as a delay anywhere else, since it is a value the upstream
+chose and RFC 9110 puts no ceiling on it.
+
 ### How to stop a run's progress writes from stampeding
 
 ```ts
@@ -522,7 +607,8 @@ keeps a consumer who only wants routing from pulling in the rest.
 
 | Import | Owns | Reach for it when |
 |---|---|---|
-| `@juno-ai/bind/routing` | Route plans, the planner, the failure taxonomy, the plan executor, the circuit breaker, billing-basis arithmetic, config degradation | You call more than one provider or model, or you want retries and fallback governed by one table |
+| `@juno-ai/bind/routing` | Route plans, the planner, the failure taxonomy and the classifier that maps your errors onto it, the plan executor, the circuit breaker, billing-basis arithmetic, config degradation | You call more than one provider or model, or you want retries and fallback governed by one table |
+| `@juno-ai/bind/completion` | Streaming idle watchdog (time-to-first-token, inter-chunk, absolute cap), completion-defect detection, and the structured-output retry predicates | You read a streamed completion |
 | `@juno-ai/bind/contracts` | Turn vocabulary — `TurnFn`, `ModelTurnResult`, `StopReason`, `RunStats` and its folds | You want one seam between your loop and any LLM client, and comparable per-run metrics |
 | `@juno-ai/bind/loop` | `runToolLoop` — the iteration engine: model turn, two-phase tool batch, activation, compaction, interrupts, suspend | You want the agent loop itself, not just the pieces to build one |
 | `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
@@ -785,7 +871,15 @@ transport reports **facts**, the executor decides order.
 //   else if (status === 401) throw;
 //   else tryNextModel();
 
-// After: the transport only classifies.
+// After: the transport only classifies — and `classifyAttemptError` does that
+// for you, so the only thing you write is how to recognize your own error class.
+const CLASSIFICATION: AttemptClassification = {
+  asTransportFailure: (error) =>
+    error instanceof MyLLMError
+      ? { kind: error.kind, statusCode: error.statusCode, retryAfterMs: error.retryAfterMs }
+      : null,
+};
+
 const attempt: AttemptFn<Completion> = async (candidate, cursor) => {
   const startedAt = performance.now();
   try {
@@ -798,27 +892,23 @@ const attempt: AttemptFn<Completion> = async (candidate, cursor) => {
       providerInvocationModel: candidate.providerInvocationModel,
       durationMs: Math.round(performance.now() - startedAt),
     };
-    if (isAbort(cause)) return { kind: "failure", error: { kind: "aborted", target, cause } };
-    if (!cause.status) return { kind: "failure", error: { kind: "network", target, cause } };
-    return {
-      kind: "failure",
-      error: {
-        kind: "http",
-        category: categorizeHttpStatus(cause.status),
-        statusCode: cause.status,
-        retryAfterMs: parseRetryAfter(cause),
-        target,
-        cause,
-      },
-    };
+    return { kind: "failure", error: classifyAttemptError(cause, target, CLASSIFICATION) };
   }
 };
 ```
 
+Do not hand-roll that `catch` from the neutral pieces — mapping statuses
+yourself is where the consequential mistakes live. The neutral mapping reads
+**403 as a credential failure**, which opens the breaker immediately; if your
+gateway also answers 403 for a moderation-flagged *prompt*, that one tenant's
+request takes a healthy endpoint out of rotation for everyone sharing the
+breaker key. Supply a `categorizeStatus` port instead — see
+[How to map your transport errors onto the routing taxonomy](#how-to-map-your-transport-errors-onto-the-routing-taxonomy).
+
 Two behaviours you get for free and probably did not have: a request-shaped
-rejection (a 400, a moderation refusal) traverses to another provider **without**
-opening the breaker, and an empty or truncated completion is retried on the same
-endpoint before any fallback.
+rejection (a 400, a correctly-classified moderation refusal) traverses to
+another provider **without** opening the breaker, and an empty or truncated
+completion is retried on the same endpoint before any fallback.
 
 ### Adapting a non-SDK client to `TurnFn`
 

package/completion/defects.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Transient defects in an assembled completion, and the retry predicates that
+ * decide whether to ask the same endpoint again.
+ *
+ * A completion can come back structurally intact at the transport layer and
+ * still be unusable: the provider cut the stream mid-arguments, or closed it
+ * having emitted nothing at all. Neither is an HTTP failure — there is no
+ * status code to classify — so nothing upstream in the routing taxonomy sees
+ * them. Left undetected they reach the agent loop, where a truncated tool call
+ * is rejected as "invalid JSON in tool arguments" and burns a whole recovery
+ * turn on something a plain retry fixes.
+ *
+ * The two defect kinds here are exactly the two that feed
+ * `InferenceAttemptError`'s `completion_defect` arm, which the disposition
+ * matrix routes to a same-endpoint retry before traversing providers.
+ *
+ * Everything in this module is pure. Types are structural rather than tied to
+ * any SDK's message class, so a host assembling chunks by hand and a host
+ * handing over an `openai` message both fit without a cast.
+ */
+/**
+ * Additional attempts when a structured-output call returns content that will
+ * not parse as JSON: the initial call plus this many retries. Providers
+ * occasionally truncate or malform JSON even under a strict schema, and a fresh
+ * attempt almost always comes back valid.
+ */
+export declare const DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES = 3;
+/**
+ * Same-endpoint retry budget for a transiently-corrupt completion. A fresh
+ * attempt on the SAME endpoint usually recovers an intact response; a
+ * persistently-broken endpoint exhausts these, and the route executor then
+ * traverses to the next provider or model.
+ */
+export declare const DEFAULT_COMPLETION_DEFECT_MAX_RETRIES = 2;
+/** The part of a streamed tool call this module reads. */
+export interface StreamedToolCall {
+    readonly function: {
+        readonly name: string;
+        readonly arguments: string;
+    };
+}
+/**
+ * The outputs of an assembled completion. `tool_calls` is `unknown[]` here
+ * because the checks that only need "did the model call a tool" must accept a
+ * host's full SDK union (which may include non-function tool calls);
+ * {@link detectCompletionDefect} narrows it where it actually reads arguments.
+ */
+export interface CompletionOutputs {
+    readonly content: string | null;
+    readonly refusal?: string | null | undefined;
+    readonly tool_calls?: readonly unknown[] | undefined;
+}
+/** {@link CompletionOutputs} with tool calls narrowed to the readable shape. */
+export interface AssembledCompletion<TToolCall extends StreamedToolCall = StreamedToolCall> extends CompletionOutputs {
+    readonly tool_calls?: readonly TToolCall[] | undefined;
+}
+/**
+ * The defect vocabulary, named once so the routing taxonomy can reference it
+ * rather than re-spelling the same two literals. `InferenceAttemptError`'s
+ * `completion_defect` arm carries exactly these, and a third kind added here
+ * must widen that arm too — which it will, by type error, only because both
+ * sides read this one declaration.
+ */
+export type CompletionDefectKind = "empty_completion" | "truncated_tool_call";
+export type CompletionDefect<TToolCall extends StreamedToolCall = StreamedToolCall> = 
+/** The provider closed the stream having emitted no content, tool call, or refusal. */
+Readonly<{
+    kind: "empty_completion";
+}>
+/** A tool call whose arguments never arrived intact. */
+ | Readonly<{
+    kind: "truncated_tool_call";
+    toolCall: TToolCall;
+}>;
+/** True when `s` parses as JSON. */
+export declare function jsonParses(s: string): boolean;
+/**
+ * Find the transient defect in an assembled completion, or `null` when it is
+ * usable.
+ *
+ * **Empty completion.** No content, no tool calls, no refusal. A refusal alone
+ * is a legitimate output and is not a defect.
+ *
+ * **Truncated tool call.** Non-empty arguments that do not parse as JSON are
+ * always a truncation — the provider cut the stream mid-arguments. *Empty*
+ * arguments are the normal zero-arg shape and are not a defect **unless** the
+ * stream was `cutByTokenLimit`: a length-truncated empty-args call is an
+ * incomplete message, not a deliberate no-arg call, and exempting it would let
+ * a dispatcher execute a tool off a half-streamed turn.
+ *
+ * `cutByTokenLimit` is the *fact*, not the wire spelling of it — OpenAI says
+ * `finish_reason: "length"`, Anthropic says `max_tokens`, Gemini says
+ * `MAX_TOKENS`. Taking the fact keeps the one behavioural rule in this module
+ * from silently reading `false` for every host that isn't on an
+ * OpenAI-compatible gateway, which would apply the zero-arg exemption to
+ * exactly the truncated calls it exists to exclude.
+ *
+ * A tool call whose `arguments` are not a readable string is skipped rather
+ * than inspected: {@link CompletionOutputs.tool_calls} accepts a host's full
+ * SDK union, and a non-function member (OpenAI's `type: "custom"`) has no
+ * arguments to truncate.
+ */
+export declare function detectCompletionDefect<TToolCall extends StreamedToolCall>(completion: AssembledCompletion<TToolCall>, cutByTokenLimit: boolean): CompletionDefect<TToolCall> | null;
+/**
+ * The part of a request's `response_format` that decides whether output is JSON
+ * we can validate by parsing. Structural so any SDK's type fits.
+ *
+ * The two JSON spellings are the OpenAI-compatible wire values. The open
+ * `(string & {})` arm keeps any other value assignable — a gateway with its own
+ * vocabulary is not a type error — while still letting an editor complete the
+ * two that {@link expectsJsonOutput} actually recognizes, so a near-miss like
+ * `"json"` is visible at the call site rather than silently falling through to
+ * "no JSON expected".
+ */
+export interface ResponseFormatShape {
+    readonly type?: "text" | "json_object" | "json_schema" | (string & {}) | undefined;
+}
+/**
+ * True when `response_format` asks the model for JSON. Free-form output
+ * (`text`, or omitted) is never retried on a parse failure — there is nothing
+ * to parse, so every completion would look like a defect.
+ */
+export declare function expectsJsonOutput(responseFormat: ResponseFormatShape | null | undefined): boolean;
+/**
+ * Whether a structured-output completion holds parseable JSON.
+ *
+ * Tool calls and refusals are valid non-JSON outcomes and pass. A wholly empty
+ * completion is a {@link detectCompletionDefect} concern, but a *whitespace-only*
+ * one is truthy there and slips through — so this deliberately does NOT
+ * short-circuit on empty content: an empty or whitespace string is not valid
+ * JSON, fails the parse, and earns a retry.
+ *
+ * The ``` / ```json fences some models wrap JSON in are stripped first,
+ * mirroring what structured consumers do before parsing. A bare `true` / `false`
+ * is itself valid JSON, so a model that answers a boolean schema with the bare
+ * literal still passes; only genuinely malformed or truncated JSON fails.
+ */
+export declare function structuredOutputParses(completion: CompletionOutputs): boolean;

package/completion/defects.js

@@ -0,0 +1,128 @@
+/**
+ * Transient defects in an assembled completion, and the retry predicates that
+ * decide whether to ask the same endpoint again.
+ *
+ * A completion can come back structurally intact at the transport layer and
+ * still be unusable: the provider cut the stream mid-arguments, or closed it
+ * having emitted nothing at all. Neither is an HTTP failure — there is no
+ * status code to classify — so nothing upstream in the routing taxonomy sees
+ * them. Left undetected they reach the agent loop, where a truncated tool call
+ * is rejected as "invalid JSON in tool arguments" and burns a whole recovery
+ * turn on something a plain retry fixes.
+ *
+ * The two defect kinds here are exactly the two that feed
+ * `InferenceAttemptError`'s `completion_defect` arm, which the disposition
+ * matrix routes to a same-endpoint retry before traversing providers.
+ *
+ * Everything in this module is pure. Types are structural rather than tied to
+ * any SDK's message class, so a host assembling chunks by hand and a host
+ * handing over an `openai` message both fit without a cast.
+ */
+/**
+ * Additional attempts when a structured-output call returns content that will
+ * not parse as JSON: the initial call plus this many retries. Providers
+ * occasionally truncate or malform JSON even under a strict schema, and a fresh
+ * attempt almost always comes back valid.
+ */
+export const DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES = 3;
+/**
+ * Same-endpoint retry budget for a transiently-corrupt completion. A fresh
+ * attempt on the SAME endpoint usually recovers an intact response; a
+ * persistently-broken endpoint exhausts these, and the route executor then
+ * traverses to the next provider or model.
+ */
+export const DEFAULT_COMPLETION_DEFECT_MAX_RETRIES = 2;
+/** True when `s` parses as JSON. */
+export function jsonParses(s) {
+    try {
+        JSON.parse(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find the transient defect in an assembled completion, or `null` when it is
+ * usable.
+ *
+ * **Empty completion.** No content, no tool calls, no refusal. A refusal alone
+ * is a legitimate output and is not a defect.
+ *
+ * **Truncated tool call.** Non-empty arguments that do not parse as JSON are
+ * always a truncation — the provider cut the stream mid-arguments. *Empty*
+ * arguments are the normal zero-arg shape and are not a defect **unless** the
+ * stream was `cutByTokenLimit`: a length-truncated empty-args call is an
+ * incomplete message, not a deliberate no-arg call, and exempting it would let
+ * a dispatcher execute a tool off a half-streamed turn.
+ *
+ * `cutByTokenLimit` is the *fact*, not the wire spelling of it — OpenAI says
+ * `finish_reason: "length"`, Anthropic says `max_tokens`, Gemini says
+ * `MAX_TOKENS`. Taking the fact keeps the one behavioural rule in this module
+ * from silently reading `false` for every host that isn't on an
+ * OpenAI-compatible gateway, which would apply the zero-arg exemption to
+ * exactly the truncated calls it exists to exclude.
+ *
+ * A tool call whose `arguments` are not a readable string is skipped rather
+ * than inspected: {@link CompletionOutputs.tool_calls} accepts a host's full
+ * SDK union, and a non-function member (OpenAI's `type: "custom"`) has no
+ * arguments to truncate.
+ */
+export function detectCompletionDefect(completion, cutByTokenLimit) {
+    const toolCalls = completion.tool_calls;
+    const hasToolCalls = toolCalls !== undefined && toolCalls.length > 0;
+    if (!completion.content && !hasToolCalls && !completion.refusal) {
+        return { kind: "empty_completion" };
+    }
+    if (hasToolCalls) {
+        const truncated = toolCalls.find((toolCall) => {
+            const args = toolCall?.function?.arguments;
+            if (typeof args !== "string")
+                return false;
+            const rawArgs = args.trim();
+            if (rawArgs.length === 0)
+                return cutByTokenLimit;
+            return !jsonParses(rawArgs);
+        });
+        if (truncated !== undefined) {
+            return { kind: "truncated_tool_call", toolCall: truncated };
+        }
+    }
+    return null;
+}
+/**
+ * True when `response_format` asks the model for JSON. Free-form output
+ * (`text`, or omitted) is never retried on a parse failure — there is nothing
+ * to parse, so every completion would look like a defect.
+ */
+export function expectsJsonOutput(responseFormat) {
+    return (responseFormat?.type === "json_schema" || responseFormat?.type === "json_object");
+}
+/**
+ * Whether a structured-output completion holds parseable JSON.
+ *
+ * Tool calls and refusals are valid non-JSON outcomes and pass. A wholly empty
+ * completion is a {@link detectCompletionDefect} concern, but a *whitespace-only*
+ * one is truthy there and slips through — so this deliberately does NOT
+ * short-circuit on empty content: an empty or whitespace string is not valid
+ * JSON, fails the parse, and earns a retry.
+ *
+ * The ``` / ```json fences some models wrap JSON in are stripped first,
+ * mirroring what structured consumers do before parsing. A bare `true` / `false`
+ * is itself valid JSON, so a model that answers a boolean schema with the bare
+ * literal still passes; only genuinely malformed or truncated JSON fails.
+ */
+export function structuredOutputParses(completion) {
+    const toolCalls = completion.tool_calls;
+    if (toolCalls !== undefined && toolCalls !== null && toolCalls.length > 0) {
+        return true;
+    }
+    if (completion.refusal)
+        return true;
+    const content = (completion.content ?? "").trim();
+    const unfenced = content
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "")
+        .trim();
+    return jsonParses(unfenced);
+}

package/completion/index.d.ts

@@ -0,0 +1,2 @@
+export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, type ChunkOutput, type StreamStall, type StreamWatchdog, type StreamWatchdogOptions, } from "./watchdog.js";
+export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, type AssembledCompletion, type CompletionDefect, type CompletionOutputs, type ResponseFormatShape, type StreamedToolCall, } from "./defects.js";

package/completion/index.js

@@ -0,0 +1,2 @@
+export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, } from "./watchdog.js";
+export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, } from "./defects.js";

package/completion/watchdog.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Streaming-completion idle watchdog.
+ *
+ * A chat-completions SDK's `timeout` bounds *establishing* the request and (for
+ * a non-streaming call) the whole response — but once a stream has started
+ * yielding, nothing bounds the gap between chunks. A provider that opens the
+ * stream and then stalls leaves the consumer's `for await` awaiting the next
+ * chunk forever, holding its worker slot until some outer deadline fires, or
+ * never. Downstream that is the agent that says "thinking…" and never answers.
+ *
+ * The budget is split into three because the phases of a streaming completion
+ * have very different normal latencies, and one number cannot serve all of them:
+ *
+ * - **Time to first token** — from opening the stream to the first *answer*
+ *   token. Generous: a high-reasoning model can legitimately think for a while
+ *   before emitting anything, and even once reasoning deltas are flowing it can
+ *   sit silent for seconds between finishing its reasoning and emitting the
+ *   first content/tool token. This budget therefore covers the reasoning phase
+ *   AND the reasoning→answer gap — {@link ChunkOutput} `"reasoning"` does NOT
+ *   switch to the tight budget. Arming the tight budget on a reasoning token is
+ *   a real observed failure: the normal reasoning→content pause of a frontier
+ *   reasoning model routinely approaches several seconds and tripped
+ *   "no chunk mid-stream" on healthy turns.
+ * - **Inter-chunk** — the gap between chunks once the model's ANSWER output
+ *   (content / tool-call arguments / refusal) is flowing. Tight: answer chunks
+ *   normally arrive sub-second, so a multi-second silence mid-answer is already
+ *   abnormal, and a shorter budget recovers a mid-stream stall far sooner.
+ * - **Overall cap** — an absolute wall-clock ceiling, armed at construction and
+ *   never re-armed. Defense in depth, not a duplicate of the two idle budgets:
+ *   the idle watchdog only bounds the *gap* between chunks, so a provider that
+ *   drip-feeds a chunk just under the idle budget forever (a reasoning delta a
+ *   minute, never reaching an answer) never trips it. The proper bound on total
+ *   work is the caller's own deadline signal, but not every caller has one, so
+ *   this guarantees a single call cannot hold a slot indefinitely regardless.
+ *
+ *   It is armed by the constructor rather than by {@link StreamWatchdog.open}
+ *   because it is the guarantee of last resort: a host that forgets `open()`
+ *   gets a watchdog that silently never fires, with no type error and no test
+ *   failure, and the symptom appears only under a stalling provider. Counting
+ *   the connection handshake against a ceiling this generous costs nothing;
+ *   leaving the ceiling to an imperative call the host may skip costs a worker
+ *   slot. The two *idle* budgets genuinely must wait for `open()` — arming them
+ *   earlier would charge connection time to the first-token budget.
+ *
+ * The watchdog owns timers and abort signals and nothing else: it does not read
+ * the stream, does not know the wire format, and does not phrase the error. It
+ * reports a structured {@link StreamStall} and the host words it — the same
+ * split the routing modules use, since a stall message is usually product copy.
+ */
+/**
+ * What a streamed chunk carried, from the watchdog's point of view. The
+ * distinction that matters is `"reasoning"` vs `"answer"`: only answer output
+ * arms the tight inter-chunk budget. A chunk carrying both is `"answer"`.
+ * A role/metadata-only opening chunk is `"none"` — the model has not produced a
+ * token yet, so it must not shorten the budget either.
+ */
+export type ChunkOutput = "none" | "reasoning" | "answer";
+/** Why the watchdog tore the stream down. */
+export type StreamStall = 
+/** The absolute wall-clock ceiling elapsed before the stream finished. */
+Readonly<{
+    kind: "overall_cap";
+    limitMs: number;
+}>
+/**
+ * No answer token within the generous budget. `sawReasoning` distinguishes
+ * "the provider never said anything" from "it streamed reasoning and never
+ * reached an answer" — different upstream faults with the same budget.
+ */
+ | Readonly<{
+    kind: "time_to_first_token";
+    limitMs: number;
+    sawReasoning: boolean;
+}>
+/** Answer output was flowing and then stopped mid-stream. */
+ | Readonly<{
+    kind: "inter_chunk";
+    limitMs: number;
+}>;
+export interface StreamWatchdogOptions {
+    /** Generous first-answer-token budget. Default {@link DEFAULT_TIME_TO_FIRST_TOKEN_MS}. */
+    readonly timeToFirstTokenMs?: number;
+    /** Tight budget between chunks once answer output flows. Default {@link DEFAULT_INTER_CHUNK_MS}. */
+    readonly interChunkMs?: number;
+    /**
+     * Absolute ceiling on the whole call, measured from **watchdog
+     * construction** — not from {@link StreamWatchdog.open}, which only arms the
+     * idle budgets. Size it to include whatever the host does between
+     * constructing the watchdog and opening the stream (connecting, sending the
+     * request, waiting on response headers), since all of that is inside the
+     * budget. Default {@link DEFAULT_MAX_CALL_DURATION_MS}.
+     */
+    readonly maxCallDurationMs?: number;
+    /**
+     * The caller's own abort signal (a run deadline, a cancellation). Composed
+     * into {@link StreamWatchdog.signal}, and — critically — consulted by
+     * {@link StreamWatchdog.stall}: when the caller aborted, the teardown is the
+     * caller's, not a stall, and must not be reclassified as a retriable
+     * upstream fault.
+     */
+    readonly external?: AbortSignal | null;
+    /**
+     * Timer port, defaulting to the ambient globals. Inject a controllable clock
+     * to test budget behaviour exactly, rather than sleeping a real interval and
+     * hoping the machine keeps up — a watchdog test asserting "nothing fired yet"
+     * against a real timer is a flake waiting for a loaded CI box.
+     *
+     * The handle is opaque (`unknown`) so a fake can hand back whatever it likes;
+     * only {@link StreamTimers.clear} ever consumes it.
+     */
+    readonly timers?: StreamTimers;
+}
+/** The subset of the timer API the watchdog needs. */
+export interface StreamTimers {
+    set(callback: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+export interface StreamWatchdog {
+    /** Hand this to the transport as the request's abort signal. */
+    readonly signal: AbortSignal;
+    /**
+     * The stream is open: arm the time-to-first-token budget. Call immediately
+     * after the transport returns the stream — arming before that would count
+     * connection time against the first-token budget. The absolute cap is already
+     * running (see {@link createStreamWatchdog}); this only starts the idle
+     * budgets. Idempotent, and a no-op after {@link dispose}.
+     */
+    open(): void;
+    /**
+     * A chunk arrived: re-arm for the gap to the *next* one. Call for every
+     * chunk, including metadata-only ones — a chunk that carried nothing still
+     * proves the stream is alive.
+     */
+    observedChunk(output: ChunkOutput): void;
+    /**
+     * Why the stream was torn down, or `null` if this watchdog did not do it.
+     * Returns `null` whenever the caller's own signal aborted, even if a budget
+     * also elapsed: a cancelled call is cancelled, not stalled.
+     *
+     * Call from the `catch` that saw the abort, before {@link dispose}.
+     */
+    stall(): StreamStall | null;
+    /**
+     * Clear the timers, forget any budget that elapsed, and settle the composite
+     * signal. Idempotent; call from a `finally` on every path.
+     *
+     * Settling matters as much as clearing: the composite holds a listener on a
+     * possibly long-lived caller signal, and one per call across a run's many
+     * calls is a leak.
+     *
+     * Forgetting matters because a timer can fire in the moment between the last
+     * chunk and the stream ending — the abort loses the race, the read completes
+     * normally, and nothing was torn down. If that stale flag survived, a *later*
+     * failure on the same call (a defect found while assembling the message, a
+     * billing read) would reach {@link stall} and be reported as an upstream
+     * stall it had nothing to do with. Call `stall()` before `dispose()`, which
+     * is the documented order and the only order in which a real stall is
+     * observable anyway.
+     */
+    dispose(): void;
+}
+export declare const DEFAULT_TIME_TO_FIRST_TOKEN_MS = 120000;
+export declare const DEFAULT_INTER_CHUNK_MS = 5000;
+export declare const DEFAULT_MAX_CALL_DURATION_MS = 600000;
+export declare function createStreamWatchdog(options?: StreamWatchdogOptions): StreamWatchdog;

package/completion/watchdog.js

@@ -0,0 +1,211 @@
+/**
+ * Streaming-completion idle watchdog.
+ *
+ * A chat-completions SDK's `timeout` bounds *establishing* the request and (for
+ * a non-streaming call) the whole response — but once a stream has started
+ * yielding, nothing bounds the gap between chunks. A provider that opens the
+ * stream and then stalls leaves the consumer's `for await` awaiting the next
+ * chunk forever, holding its worker slot until some outer deadline fires, or
+ * never. Downstream that is the agent that says "thinking…" and never answers.
+ *
+ * The budget is split into three because the phases of a streaming completion
+ * have very different normal latencies, and one number cannot serve all of them:
+ *
+ * - **Time to first token** — from opening the stream to the first *answer*
+ *   token. Generous: a high-reasoning model can legitimately think for a while
+ *   before emitting anything, and even once reasoning deltas are flowing it can
+ *   sit silent for seconds between finishing its reasoning and emitting the
+ *   first content/tool token. This budget therefore covers the reasoning phase
+ *   AND the reasoning→answer gap — {@link ChunkOutput} `"reasoning"` does NOT
+ *   switch to the tight budget. Arming the tight budget on a reasoning token is
+ *   a real observed failure: the normal reasoning→content pause of a frontier
+ *   reasoning model routinely approaches several seconds and tripped
+ *   "no chunk mid-stream" on healthy turns.
+ * - **Inter-chunk** — the gap between chunks once the model's ANSWER output
+ *   (content / tool-call arguments / refusal) is flowing. Tight: answer chunks
+ *   normally arrive sub-second, so a multi-second silence mid-answer is already
+ *   abnormal, and a shorter budget recovers a mid-stream stall far sooner.
+ * - **Overall cap** — an absolute wall-clock ceiling, armed at construction and
+ *   never re-armed. Defense in depth, not a duplicate of the two idle budgets:
+ *   the idle watchdog only bounds the *gap* between chunks, so a provider that
+ *   drip-feeds a chunk just under the idle budget forever (a reasoning delta a
+ *   minute, never reaching an answer) never trips it. The proper bound on total
+ *   work is the caller's own deadline signal, but not every caller has one, so
+ *   this guarantees a single call cannot hold a slot indefinitely regardless.
+ *
+ *   It is armed by the constructor rather than by {@link StreamWatchdog.open}
+ *   because it is the guarantee of last resort: a host that forgets `open()`
+ *   gets a watchdog that silently never fires, with no type error and no test
+ *   failure, and the symptom appears only under a stalling provider. Counting
+ *   the connection handshake against a ceiling this generous costs nothing;
+ *   leaving the ceiling to an imperative call the host may skip costs a worker
+ *   slot. The two *idle* budgets genuinely must wait for `open()` — arming them
+ *   earlier would charge connection time to the first-token budget.
+ *
+ * The watchdog owns timers and abort signals and nothing else: it does not read
+ * the stream, does not know the wire format, and does not phrase the error. It
+ * reports a structured {@link StreamStall} and the host words it — the same
+ * split the routing modules use, since a stall message is usually product copy.
+ */
+export const DEFAULT_TIME_TO_FIRST_TOKEN_MS = 120_000;
+export const DEFAULT_INTER_CHUNK_MS = 5_000;
+export const DEFAULT_MAX_CALL_DURATION_MS = 600_000;
+/**
+ * The largest delay `setTimeout` can represent. Above this the delay overflows
+ * its 32-bit signed field and the timer fires almost immediately instead.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * A budget must be a delay `setTimeout` can actually honour.
+ *
+ * This is checked at construction, and it fails closed in the direction that
+ * actually bites. Every value rejected here would otherwise make the watchdog
+ * fire on the next tick and tear down every *healthy* stream, surfacing as a
+ * total inference outage that looks like a provider incident:
+ *
+ * - `NaN` / `Infinity`: `setTimeout` coerces a non-finite delay to 1ms rather
+ *   than ignoring it, so a bad budget does not disable the watchdog — it makes
+ *   it instantaneous.
+ * - Zero or negative: fires on the next tick by definition.
+ * - Above {@link MAX_TIMEOUT_MS}: overflows the 32-bit delay and, per spec,
+ *   clamps to 1ms. This is the trap that reads as reasonable — `maxCallDuration`
+ *   of 30 days is a plausible config value and the units are milliseconds, so
+ *   it is one `* 1000` away from a healthy-looking number that disables the
+ *   backstop entirely.
+ *
+ * Refusing the value at construction turns a silent outage into a stack trace
+ * at the call site that supplied it.
+ */
+function requirePositiveMs(value, field) {
+    if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMEOUT_MS) {
+        throw new RangeError(`StreamWatchdog ${field} must be a positive number of ms no greater than ${MAX_TIMEOUT_MS}, got ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * Call `unref()` on a timer when the runtime exposes it (Node/Bun) so a
+ * forgotten `dispose()` cannot hold the event loop open; a no-op under a DOM
+ * `number` timer or an injected fake. Feature-detected rather than `as`-cast to
+ * keep type safety.
+ *
+ * Duplicated from `../run/harness` deliberately: importing across module
+ * folders would make `@juno-ai/bind/completion` drag in the run mechanics for
+ * five lines, and a consumer that wants only the watchdog should get only the
+ * watchdog.
+ */
+function unrefTimer(timer) {
+    if (typeof timer === "object" &&
+        timer !== null &&
+        "unref" in timer &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+const AMBIENT_TIMERS = {
+    set: (callback, ms) => setTimeout(callback, ms),
+    clear: (handle) => {
+        clearTimeout(handle);
+    },
+};
+export function createStreamWatchdog(options = {}) {
+    const timeToFirstTokenMs = requirePositiveMs(options.timeToFirstTokenMs ?? DEFAULT_TIME_TO_FIRST_TOKEN_MS, "timeToFirstTokenMs");
+    const interChunkMs = requirePositiveMs(options.interChunkMs ?? DEFAULT_INTER_CHUNK_MS, "interChunkMs");
+    const maxCallDurationMs = requirePositiveMs(options.maxCallDurationMs ?? DEFAULT_MAX_CALL_DURATION_MS, "maxCallDurationMs");
+    const external = options.external ?? null;
+    const timers = options.timers ?? AMBIENT_TIMERS;
+    // Two controllers rather than one, so `stall()` can name which bound tripped
+    // without the caller having to correlate timers.
+    const idleController = new AbortController();
+    const overallController = new AbortController();
+    let idleFired = false;
+    let overallFired = false;
+    let disposed = false;
+    // True once any chunk carried model output; only phrases the diagnostic.
+    let sawOutput = false;
+    // True once ANSWER output flowed. Only this arms the tight budget.
+    let sawAnswerOutput = false;
+    let idleTimer = null;
+    let overallTimer = null;
+    function armIdle(ms) {
+        if (idleTimer !== null)
+            timers.clear(idleTimer);
+        idleTimer = timers.set(() => {
+            idleFired = true;
+            idleController.abort();
+        }, ms);
+        unrefTimer(idleTimer);
+    }
+    function clearTimers() {
+        if (idleTimer !== null) {
+            timers.clear(idleTimer);
+            idleTimer = null;
+        }
+        if (overallTimer !== null) {
+            timers.clear(overallTimer);
+            overallTimer = null;
+        }
+    }
+    const signal = AbortSignal.any(external
+        ? [external, idleController.signal, overallController.signal]
+        : [idleController.signal, overallController.signal]);
+    // Armed here, not in `open()`, so the ceiling holds even for a host that
+    // never calls `open()`. See the module header.
+    overallTimer = timers.set(() => {
+        overallFired = true;
+        overallController.abort();
+    }, maxCallDurationMs);
+    unrefTimer(overallTimer);
+    return {
+        signal,
+        open() {
+            if (disposed)
+                return;
+            armIdle(timeToFirstTokenMs);
+        },
+        observedChunk(output) {
+            if (disposed)
+                return;
+            if (output !== "none")
+                sawOutput = true;
+            if (output === "answer")
+                sawAnswerOutput = true;
+            armIdle(sawAnswerOutput ? interChunkMs : timeToFirstTokenMs);
+        },
+        stall() {
+            // A caller abort wins over every budget: the stream may well have been
+            // idle when cancellation landed, but reporting that as an upstream stall
+            // would make a deliberate cancellation look retriable.
+            if (external?.aborted)
+                return null;
+            // Checked before the idle budget because the cap is the stronger claim:
+            // when both elapsed, the call ran past its absolute ceiling, and the
+            // trailing idle gap is a symptom of that rather than a separate fault.
+            if (overallFired) {
+                return { kind: "overall_cap", limitMs: maxCallDurationMs };
+            }
+            if (idleFired) {
+                if (sawAnswerOutput)
+                    return { kind: "inter_chunk", limitMs: interChunkMs };
+                return {
+                    kind: "time_to_first_token",
+                    limitMs: timeToFirstTokenMs,
+                    sawReasoning: sawOutput,
+                };
+            }
+            return null;
+        },
+        dispose() {
+            disposed = true;
+            clearTimers();
+            // Drop any budget that elapsed. A timer that fired in the moment before
+            // the stream ended lost the race — it tore nothing down — and leaving the
+            // flag set would let it be blamed for a later, unrelated failure on the
+            // same call. See the `dispose` doc comment.
+            idleFired = false;
+            overallFired = false;
+            // Abort the idle controller (not the overall one) purely to settle the
+            // composite so it releases its listener on `external`.
+            idleController.abort();
+        },
+    };
+}

package/index.d.ts

@@ -6,16 +6,19 @@
  * the harness that runs that chain.
  *
  * Current surface: the tool-calling turn kernel (`src/loop/` — the iteration
- * engine itself), the deterministic LLM provider-routing core, the turn
- * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
- * classification, tool-batch pooling, child-run lineage and admission),
- * transcript validation/healing, provider tool-schema sanitization, and the
- * plugin/tool vocabulary with its registry and progressive-disclosure
- * activation — generic over the host's invocation context. What is NOT here is
+ * engine itself), the deterministic LLM provider-routing core with its
+ * transport-error classifier, the turn vocabulary, the run mechanics (deadline,
+ * coalesced heartbeat, failure classification, tool-batch pooling, child-run
+ * lineage and admission), the streaming-completion watchdog and completion
+ * defect detection (`src/completion/`), transcript validation/healing, provider
+ * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * progressive-disclosure activation — generic over the host's invocation
+ * context. What is NOT here is
  * the run driver: starting a run, recording what it did, and delivering its
  * output. See the README for the rest of what is deliberately absent.
  */
 export * from "./routing/index.js";
+export * from "./completion/index.js";
 export * from "./contracts/index.js";
 export * from "./run/index.js";
 export * from "./transcript/index.js";

package/index.js

@@ -6,16 +6,19 @@
  * the harness that runs that chain.
  *
  * Current surface: the tool-calling turn kernel (`src/loop/` — the iteration
- * engine itself), the deterministic LLM provider-routing core, the turn
- * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
- * classification, tool-batch pooling, child-run lineage and admission),
- * transcript validation/healing, provider tool-schema sanitization, and the
- * plugin/tool vocabulary with its registry and progressive-disclosure
- * activation — generic over the host's invocation context. What is NOT here is
+ * engine itself), the deterministic LLM provider-routing core with its
+ * transport-error classifier, the turn vocabulary, the run mechanics (deadline,
+ * coalesced heartbeat, failure classification, tool-batch pooling, child-run
+ * lineage and admission), the streaming-completion watchdog and completion
+ * defect detection (`src/completion/`), transcript validation/healing, provider
+ * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * progressive-disclosure activation — generic over the host's invocation
+ * context. What is NOT here is
  * the run driver: starting a run, recording what it did, and delivering its
  * output. See the README for the rest of what is deliberately absent.
  */
 export * from "./routing/index.js";
+export * from "./completion/index.js";
 export * from "./contracts/index.js";
 export * from "./run/index.js";
 export * from "./transcript/index.js";

package/loop/tool-loop.js

@@ -43,17 +43,29 @@ export async function runToolLoop(params) {
         await ensureNotCancelled?.();
         const tools = buildTools();
         onStatus?.(iteration === 0 ? "thinking" : "thinking_with_tools");
-        // Stream live token progress: the per-call estimate is added to the cumulative
-        // from prior iterations so a caller's counter rises monotonically across a
-        // multi-iteration run. The real cumulative is published right after the call
-        // returns (below), reconciling any estimate drift.
+        // Stream live token progress: the per-call estimate is added to the
+        // cumulative from prior iterations so a caller's counter rises across a
+        // multi-iteration run. The real cumulative is published right after the
+        // call returns (below), reconciling any estimate drift.
+        //
+        // Clamped to a per-call high-water mark because `callModel` may internally
+        // retry — a defect retry, another provider, the fallback model — and each
+        // attempt restarts its own estimate at zero. Unclamped, a caller's counter
+        // visibly runs backwards mid-turn ("1.2k tokens" → blank → "120 tokens"),
+        // which reads as lost work at exactly the moment the system is recovering
+        // from a fault. The mark is per-call, so the post-call reconciliation to
+        // the real total below is free to correct downward.
         const baseOutputTokens = state.outputTokens;
+        let progressHighWater = baseOutputTokens;
         const result = await callModel(state.messages, tools.length > 0 ? tools : undefined, 
         // Carry the cumulative tool count alongside the streamed token estimate so
         // the pill shows both; no tools run *during* a model call, so the count is
         // whatever has accumulated from prior iterations.
         onProgressUpdate
-            ? (estCallTokens) => onProgressUpdate(baseOutputTokens + estCallTokens, state.toolCalls)
+            ? (estCallTokens) => {
+                progressHighWater = Math.max(progressHighWater, baseOutputTokens + estCallTokens);
+                onProgressUpdate(progressHighWater, state.toolCalls);
+            }
             : undefined);
         state.inputTokens += result.inputTokens;
         state.outputTokens += result.outputTokens;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juno-ai/bind",
-  "version": "4.0.0",
-  "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "version": "5.0.0",
+  "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -15,6 +15,10 @@
       "types": "./routing/index.d.ts",
       "import": "./routing/index.js"
     },
+    "./completion": {
+      "types": "./completion/index.d.ts",
+      "import": "./completion/index.js"
+    },
     "./contracts": {
       "types": "./contracts/index.d.ts",
       "import": "./contracts/index.js"

package/routing/attempt-errors.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Classification: a thrown transport error → the {@link InferenceAttemptError}
+ * taxonomy the executor routes on.
+ *
+ * `errors.ts` owns what the router *does* with a classified failure
+ * (`failureDisposition`) and `executor.ts` applies it. This module is the step
+ * before both — the one every host was writing itself. The PRD's split is
+ * "transports classify facts; the executor decides," and shipping only the
+ * decider left each consumer to hand-roll the classifier, where the mistakes
+ * are not obvious: misfile a moderation refusal as a credential failure and the
+ * circuit breaker opens the endpoint for everyone sharing that breaker key —
+ * which, for a host that does not set `credentialScope`, is every tenant on the
+ * process.
+ *
+ * The host keeps the two things that are genuinely its own — recognizing its
+ * error class ({@link AttemptClassification.asTransportFailure}) and any
+ * provider-specific status reading ({@link AttemptClassification.categorizeStatus}).
+ * Neither can live here: the first is a class this package must not import, and
+ * the second is provider-registry knowledge.
+ */
+import type { AttemptTarget, HttpFailureCategory, InferenceAttemptError } from "./errors.js";
+import type { ProviderId } from "./canonical-model.js";
+import type { CompletionDefectKind } from "../completion/defects.js";
+/**
+ * What a transport observed, in the vocabulary the taxonomy needs. A host maps
+ * its own error class onto this once.
+ *
+ * `"api"` is the catch-all for a response the provider rejected with a status
+ * the transport did not interpret further; it is the only kind whose routing
+ * behavior depends on {@link TransportFailure.statusCode}.
+ */
+export type TransportFailureKind = CompletionDefectKind | "server_error" | "rate_limit" | "no_credits" | "api" | "network";
+export interface TransportFailure {
+    readonly kind: TransportFailureKind;
+    /** HTTP status when the failure carried one; null for transport-level faults. */
+    readonly statusCode: number | null;
+    /** Parsed `Retry-After`, which bounds-extends the breaker cooldown. */
+    readonly retryAfterMs: number | null;
+}
+export interface AttemptClassification {
+    /**
+     * Recognize the host's own transport-error class and describe it. Return
+     * `null` for anything that is not one — those propagate as a client error
+     * rather than burning the plan (see {@link classifyAttemptError}).
+     */
+    readonly asTransportFailure: (error: unknown) => TransportFailure | null;
+    /**
+     * Provider-specific status → category, consulted before the neutral
+     * {@link categorizeHttpStatus}. Return `null` to fall through to it.
+     *
+     * This exists because status codes are not portable across providers: one
+     * gateway answers 403 for moderation-flagged *input* (request-shaped — a
+     * different provider may accept it, and the endpoint is healthy), where the
+     * neutral mapping reads 403 as a credential failure and opens the circuit
+     * immediately.
+     */
+    readonly categorizeStatus?: (statusCode: number, providerId: ProviderId) => HttpFailureCategory | null;
+    /**
+     * Recognize a caller-cancellation. Defaults to {@link isAbortByName} —
+     * `error.name === "AbortError"`, which is what `AbortSignal` and `fetch`
+     * produce.
+     *
+     * **Override this if your SDK wraps aborts in its own class.** The one that
+     * bites: `openai`'s `APIUserAbortError` extends its `APIError` and never sets
+     * `name`, so `error.name` is the inherited `"Error"` — it matches neither the
+     * default nor an `instanceof` check you didn't write. Left unrecognized, a
+     * deliberate cancellation classifies as a propagating `client_error`: it
+     * still stops the plan, but it is attributed as a fault rather than a
+     * cancellation, which pollutes failure telemetry and any breaker or retry
+     * accounting keyed off it.
+     *
+     * ```ts
+     * isAbort: (e) => e instanceof OpenAI.APIUserAbortError || isAbortByName(e),
+     * ```
+     */
+    readonly isAbort?: (error: unknown) => boolean;
+}
+/**
+ * The default abort test: the `name` an `AbortSignal`-driven `fetch` rejection
+ * carries. Exported so a host overriding {@link AttemptClassification.isAbort}
+ * can widen it rather than replace it.
+ */
+export declare function isAbortByName(error: unknown): boolean;
+/**
+ * Map a thrown error onto the attempt-error taxonomy. The original error rides
+ * in `cause` and is re-thrown verbatim if the plan exhausts, so a host's error
+ * classes and messages survive routing untouched.
+ *
+ * Order is deliberate. An abort is checked first: a cancelled call must never
+ * be reclassified as a provider fault, whatever else is true of it. Anything
+ * the host does not recognize as a transport failure is classified
+ * `client_error` — which propagates rather than traverses — because an error
+ * that escaped the transport without becoming one of its own is a programming
+ * defect (a `TypeError`, a validation throw), and burning every provider and
+ * the fallback model retrying a bug wastes a whole plan to arrive at the same
+ * exception.
+ */
+export declare function classifyAttemptError(error: unknown, target: AttemptTarget, classification: AttemptClassification): InferenceAttemptError;
+/**
+ * Parse a `Retry-After` response header into milliseconds, per RFC 9110: either
+ * delta-seconds or an HTTP-date. Returns `null` when absent or unparseable —
+ * the breaker then falls back to its own cooldown, so a header this cannot read
+ * degrades to the default rather than to no cooldown at all.
+ *
+ * **This value is attacker-influenceable and is not bounded here.** It comes
+ * from whatever answered the request — the provider, a gateway, a proxy — and
+ * RFC 9110 puts no ceiling on it, so a hostile or malfunctioning upstream can
+ * ask for a delay of years. Clamp before using it as a delay:
+ * {@link createCircuitBreaker} already does (`maxCooldownMs`), but a host that
+ * sleeps on this directly must impose its own bound, or one bad response header
+ * parks an endpoint indefinitely.
+ *
+ * `headers` is deliberately `unknown`: SDKs hand back a `Headers`, a plain
+ * object, or a `Map` depending on version and runtime. Anything with a `get`
+ * method is asked for the header (covering `Headers` and `Map` without naming
+ * either global, which keeps this portable to runtimes that ship neither);
+ * a plain object is read case-insensitively for the two spellings that occur
+ * in practice.
+ *
+ * @param now Injectable clock for the HTTP-date branch; defaults to `Date.now`.
+ */
+export declare function retryAfterMsFromHeaders(headers: unknown, now?: () => number): number | null;

package/routing/attempt-errors.js

@@ -0,0 +1,176 @@
+/**
+ * Classification: a thrown transport error → the {@link InferenceAttemptError}
+ * taxonomy the executor routes on.
+ *
+ * `errors.ts` owns what the router *does* with a classified failure
+ * (`failureDisposition`) and `executor.ts` applies it. This module is the step
+ * before both — the one every host was writing itself. The PRD's split is
+ * "transports classify facts; the executor decides," and shipping only the
+ * decider left each consumer to hand-roll the classifier, where the mistakes
+ * are not obvious: misfile a moderation refusal as a credential failure and the
+ * circuit breaker opens the endpoint for everyone sharing that breaker key —
+ * which, for a host that does not set `credentialScope`, is every tenant on the
+ * process.
+ *
+ * The host keeps the two things that are genuinely its own — recognizing its
+ * error class ({@link AttemptClassification.asTransportFailure}) and any
+ * provider-specific status reading ({@link AttemptClassification.categorizeStatus}).
+ * Neither can live here: the first is a class this package must not import, and
+ * the second is provider-registry knowledge.
+ */
+import { categorizeHttpStatus } from "./errors.js";
+/**
+ * The default abort test: the `name` an `AbortSignal`-driven `fetch` rejection
+ * carries. Exported so a host overriding {@link AttemptClassification.isAbort}
+ * can widen it rather than replace it.
+ */
+export function isAbortByName(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+/**
+ * Map a thrown error onto the attempt-error taxonomy. The original error rides
+ * in `cause` and is re-thrown verbatim if the plan exhausts, so a host's error
+ * classes and messages survive routing untouched.
+ *
+ * Order is deliberate. An abort is checked first: a cancelled call must never
+ * be reclassified as a provider fault, whatever else is true of it. Anything
+ * the host does not recognize as a transport failure is classified
+ * `client_error` — which propagates rather than traverses — because an error
+ * that escaped the transport without becoming one of its own is a programming
+ * defect (a `TypeError`, a validation throw), and burning every provider and
+ * the fallback model retrying a bug wastes a whole plan to arrive at the same
+ * exception.
+ */
+export function classifyAttemptError(error, target, classification) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const isAbort = classification.isAbort ?? isAbortByName;
+    if (isAbort(error)) {
+        return { kind: "aborted", target, cause };
+    }
+    const failure = classification.asTransportFailure(error);
+    if (failure === null) {
+        return {
+            kind: "http",
+            category: "client_error",
+            statusCode: 0,
+            retryAfterMs: null,
+            target,
+            cause,
+        };
+    }
+    switch (failure.kind) {
+        case "empty_completion":
+        case "truncated_tool_call":
+            return { kind: "completion_defect", defect: failure.kind, target, cause };
+        case "network":
+            return { kind: "network", target, cause };
+        case "rate_limit":
+            return httpError("rate_limit", failure.statusCode ?? 429, failure, target, cause);
+        case "no_credits":
+            return httpError("credits", failure.statusCode ?? 402, failure, target, cause);
+        case "server_error":
+            return httpError("server_error", failure.statusCode ?? 500, failure, target, cause);
+        case "api": {
+            const statusCode = failure.statusCode;
+            // No status at all means the transport could not attribute the rejection
+            // to the endpoint; propagate rather than traverse.
+            const category = statusCode === null
+                ? "client_error"
+                : (classification.categorizeStatus?.(statusCode, target.providerId) ??
+                    categorizeHttpStatus(statusCode));
+            return httpError(category, statusCode ?? 0, failure, target, cause);
+        }
+        default: {
+            const _exhaustive = failure.kind;
+            throw new Error(`unknown transport failure kind: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+function httpError(category, statusCode, failure, target, cause) {
+    return {
+        kind: "http",
+        category,
+        statusCode,
+        retryAfterMs: failure.retryAfterMs,
+        target,
+        cause,
+    };
+}
+/**
+ * Parse a `Retry-After` response header into milliseconds, per RFC 9110: either
+ * delta-seconds or an HTTP-date. Returns `null` when absent or unparseable —
+ * the breaker then falls back to its own cooldown, so a header this cannot read
+ * degrades to the default rather than to no cooldown at all.
+ *
+ * **This value is attacker-influenceable and is not bounded here.** It comes
+ * from whatever answered the request — the provider, a gateway, a proxy — and
+ * RFC 9110 puts no ceiling on it, so a hostile or malfunctioning upstream can
+ * ask for a delay of years. Clamp before using it as a delay:
+ * {@link createCircuitBreaker} already does (`maxCooldownMs`), but a host that
+ * sleeps on this directly must impose its own bound, or one bad response header
+ * parks an endpoint indefinitely.
+ *
+ * `headers` is deliberately `unknown`: SDKs hand back a `Headers`, a plain
+ * object, or a `Map` depending on version and runtime. Anything with a `get`
+ * method is asked for the header (covering `Headers` and `Map` without naming
+ * either global, which keeps this portable to runtimes that ship neither);
+ * a plain object is read case-insensitively for the two spellings that occur
+ * in practice.
+ *
+ * @param now Injectable clock for the HTTP-date branch; defaults to `Date.now`.
+ */
+export function retryAfterMsFromHeaders(headers, now = Date.now) {
+    const raw = rawRetryAfter(headers);
+    if (raw === null || raw === "")
+        return null;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds)) {
+        // A negative delta is malformed, and the date branch below would not
+        // reliably reject a bare "-5" either. Reject here instead.
+        if (seconds < 0)
+            return null;
+        // `1e308` is finite but overflows to Infinity once scaled to ms, and a
+        // non-finite delay is the one value that makes a timer fire immediately
+        // rather than never — the same trap `requirePositiveMs` guards in the
+        // watchdog. Refuse it rather than hand a caller a poisoned number.
+        const ms = Math.round(seconds * 1000);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    const dateMs = Date.parse(raw);
+    if (Number.isFinite(dateMs))
+        return Math.max(0, dateMs - now());
+    return null;
+}
+function rawRetryAfter(headers) {
+    if (typeof headers !== "object" || headers === null)
+        return null;
+    const getter = headers.get;
+    if (typeof getter === "function") {
+        // The getter belongs to the caller's object, so it is arbitrary code. This
+        // runs inside a host's `catch` while classifying a failure; letting a throw
+        // escape would replace the real provider error with this one and lose the
+        // classification entirely.
+        let value;
+        try {
+            value = getter.call(headers, "retry-after");
+        }
+        catch {
+            return null;
+        }
+        if (typeof value === "string")
+            return value;
+        // A `Map<string, number>` is as plausible as a `Map<string, string>`; the
+        // plain-object branch below accepts a number, so this one must too or the
+        // same header is read from one container and dropped from the other.
+        if (typeof value === "number")
+            return String(value);
+        return null;
+    }
+    const record = headers;
+    const value = record["retry-after"] ?? record["Retry-After"];
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    return null;
+}

package/routing/executor.js

@@ -42,7 +42,22 @@ export async function executeRoutePlan(options) {
                     endpointAttempt,
                 });
                 attemptCount += 1;
-                const outcome = await options.attempt(candidate, cursor);
+                // `attempt` is host code and is expected to resolve to an outcome, not
+                // throw — but if it does throw (a bug in its own classification, a
+                // host-supplied port raising), the throw must not carry a half-open
+                // probe out of the loop with it. The probe slot would stay occupied for
+                // the process's lifetime and every later call for this endpoint would
+                // be refused admission, silently, with no failure recorded to ever
+                // reopen it.
+                let outcome;
+                try {
+                    outcome = await options.attempt(candidate, cursor);
+                }
+                catch (error) {
+                    if (halfOpenProbe)
+                        breaker?.releaseProbe(breakerKey);
+                    throw error;
+                }
                 if (outcome.kind === "success") {
                     breaker?.recordSuccess(breakerKey);
                     return {

package/routing/index.d.ts

@@ -7,5 +7,6 @@ export { buildRoutePlanWithConfigDegradation, type DegradedStage, type DegradedP
 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 { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, type AttemptClassification, type TransportFailure, type TransportFailureKind, } from "./attempt-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

@@ -7,5 +7,6 @@ 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 { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, } from "./attempt-errors.js";
 export { createCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, } from "./executor.js";