@juno-ai/bind 4.0.0 → 6.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,126 @@ 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 read the arguments of a tool call the model asked for
+
+`JSON.parse(toolCall.function.arguments)` is the obvious implementation and it
+is wrong for the commonest tool there is. Providers send `""` for a
+**zero-argument** call as readily as `"{}"`, so the obvious version kills a
+perfectly good call as a JSON syntax error and burns a recovery turn on a turn
+that was never broken.
+
+```ts
+import { parseToolCallArguments } from "@juno-ai/bind/completion";
+
+const read = parseToolCallArguments(toolCall);
+switch (read.kind) {
+  case "parsed":
+    return dispatch(toolCall.function.name, read.arguments);
+  case "unsupported_type":
+    return toolMessage(toolCall.id, `Unsupported tool call type: ${read.type}`);
+  case "unparseable":
+    // Put `detail` in front of the MODEL, not only in a log — its next turn is
+    // the only thing that can correct the arguments.
+    return toolMessage(toolCall.id, `Invalid tool arguments: ${read.detail}`);
+}
+```
+
+Every outcome is a value, not a throw, because every outcome has to end with a
+`tool` message carrying this call's id — a transcript where an assistant asked
+for a tool and nothing answered it is rejected by the provider on the *next*
+request, so "give up on this call" was never an option.
+
+Valid JSON that is not an object — `null`, `[]`, `42` — is refused rather than
+dispatched. Tool arguments are a named parameter bag by definition, and handing
+a tool an array where it expects fields turns a clear failure here into a
+confusing one inside the tool, after any side effect it performs before its own
+validation.
+
+### 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 +642,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, the tool-call argument read (`parseToolCallArguments`), 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 |
@@ -564,6 +685,22 @@ 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 — "could not measure" is an omission, never a sentinel.** The refusal
+above is for a count you *did* supply and that came back broken. A bound you
+could not measure at all — the query threw, the counter was unreachable — is
+expressed by leaving that rule out of the array, which admits. The two are
+opposite answers to opposite questions, and passing `NaN` for "unknown" turns a
+transient database blip into every agent in your system refusing to run. Which
+of the two a given failure is is yours to decide; the harness only judges what
+it was handed.
+
+**Completion — the zero-argument rule has two halves and they must agree.**
+`detectCompletionDefect` decides a tool call with *empty* arguments is
+legitimate and passes it through; `parseToolCallArguments` is what then reads
+it as the zero-argument call it is. Both read one `toolCallArgumentsAbsent`, so
+adopting only the detection half means independently reinventing the matching
+parse — and getting it wrong the way everyone does, with a bare `JSON.parse`.
+
 **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`;
@@ -785,7 +922,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 +943,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`
 
@@ -1034,13 +1175,15 @@ 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_seen", alreadyPaired: await hasPairedInChain(chain, targetId) },
   { kind: "pair_cooldown", msSinceLastSpawn: await msSinceLastSpawn(runId), cooldownMs: 30_000 },
