@juno-ai/bind 3.0.0 → 5.0.0

package/README.md

@@ -36,7 +36,8 @@ is; you do not need it to use the package.*
 
 ### What a harness is, and what it is not
 
-A harness owns the parts of an agent loop that are the same for everyone:
+A harness owns the parts of an agent loop that are the same for everyone: the
+iteration itself — call the model, run what it asked for, repeat — plus
 deciding which provider to call and what to do when it fails, bounding a run in
 wall-clock time, keeping a transcript in a shape providers accept, rewriting
 tool schemas that strict validators reject, and tracking which tools are
@@ -103,11 +104,18 @@ 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 any child runs it
-spawns (see [Spawning child runs](#spawning-child-runs-sub-agents)).
+and run orchestration — the queue a run is scheduled on, and the enqueuing and
+storage behind any child runs it spawns. The harness decides whether a child is
+*allowed*; putting it on a queue is yours (see
+[Spawning child runs](#spawning-child-runs-sub-agents)).
+
+The loop is here, but the **driver** around it is not: starting a run, recording
+what it did, delivering its output, and deciding when to run it again. That is
+where a runtime's identity, storage, and product behaviour live, and it is why
+`runToolLoop` takes a dozen observers instead of doing any of it.
 
 ---
 
@@ -246,6 +254,93 @@ progressive tool disclosure with
 *Goal-oriented. Each answers one question and assumes you know roughly what you
 are doing.*
 
+### How to run the loop
+
+`runToolLoop` is the engine: it calls the model, runs the tools the model asks
+for, and repeats until the model stops asking, a tool suspends the run, a caller
+stops it, or `maxIterations` is reached. Everything that *happens* as a result is
+a callback you supply.
+
+```ts
+import { runToolLoop, type ToolLoopState } from "@juno-ai/bind/loop";
+
+const state: ToolLoopState = {
+  messages: [systemMessage, userMessage],
+  inputTokens: 0,
+  outputTokens: 0,
+  costCents: 0,
+  lastPromptTokens: 0,
+  lastOutputTokens: 0,
+  hasFreshTokenCount: false,
+  toolCalls: 0,
+};
+
+await runToolLoop({
+  state,
+  activePlugins,
+  maxIterations: 30,
+
+  callModel: (messages, tools) => llm.complete({ messages, tools }),
+  buildTools: () => registry.toolDefinitions([...activePlugins]),
+  runToolCall: (call) => dispatch(call),
+  activatePlugins: (names) => names.forEach((n) => activePlugins.add(n)),
+  activateSkills: (refs) => loadInstructions(refs),
+});
+
+// `state` is mutated in place — read totals off it after, or mid-run from a
+// heartbeat.
+console.log(state.inputTokens, state.outputTokens, state.toolCalls);
+```
+
+`state` is mutated rather than returned so a heartbeat can read live totals while
+the run is still going; a returned result could not report anything until the
+run ended.
+
+### How to make a tool take effect mid-batch
+
+A model can request several tools at once, and one of them may change what the
+others can do — activating a plugin, loading an instruction module. Those must
+run first, alone, or a dependent call in the same batch executes against the old
+tool surface.
+
+```ts
+runsSerially: (call) =>
+  call.type === "function" && ACTIVATION_TOOLS.has(call.function.name),
+```
+
+The loop runs those one at a time, applies each outcome immediately, then fans
+the rest out concurrently (pooled per tool name). Outcomes are reassembled in the
+model's original order either way — every `tool_call_id` gets its answer in the
+sequence the provider expects.
+
+Unwired, nothing is serial. That is correct for a host whose tools do not reshape
+the tool surface, and wrong the moment one does.
+
+### How to decide which tool failures kill the run
+
+By default a thrown tool becomes a tool error the model can read and recover
+from, which is what you want for an isolated failure. Two kinds are not that:
+
+```ts
+isFatalToolError: (error) =>
+  error instanceof RunCancelledError ||   // must abort, not be answered
+  error instanceof PersistenceError,      // we could not RECORD the outcome
+```
+
+Cancellation has to propagate even when no `ensureNotCancelled` observer is
+wired. A persistence failure matters for a subtler reason: synthesizing "the tool
+failed" over a write you could not record tells the model a lie about work that
+may well have happened.
+
+Everything not fatal is answered and observed:
+
+```ts
+onToolCallRejected: (toolCallId, error) => log.warn("tool rejected", { toolCallId, error }),
+```
+
+Wire it. The model sees these failures either way; without the observer, nothing
+else does.
+
 ### How to pin a model to one provider
 
 Use a hard `only` fence. Plan-time filtering and runtime traversal both respect
@@ -284,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
@@ -427,9 +607,11 @@ 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/contracts` | Turn vocabulary — `TurnFn`, `ModelTurnResult`, `StopReason`, `RunStats` | You want one seam between your loop and any LLM client, and comparable per-run metrics |
-| `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling | A run must be bounded, observable, and able to say *why* it stopped |
+| `@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 |
 | `@juno-ai/bind/transcript` | `validateAndHealMessages` | You send transcripts to more than one provider, or you build them across turns |
 | `@juno-ai/bind/tools` | `sanitizeToolSchema` | Any tool schema reaches a provider — especially third-party ones |
 | `@juno-ai/bind/plugins` | Tool/plugin vocabulary, the registry factory, progressive-disclosure activation | You have more tools than fit comfortably in one prompt |
@@ -462,6 +644,20 @@ tenant's revoked key opens the circuit for every tenant sharing that
 60 s ceiling including `Retry-After` extensions. Resolve a half-open probe that
 ended without a recordable outcome via `releaseProbe`, or the slot sticks.
 
+**Run — a child is admitted before it exists, never after.** `admitChildRun`
+judges counts you supply; call it ahead of enqueuing. A chain bounded only once
+its runs are on the queue is not bounded, it is billed. A rule whose measurement
+is `NaN` or `Infinity` refuses rather than admits — every comparison is false
+against `NaN`, so the naive reading of a broken count is an unbounded chain.
+
+**Run — chain lineage is "null means me".** A root run's `rootRunId` and
+`parentRunId` are both `null`, because a chain's origin has no id to point at
+until its own row exists. Read any chain's root as `chain.rootRunId ?? runId`;
+`descendChain` does that when it hands the id down, so every descendant carries
+a concrete root. Adopting the parent's id at *every* level instead makes each
+generation a fresh chain, and every per-chain bound then counts the wrong set
+and silently never fires.
+
 **Run — whoever classifies the outcome owns the deadline.** `timedOut` reflects
 *that* deadline firing, and stays false when only a combined external signal
 aborts — which is what separates a timeout from a cancellation. Handle
@@ -675,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 {
@@ -688,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`
 
@@ -865,14 +1065,13 @@ try {
 
 ### Spawning child runs (sub-agents)
 
-> **Not in the harness yet.** There is no sub-agent, spawn, or child-run concept
-> in `bind` today — the vocabulary below is yours to define. The admission
-> policy is a planned addition; see [Roadmap](#roadmap).
-
 A sub-agent is not a special kind of thing. It is **a run that another run
 asked for**, so everything the harness already gives a run applies unchanged:
 its own deadline, its own heartbeat, its own `RunStats`, its own route plan.
-Only three things are genuinely new, and all three are currently yours.
+Three things are genuinely new — lineage, admission, and waiting — and
+`@juno-ai/bind/run` owns the decision in each. It owns none of the measuring:
+counting runs in a chain needs your database, and judging whether a count is
+too high does not.
 
 **1. The spawn tool is an ordinary plugin.** Nothing special is needed here —
 the tool vocabulary is already shared.
@@ -892,10 +1091,10 @@ const orchestration: ToolPlugin<Ctx> = {
   async execute(toolName, args, ctx) {
     const { objective, plugins } = spawnArgsSchema.parse(args);
 
-    const admission = await admitChildRun(
-      { depth: ctx.chainDepth, chainId: ctx.chainId, parentKey: ctx.runKey },
-      BOUNDS,
-    );
+    const admission = admitChildRun([
+      { kind: "depth", parentDepth: ctx.chain.depth, maxDepth: 5 },
+      { kind: "chain_budget", runsInChain: await countRuns(ctx.chain), maxRuns: 50 },
+    ]);
     if (!admission.admitted) {
       return { success: false, kind: "validation", error: admission.reason };
     }
@@ -903,9 +1102,7 @@ const orchestration: ToolPlugin<Ctx> = {
     const childRunId = await queue.enqueueRun({
       objective,
       plugins,
-      chainId: ctx.chainId,
-      depth: ctx.chainDepth + 1,
-      parentRunId: ctx.runId,
+      chain: descendChain(ctx.runId, ctx.chain),
     });
     return { success: true, data: { childRunId } };
   },
@@ -914,34 +1111,47 @@ const orchestration: ToolPlugin<Ctx> = {
 
 **2. Admission is the part worth getting right.** An agent that can spawn can
 spawn agents that spawn. Bound it *before* enqueuing, not after — an unbounded
-chain is a runaway spend, and the failure mode is silent. The counting needs
-your database; the deciding does not.
+chain is a runaway spend, and the failure mode is silent.
 
-```ts
-type Admission = { admitted: true } | { admitted: false; reason: string };
+Each rule carries its limit **and** the measurement it judges, so a bound you
+configure but never wired a count for is not expressible. That shape exists
+because the alternative fails quietly: a bounds object beside a facts object
+lets a limit sit in config and never fire, and nothing looks wrong.
 
-async function admitChildRun(chain: Chain, bounds: Bounds): Promise<Admission> {
-  if (chain.depth >= bounds.maxDepth) {
-    return { admitted: false, reason: `chain depth limit reached (${chain.depth}/${bounds.maxDepth})` };
-  }
-  if (await countRunsInChain(chain.chainId) >= bounds.maxRunsPerChain) {
-    return { admitted: false, reason: "chain run budget exhausted" };
-  }
-  if (Date.now() - (await lastSpawnBetween(chain.parentKey)) < bounds.pairCooldownMs) {
-    return { admitted: false, reason: "spawn cooldown active" };
-  }
-  return { admitted: true };
+```ts
+import { admitChildRun, descendChain, type ChainRule } from "@juno-ai/bind/run";
+
+const rules: ChainRule[] = [
+  { kind: "depth", parentDepth: chain.depth, maxDepth: 5 },
+  { kind: "chain_budget", runsInChain: await countRunsInChain(chain), maxRuns: 50 },
+  { kind: "pair_cooldown", msSinceLastSpawn: await msSinceLastSpawn(runId), cooldownMs: 30_000 },
+  { kind: "tenant_ceiling", activeRuns: await countActiveRuns(tenantId), maxActiveRuns: 200 },
+];
+
+const admission = admitChildRun(rules);
+if (!admission.admitted) {
+  log.warn("child run refused", { rule: admission.rule });
+  return { success: false, kind: "validation", error: admission.reason };
 }
 ```
 
-Pick bounds against your own cost model. Depth caps runaway recursion; a
-per-chain run budget caps total spend once a chain starts; a pair cooldown stops
-two agents ping-ponging. A separate per-tenant ceiling on *directly triggered*
-runs is worth having too — depth limits do not constrain someone starting a
-thousand independent runs.
+Rules are evaluated in order and the first refusal wins, so you choose which
+reason the model sees. Pick the set against your own cost model: depth caps
+runaway recursion, a chain budget caps a chain that stays shallow but keeps
+fanning out, a pair cooldown stops two runs ping-ponging, and a tenant ceiling
+covers what none of the chain rules can — someone starting a thousand
+independent chains. A broken measurement (`NaN`, `Infinity`) refuses rather
+than admits: every comparison is false against `NaN`, so the naive reading
+would turn a broken count into an unbounded chain.
+
+`descendChain` handles the lineage arithmetic, including the root-id fallback
+that is easy to get backwards — a first-generation child adopts its parent's
+*id* as the chain root, later generations keep the root the parent already
+carries. Getting that wrong makes every generation its own chain, and every
+per-chain bound then counts the wrong set and never fires.
 
-**3. Waiting, and rolling results up.** Two shapes work. Suspend the parent and
-let child completion wake it, which frees the worker slot:
+**3. Waiting.** Two shapes work. Suspend the parent and let child completion
+wake it, which frees the worker slot:
 
 ```ts
 return {
@@ -952,27 +1162,51 @@ return {
 ```
 
 …or poll inside the tool, which keeps the parent's transcript intact but holds
-its slot — so cap the poll well under the parent's deadline.
+its slot — so budget the poll well under the parent's own deadline.
+`createPollSchedule` is a doubling backoff bounded by that budget; it clamps
+the final delay so a sleep can never overshoot the deadline you promised.
 
-For accounting, note that `accumulateTurn` and `accumulateToolCall` fold a
-run's *own* activity; there is no built-in roll-up across child runs. Sum them
-yourself if a chain's total cost is a number you report:
+```ts
+import { createPollSchedule } from "@juno-ai/bind/run";
+
+const startedAt = Date.now();
+const poll = createPollSchedule({
+  initialDelayMs: 500,
+  maxDelayMs: 30_000,
+  budgetMs: 10 * 60_000,
+});
+
+while (true) {
+  const children = await loadChildRuns(childRunIds);
+  if (children.every((c) => c.finished)) return { success: true, data: { children } };
+
+  const step = poll.next(Date.now() - startedAt);
+  if (step.kind === "expired") {
+    return { success: true, data: { children, timedOut: true } };
+  }
+  await sleep(step.delayMs, signal);
+}
+```
+
+Elapsed time is an argument rather than something the schedule reads off a
+clock, so a test can drive the whole backoff without waiting for any of it.
+
+**4. Rolling results up.** `accumulateTurn` and `accumulateToolCall` fold a
+run's *own* activity; `accumulateRun` folds one whole run into another, which
+is what a chain's totals are made of.
 
 ```ts
-const chainTotals = [parentStats, ...childStats].reduce((acc, s) => ({
-  ...acc,
-  turns: acc.turns + s.turns,
-  toolCalls: acc.toolCalls + s.toolCalls,
-  inputTokens: acc.inputTokens + s.inputTokens,
-  outputTokens: acc.outputTokens + s.outputTokens,
-  costCents: acc.costCents + s.costCents,
-  modelTimeMs: acc.modelTimeMs + s.modelTimeMs,
-  toolTimeMs: acc.toolTimeMs + s.toolTimeMs,
-}), emptyRunStats());
+import { accumulateRun, emptyRunStats } from "@juno-ai/bind/contracts";
+
+const chainTotals = childStats.reduce(accumulateRun, parentStats);
 ```
 
-Model time will exceed wall-clock once children run in parallel — that is
-correct, and it is why the two are tracked separately.
+The fold is associative, so a chain reduces in whatever order its children
+finish. Two properties are worth expecting rather than debugging: `modelTimeMs`
+will exceed the chain's wall-clock once children run in parallel (the sum is
+what the chain *cost*, not how long it took), and `outputTokensPerSecond` is
+recomputed from the merged totals rather than averaged across runs — averaging
+two rates weights a 10-token run like a 10,000-token one.
 
 ---
 
@@ -981,13 +1215,12 @@ correct, and it is why the two are tracked separately.
 Named, not scheduled. Listed so a consumer can tell a deliberate omission from
 an oversight.
 
-- **The turn kernel** — `runAgent` / `advanceTurn` over `TurnFn`. The loop
-  itself is still yours.
-- **Sub-agent admission** — the depth / chain-budget / cooldown policy
-  sketched [above](#spawning-child-runs-sub-agents), as a pure decision over
-  injected counts. The queue, the persistence, and the bounds stay yours.
-- **Child-run stats roll-up** — an `accumulateRun` fold so a chain's totals do
-  not have to be summed by hand.
+- **One `RunStats` per turn.** The loop accounts usage with `ToolLoopTurn`
+  (tokens and cost) while `ModelTurnResult` carries timings too. They converge
+  when the loop folds `RunStats` directly; today a host that wants throughput
+  metrics accumulates them alongside.
+- **A streaming turn contract.** `callModel` reports an output-token estimate
+  mid-stream; the assistant message itself still arrives whole.
 
 ---
 

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;