@gtrabanco/pi-nan-provider 1.0.0 → 1.0.1

package/README.md

@@ -327,12 +327,14 @@ Chat models:
 | :--- | :--- | :--- | :--- | :---: |
 | `qwen3.6` | 262,144 | 65,536 | text, image | ✅ |
 | `gemma4` | 262,144 | 32,768 | text, image | ✅ |
-| `deepseek-v4-flash` | 1,000,000 | 384,000 | text, image | ✅ |
+| `deepseek-v4-flash` | 1,000,000 | 32,768* | text, image | ✅ |
 | `mimo-v2.6-flash` | 1,048,576 | 131,072 | text, image | ✅ |
 | `glm5.3-flash` | 1,000,000 | 131,072 | text, image | ✅ |
 | `qwen3.8-flash` | 262,144 | 131,072 | text, image | ✅ |
 
 > [!NOTE]
+> `*` deepseek-v4-flash max output 32,768 is the ceiling from the official NaN pi docs (https://nan.builders/docs/pi, "the same set the NaN CLI writes", issue #20, 2026-10-02); models.dev still lists 384,000 but the gateway rejects `max_tokens` above ~256k with 403.
+>
 > **Cold prompt cache practical ceiling (issue #18).** The context windows above are the models' real windows, but the api.nan.builders edge (Cloudflare) aborts responses past its 120 s Proxy Read Timeout. Measured with direct cold requests (unique filler, no prompt cache; 2026-10-01): 208,036 tokens (~960 KB body) answered in 12.9 s while ~220k and ~286k tokens returned **HTTP 524 `origin_response_timeout`** at ~126 s; the same sizes with a warm prompt cache answer in ~10 s. The practical ceiling for cold requests is therefore well below the declared windows. Since 1.0.0 the provider reclassifies a 524 on an estimated over-200,000-token request (`NAN_COLD_CACHE_CEILING_TOKENS`) as a context overflow so pi compacts and retries instead of wedging; a 524 on a smaller request is left alone (genuine transient timeout).
 
 Non-chat image models (available through `models.generateImages()` /

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",

package/scripts/manual-overrides.ts

@@ -141,10 +141,12 @@ export const MANUAL_ONLY_MODELS: Record<string, ManualModelOverride> = {
 export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
 	"deepseek-v4-flash": {
 		input: ["text", "image"],
+		maxTokens: 32_768,
 		reasoningEffortValues: ["none"],
 		thinkingLevelMap: { off: "none" },
 		note:
 			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. " +
+			"maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. " +
 			"reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. " +
 			"thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
 	},

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-02T00:02:21.641Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-02T22:53:40.291Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -27,7 +27,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"cacheWrite": 0
 		},
 		"contextWindow": 1000000,
-		"maxTokens": 384000,
+		"maxTokens": 32768,
 		"reasoningEffortValues": [
 			"none"
 		],
@@ -43,7 +43,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		},
 		"notes": [
 			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
-			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode."
+			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode."
 		],
 		"extras": {
 			"id": "deepseek-v4-flash",
@@ -455,7 +455,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-10-02T00:02:21.641Z",
+	fetchedAt: "2026-10-02T22:53:40.291Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [
@@ -469,7 +469,7 @@ export const GENERATED_CATALOG_META = {
 	"non-chat: \"whisper\" excluded from the chat catalog (speech-to-text (STT) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
 	"non-chat: \"flux-2-klein\" excluded from the chat catalog (image generation endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
 	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
-	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
+	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. maxTokens 32768 per the official NaN pi docs (https://nan.builders/docs/pi, 'the same set the NaN CLI writes', checked 2026-10-02) closing issue #20 — the gateway now rejects max_tokens above ~256k for this model with 403 permission_error (measured 2026-10-02: 256,000 → 200; 262,143 → 403), and the previous models.dev-derived 384000 made every pi request fail since pi-ai sends max_tokens = model.maxTokens when no cap is set. models.dev still lists 384000, so this override pins the documented value. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
 	"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter gemma4 defaults to reasoning ON (16,384-token budget), while `none`/`minimal` skip reasoning entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",
 	"thinkingLevelMap { off: \"minimal\" } (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"minimal\" supplies the effort so the gateway receives reasoning_effort:\"minimal\" (38 reasoning tokens + answer). Note: \"none\" does NOT suppress reasoning on glm5.3-flash (13,382 tokens) — only \"minimal\" was measured to be effective. reasoning_effort_values includes \"minimal\" (not documented by NaN docs but accepted and effective by the gateway, issue #16).",
 	"manual-only: \"mimo-v2.6-flash\" skipped: models.dev provider \"nan\" now lists it, so the manual-only entry is not emitted and the models.dev values are used (omnimodal model (text, image, audio input) served by NaN; limits and modalities from https://nan.builders/docs/models#mimo-v2-6-flash (checked 2026-09-25, quotas re-checked 2026-09-29): 1,048,576 context / 131,072 max output / 1.0B monthly quota per member. Reasoning: accepted, depth not adjustable (docs table, checked 2026-09-29). Tool calling: yes. Streaming: yes. Input modalities (pi-representable): text, image (audio not representable in pi's Model type). Fallback entry: emitted only while models.dev provider nan does not list the model — models.dev started listing it on 2026-09-29, so the generator then keeps the models.dev values and attaches this note to that entry instead of emitting a second one.)",

package/src/provider-factory.ts

@@ -37,6 +37,7 @@ import type {
 	RefreshModelsContext,
 } from "@earendil-works/pi-ai";
 import { withContextOverflowClassification } from "./context-overflow-classifier.ts";
+import { withReasoningOnlyStreamGuard } from "./reasoning-only-stream-guard.ts";
 import { NAN_IMAGE_API, baselineImageModels, createNanImagesApi } from "./images.ts";
 import {
 	baselineModels,
@@ -248,13 +249,19 @@ export async function createNanCompatibleProvider(
 				const current = liveIds;
 				return current ? models.filter((model) => current.has(model.id)) : models;
 			},
-			// Sanitize the payload for NaN's strict schema, then classify an opaque
-			// generic 400 as a context overflow when the request we just sent was over
-			// the model's window. The second layer keeps a replayed cross-model
-			// reasoning trace (or any other over-window request the context-hook guard
-			// cannot reach, e.g. NAN_THINKING_GUARD=0) recoverable instead of wedging
-			// the session — see src/context-overflow-classifier.ts.
-			api: withContextOverflowClassification(wrapApiForStrictSanitization(apiFactory())),
+			// Sanitize the payload for NaN's strict schema, then wrap a guard that
+			// detects NaN's reasoning-only stream closure marker and rewrites the
+			// terminal message so pi-ai retries it as a retryable error (issue #21).
+			// Finally, classify an opaque generic 400 as a context overflow when
+			// the request we just sent was over the model's window (issue #3).
+			//
+			// Composition order: outermost → classifier (error rewrites),
+			// middle → guard (marker detection), innermost → sanitizer (payload).
+			// The guard's onProviderStreamEvent hook sees the raw response chunks
+			// (NOT onPayload, which only receives the outgoing request params).
+			api: withContextOverflowClassification(
+				withReasoningOnlyStreamGuard(wrapApiForStrictSanitization(apiFactory())),
+			),
 		}),
 		overlayMap,
 	);

package/src/reasoning-only-stream-guard.ts

@@ -0,0 +1,201 @@
+/**
+ * NaN reasoning-only stream guard (issue #21).
+ *
+ * Problem: NaN's gateway closes a streaming turn that produced ONLY reasoning
+ * (no content, no tool calls) at 60,000 reasoning chars or 420 seconds:
+ * `finish_reason: "length"` on an empty delta, followed by a final usage chunk
+ * (estimated, unbilled) carrying `nan_truncation: { reason: "reasoning_only_stream" }`.
+ * Through pi-ai this maps to `stopReason: "length"` with no text — indistinguishable
+ * from a real output-limit cut, never retried, and the turn is silently wasted.
+ *
+ * Solution: intercept the raw stream chunks via the `onProviderStreamEvent`
+ * hook (pi-ai's openai-completions calls `options?.onProviderStreamEvent?.(chunk,
+ * model)` for every raw chunk — including the final usage-only chunk, which is
+ * where NaN attaches `nan_truncation`) and detect the
+ * `nan_truncation.reason === "reasoning_only_stream"` marker. When seen,
+ * rewrite the terminal message (both the async-iterator `done`/`error` events and
+ * `result()`) to `stopReason: "error"` with an errorMessage containing the word
+ * "timeout", so pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN` treats it as retryable.
+ *
+ * The rewrite is **never** applied when the marker was not observed on that stream —
+ * a legitimate `length` (real output cut with content) and the issue-#16 runaway
+ * `length` (no marker) must pass through untouched.
+ *
+ * Composition: `withReasoningOnlyStreamGuard` is the **innermost** of the three
+ * wrapper layers in `src/provider-factory.ts` (inside both the sanitizer and the
+ * overflow classifier) so that:
+ * 1. The sanitizer still runs first (payload goes out clean).
+ * 2. The classifier's error rewrites still apply on top of our rewrite.
+ * 3. The guard's marker detection runs on the *raw* chunk.
+ *
+ * NOTE: the observation hook MUST be `onProviderStreamEvent` (response chunks),
+ * NOT `onPayload` — `onPayload` receives the OUTGOING request params
+ * (openai-completions.js:188) and would never carry `nan_truncation`.
+ *
+ * In practice, the composition line is:
+ * ```
+ * withContextOverflowClassification(
+ *   withReasoningOnlyStreamGuard(
+ *     wrapApiForStrictSanitization(apiFactory())
+ *   )
+ * )
+ * ```
+ */
+
+import type {
+	AssistantMessage,
+	AssistantMessageEventStream,
+	ProviderStreams,
+} from "@earendil-works/pi-ai";
+
+/** The JSON key under which NaN attaches the truncation metadata. */
+export const NAN_TRUNCATION_MARKER = "nan_truncation";
+
+/** The value of `reason` when NaN closes a reasoning-only stream. */
+export const REASONING_ONLY_STREAM_REASON = "reasoning_only_stream";
+
+/**
+ * Check whether a raw stream chunk carries the reasoning-only stream marker.
+ *
+ * Pure function — useful for unit tests and for reasoning about chunk shapes
+ * without needing the full guard wrapper.
+ */
+export function isReasoningOnlyStreamChunk(chunk: unknown): boolean {
+	if (typeof chunk !== "object" || chunk === null) return false;
+	const obj = chunk as Record<string, unknown>;
+	const truncation = obj[NAN_TRUNCATION_MARKER];
+	if (typeof truncation !== "object" || truncation === null) return false;
+	return (truncation as Record<string, unknown>)?.reason === REASONING_ONLY_STREAM_REASON;
+}
+
+/** The rewrite applied to a terminal message when the marker was observed. */
+const REASONING_ONLY_REWRITE: Partial<AssistantMessage> = {
+	stopReason: "error" as const,
+	errorMessage:
+		"NaN timed out the stream before any answer content (reasoning-only stream guard: 420 s / 60,000-character limit; the turn was not billed). Original finish_reason: length.",
+};
+
+/**
+ * Rewrite the terminal assistant message when the reasoning-only stream marker
+ * was observed during this stream.  Only rewrites when `stopReason === "length"`
+ * AND the marker was set — everything else passes through untouched.
+ *
+ * Mutates and returns the same message object so that both the async-iterator
+ * consumers and `result()`-only consumers see the rewrite (pi-ai yields the
+ * same object through the `"done"` event's `message` field and through `result()`).
+ */
+function rewriteReasoningOnlyMessage(
+	message: AssistantMessage | undefined,
+	observedMarker: boolean,
+): AssistantMessage | undefined {
+	if (!observedMarker || !message) return message;
+	if (message.stopReason !== "length") return message;
+
+	// Only rewrite a terminal "length" that came with the nan_truncation marker.
+	// Preserve all existing fields: reasoning/thinking blocks, usage, responseId.
+	message.stopReason = "error";
+	message.errorMessage = REASONING_ONLY_REWRITE.errorMessage!;
+	return message;
+}
+
+/**
+ * Wrap a stream so its terminal message is rewritten when the reasoning-only
+ * stream marker was observed. Uses a Proxy to intercept both the async-iterator
+ * `"error"`/`"done"` events and the `result()` call, mirroring the
+ * `classifyStreamContextOverflow` technique.
+ */
+function rewriteStream(
+	stream: AssistantMessageEventStream,
+	observedMarker: () => boolean,
+): AssistantMessageEventStream {
+	const rewrite = (message: AssistantMessage | undefined): AssistantMessage | undefined =>
+		rewriteReasoningOnlyMessage(message, observedMarker());
+	const resultPromise = stream.result().then(rewrite);
+
+	return new Proxy(stream, {
+		get(target, property, receiver) {
+			if (property === "result") return () => resultPromise;
+			if (property === Symbol.asyncIterator) {
+				return () => {
+					const iterator = target[Symbol.asyncIterator]();
+					return {
+						async next() {
+							const step = await iterator.next();
+							if (!step.done && step.value?.type === "error") rewrite(step.value.error);
+							return step;
+						},
+						async return(value?: unknown) {
+							return iterator.return ? iterator.return(value) : { done: true, value };
+						},
+						async throw(error?: unknown) {
+							if (iterator.throw) return iterator.throw(error);
+							throw error;
+						},
+						[Symbol.asyncIterator]() {
+							return this;
+						},
+					};
+				};
+			}
+			const value = Reflect.get(target, property, receiver);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	}) as AssistantMessageEventStream;
+}
+
+/**
+ * Wrap every `stream`/`streamSimple` call so a NaN reasoning-only stream that
+ * terminates with `stopReason: "length"` (but carries the
+ * `nan_truncation.reason: "reasoning_only_stream"` marker) is surfaced as a
+ * retryable error instead of a silent waste.
+ *
+ * The guard chains an `onProviderStreamEvent` hook that detects the raw chunk
+ * marker and sets a closure-local flag. The `done` event's `message` and the
+ * `result()` promise both receive the rewritten terminal message.
+ *
+ * Any caller-supplied `onProviderStreamEvent` is preserved and chained **after**
+ * the guard's marker detection, so the caller always sees the same chunks it
+ * would have without the guard — the guard only reads, never mutates the chunk.
+ *
+ * @see src/provider-factory.ts for composition
+ * @see Issue #21
+ */
+export function withReasoningOnlyStreamGuard(api: ProviderStreams): ProviderStreams {
+	return {
+		...api,
+		stream: (model, context, options) => {
+			let observedMarker = false;
+			const withGuardedOptions = { ...((options ?? {}) as Record<string, unknown>) };
+
+			const userOnStreamEvent = withGuardedOptions.onProviderStreamEvent;
+			withGuardedOptions.onProviderStreamEvent = async (chunk: unknown, modelHint: unknown) => {
+				if (isReasoningOnlyStreamChunk(chunk)) {
+					observedMarker = true;
+				}
+				if (typeof userOnStreamEvent === "function") {
+					await userOnStreamEvent(chunk, modelHint);
+				}
+			};
+
+			const stream = api.stream(model, context, withGuardedOptions as typeof options);
+			return rewriteStream(stream, () => observedMarker);
+		},
+		streamSimple: (model, context, options) => {
+			let observedMarker = false;
+			const withGuardedOptions = { ...((options ?? {}) as Record<string, unknown>) };
+
+			const userOnStreamEvent = withGuardedOptions.onProviderStreamEvent;
+			withGuardedOptions.onProviderStreamEvent = async (chunk: unknown, modelHint: unknown) => {
+				if (isReasoningOnlyStreamChunk(chunk)) {
+					observedMarker = true;
+				}
+				if (typeof userOnStreamEvent === "function") {
+					await userOnStreamEvent(chunk, modelHint);
+				}
+			};
+
+			const stream = api.streamSimple(model, context, withGuardedOptions as typeof options);
+			return rewriteStream(stream, () => observedMarker);
+		},
+	};
+}