+  { kind: "tenant_rate", runsInWindow: await countRecentRuns(tenantId), maxRuns: 100, windowMs: 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 });
+  log.warn("child run refused", { rule: admission.rule, retryable: admission.retryable });
   return { success: false, kind: "validation", error: admission.reason };
 }
 ```
@@ -1048,11 +1191,25 @@ if (!admission.admitted) {
 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.
+fanning out, `pair_seen` allows a given pair to work together once per chain
+and a `pair_cooldown` merely spaces them out, a tenant rate limit bounds a burst
+over a rolling window, and a tenant ceiling bounds what is running *right now* —
+the last two covering what no chain rule can, someone starting a thousand
+independent chains.
+
+A refusal carries `rule` (which bound fired) and `retryable`, which separates a
+bound that clears on its own — a cooldown, a rate window rolling — from one that
+never will, so a caller can choose between waiting and giving up. Only a
+refusal carries them; `retryable === undefined` means there was nothing to
+retry, not "not retryable".
+
+Two failure modes get opposite treatment, and the difference is the part to get
+right. A **broken measurement** (`NaN`, `Infinity`, a negative count) refuses:
+every comparison is false against `NaN`, so the naive reading would turn a
+broken count into an unbounded chain. A bound you **could not measure at all**
+— the count query threw — is expressed by *omitting the rule*, which admits.
+Reaching for `NaN` to mean "unknown" collapses the two and makes a transient
+database blip refuse every child run you have.
 
 `descendChain` handles the lineage arithmetic, including the root-id fallback
 that is easy to get backwards — a first-generation child adopts its parent's

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,130 @@
+/**
+ * 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.
+ */
+import { toolCallArgumentsAbsent } from "./tool-calls.js";
+/**
+ * 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;
+            // The same predicate the dispatcher reads, so the two halves of the
+            // zero-argument rule cannot drift — see `tool-calls.ts`.
+            if (toolCallArgumentsAbsent(args))
+                return cutByTokenLimit;
+            return !jsonParses(args.trim());
+        });
+        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,3 @@
+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";
+export { parseToolCallArguments, toolCallArgumentsAbsent, type DispatchableToolCall, type ToolCallArguments, } from "./tool-calls.js";

package/completion/index.js

@@ -0,0 +1,3 @@
+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";
+export { parseToolCallArguments, toolCallArgumentsAbsent, } from "./tool-calls.js";

package/completion/tool-calls.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reading a tool call the model asked for.
+ *
+ * This is the dispatch half of a rule whose other half lives in
+ * `defects.ts`, and the two only work if they agree. `detectCompletionDefect`
+ * decides that a tool call with *empty* arguments is legitimate — the normal
+ * zero-argument shape, not a truncation — and passes it through to be run.
+ * Something then has to run it, and that something has to reach the same
+ * conclusion: empty arguments mean no arguments, not malformed JSON.
+ *
+ * Splitting those halves across a package boundary is how the original bug
+ * happened. Providers send `""` for a zero-arg call as readily as `"{}"`, the
+ * dispatcher fed `""` to `JSON.parse`, and a perfectly good call died as
+ * "Invalid JSON in tool arguments" — a whole recovery turn spent on a turn
+ * that was never broken. A host adopting only the detection half inherits the
+ * permissive decision and has to independently invent the matching parse.
+ *
+ * So both halves read {@link toolCallArgumentsAbsent}. One definition, and a
+ * change to what "absent" means cannot update one side and miss the other.
+ */
+/**
+ * The shape this module reads. Structural rather than tied to an SDK's class,
+ * and `type` is optional because a host assembling calls by hand may not carry
+ * one — its absence is treated as the ordinary function call it almost always
+ * is, while a *present* non-function type is refused.
+ */
+export interface DispatchableToolCall {
+    readonly type?: string | undefined;
+    readonly function?: {
+        readonly name?: string | undefined;
+        readonly arguments?: string | undefined;
+    } | undefined;
+}
+/**
+ * Whether a tool call carried no arguments at all.
+ *
+ * Whitespace counts as absent: a provider that pads its zero-arg payload is
+ * still saying "no arguments", and treating `"  "` as content sends it to a
+ * JSON parse that can only fail.
+ */
+export declare function toolCallArgumentsAbsent(rawArguments: string): boolean;
+/**
+ * What a tool call's arguments turned out to be.
+ *
+ * A tagged union rather than a throw, because every outcome here has to end
+ * with the host emitting a `tool` message for this call's id. A transcript
+ * where an assistant asked for a tool and no `tool` message answers it is
+ * rejected by the provider on the *next* request, so "give up on this call"
+ * is never an option — only "dispatch it" or "answer it with an error".
+ */
+export type ToolCallArguments = 
+/** Dispatch with these. `{}` for a legitimate zero-argument call. */
+{
+    kind: "parsed";
+    arguments: Record<string, unknown>;
+}
+/**
+ * Not a function call, so there is nothing to dispatch. Present in the
+ * OpenAI union (`type: "custom"`) and in whatever a future provider adds.
+ */
+ | {
+    kind: "unsupported_type";
+    type: string;
+}
+/**
+ * Arguments that cannot be used: either not JSON at all, or JSON that is not
+ * an object.
+ *
+ * The two have different histories, which matters for how the host words the
+ * error. A *syntax* failure by this point is a real error rather than a
+ * truncation — a cut-off stream is caught upstream by
+ * `detectCompletionDefect` and retried, so anything still unparseable here
+ * survived that. A payload that parsed but is not an object was never
+ * eligible for that retry (it parses fine), so the model's next turn is its
+ * only correction — which is why {@link detail} names what was wrong, and
+ * why a host should put it in front of the model rather than only in a log.
+ */
+ | {
+    kind: "unparseable";
+    detail: string;
+};
+/**
+ * Read a tool call's arguments, or say why it cannot be dispatched.
+ *
+ * A parsed value that is not a JSON object — `"null"`, `"[]"`, `"42"`, all
+ * valid JSON — is refused rather than passed on. Tool arguments are a named
+ * parameter bag by definition, and handing a tool an array where it expects
+ * fields turns a clear failure here into a confusing one inside the tool.
+ */
+export declare function parseToolCallArguments(toolCall: DispatchableToolCall): ToolCallArguments;