190proof 1.0.110 → 1.0.112

package/README.md

@@ -278,6 +278,9 @@ Optional per-request knobs live on `payload` (`GenericPayload`):
 - `payload.requestTimeoutMs`: `number` - Per-attempt HTTP timeout in ms (default: 120000), honored by every adapter — except streaming OpenRouter attempts, which it deliberately does NOT bound (see below). For OpenRouter's non-streaming transport the default is 180000.
 - `payload.streaming`: `boolean` - OpenRouter-only (default: true). Streams the completion over SSE. A streaming attempt is bounded by two independent timers instead of `requestTimeoutMs`: `streamTimeoutMs` (total wall clock, default 600000) and the per-useful-chunk stall timeout (`chunkTimeoutMs` argument, default 15000). A chunk is "useful" only if it advances content, reasoning, tool-call fragments, finish_reason, or usage — SSE comment keep-alives (`: OPENROUTER PROCESSING`) and role-only deltas don't reset the stall timer, so a hung provider dies within one stall window while a healthy long generation can run to the total budget. Set `streaming: false` for the old single-JSON-body transport.
 - `payload.streamTimeoutMs`: `number` - OpenRouter-only: total wall-clock budget per streaming attempt (default: 600000).
+- `payload.streamDeadlineAt`: `number` - OpenRouter-only: absolute deadline (epoch ms) for the whole call **including retries** — the caller's turn budget. Each attempt gets `min(streamTimeoutMs, deadline - now)`, and once under 10s remain the call fails fast instead of starting a generation that cannot be delivered. Use it whenever the caller has its own timeout: a per-attempt budget alone is re-granted on every retry and can outlive that timeout.
+
+When a streaming attempt is cut at its **total deadline** and prose has already arrived, the partial answer is returned with `truncated: true` on the response rather than discarded — those tokens were generated and billed, so throwing them away costs money and gives the user nothing. Surface such a reply as incomplete. Salvage never applies to tool-call turns (half-streamed arguments are unparseable JSON), to stalls (the provider died mid-thought), or to caller aborts. When nothing is salvageable, the discard is logged with an approximate token count — aborted attempts never receive OpenRouter's `usage` chunk, so that log line is the only record of the wasted spend.
 
 OpenRouter retries also perform **moderation eviction**: a provider content-moderation rejection (e.g. "Upstream error from Alibaba: Output data may contain inappropriate content.") is deterministic for a given payload, so on the first one the refusing provider is removed from the request's provider preferences (`ignore` += slug, `order` -= slug) and every remaining attempt reroutes to the next provider. Non-moderation errors retry with unchanged preferences, and `fallbackModel` still applies if the whole pool refuses.
 - `payload.signal`: `AbortSignal` - Caller-supplied cancellation. When it aborts, the in-flight provider request is cancelled and `callWithRetries` **rejects immediately — it does not retry or fall back** (both the retry loop and the fallback branch bail on `signal.aborted`). Threaded to the underlying fetch/axios/SDK call of each provider.

package/dist/index.d.mts

@@ -184,6 +184,15 @@ interface ParsedResponseMessage {
      * mismatch with the requested model's provider reveals the fallback.
      */
     provider?: string;
+    /**
+     * True when the answer is INCOMPLETE: the streamed generation was cut at the
+     * caller's deadline and the partial prose is returned instead of discarded.
+     * Content is mid-sentence (or mid-file) by definition — surface it to the
+     * end user as truncated rather than presenting it as a finished answer.
+     * Never set on tool-call turns (a half-streamed arguments fragment can't be
+     * salvaged) and never on a normal completion.
+     */
+    truncated?: boolean;
     usage: {
         prompt_tokens: number;
         completion_tokens: number;
@@ -297,6 +306,19 @@ interface GenericPayload {
      * by chunks that advance the output, never by keep-alive bytes/comments).
      */
     streamTimeoutMs?: number;
+    /**
+     * OpenRouter-only: absolute wall-clock deadline (epoch ms) for the whole
+     * call INCLUDING retries — the caller's turn budget, not a per-attempt one.
+     * Each streaming attempt gets `min(streamTimeoutMs, deadline - now)`, and
+     * once too little time remains to be worth an attempt the call fails fast
+     * instead of starting a generation that cannot finish.
+     *
+     * Without it, a per-attempt budget is re-granted on every retry, so a slow
+     * generation can outlive the caller's own turn deadline and get killed with
+     * nothing to show (2026-07-28: a 538s completion finished just as the
+     * caller's 585s turn budget expired, and the reply was discarded).
+     */
+    streamDeadlineAt?: number;
     /**
      * Optional caller-supplied cancellation signal. When it aborts, the in-flight
      * provider request is cancelled and `callWithRetries` rejects immediately —
@@ -309,10 +331,16 @@ interface GenericPayload {
 
 declare const OPENROUTER_STREAM_TIMEOUT_MS = 600000;
 declare const OPENROUTER_NONSTREAM_TIMEOUT_MS = 180000;
+/**
+ * Least time a streaming attempt is worth starting with. Below this the
+ * generation cannot plausibly finish before the caller's deadline, so burning
+ * a provider call (and paying for tokens that get discarded) is pure waste.
+ */
+declare const MIN_STREAM_ATTEMPT_MS = 10000;
 declare function parseModelString(model: string): {
     provider: Provider;
     modelId: string;
 };
 declare function callWithRetries(id: string | string[], aiPayload: GenericPayload, aiConfig?: OpenAIConfig | AnthropicAIConfig, retries?: number, chunkTimeoutMs?: number): Promise<ParsedResponseMessage>;
 
-export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, OPENROUTER_NONSTREAM_TIMEOUT_MS, OPENROUTER_STREAM_TIMEOUT_MS, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };
+export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, MIN_STREAM_ATTEMPT_MS, OPENROUTER_NONSTREAM_TIMEOUT_MS, OPENROUTER_STREAM_TIMEOUT_MS, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };

package/dist/index.d.ts

@@ -184,6 +184,15 @@ interface ParsedResponseMessage {
      * mismatch with the requested model's provider reveals the fallback.
      */
     provider?: string;
+    /**
+     * True when the answer is INCOMPLETE: the streamed generation was cut at the
+     * caller's deadline and the partial prose is returned instead of discarded.
+     * Content is mid-sentence (or mid-file) by definition — surface it to the
+     * end user as truncated rather than presenting it as a finished answer.
+     * Never set on tool-call turns (a half-streamed arguments fragment can't be
+     * salvaged) and never on a normal completion.
+     */
+    truncated?: boolean;
     usage: {
         prompt_tokens: number;
         completion_tokens: number;
@@ -297,6 +306,19 @@ interface GenericPayload {
      * by chunks that advance the output, never by keep-alive bytes/comments).
      */
     streamTimeoutMs?: number;
+    /**
+     * OpenRouter-only: absolute wall-clock deadline (epoch ms) for the whole
+     * call INCLUDING retries — the caller's turn budget, not a per-attempt one.
+     * Each streaming attempt gets `min(streamTimeoutMs, deadline - now)`, and
+     * once too little time remains to be worth an attempt the call fails fast
+     * instead of starting a generation that cannot finish.
+     *
+     * Without it, a per-attempt budget is re-granted on every retry, so a slow
+     * generation can outlive the caller's own turn deadline and get killed with
+     * nothing to show (2026-07-28: a 538s completion finished just as the
+     * caller's 585s turn budget expired, and the reply was discarded).
+     */
+    streamDeadlineAt?: number;
     /**
      * Optional caller-supplied cancellation signal. When it aborts, the in-flight
      * provider request is cancelled and `callWithRetries` rejects immediately —
@@ -309,10 +331,16 @@ interface GenericPayload {
 
 declare const OPENROUTER_STREAM_TIMEOUT_MS = 600000;
 declare const OPENROUTER_NONSTREAM_TIMEOUT_MS = 180000;
+/**
+ * Least time a streaming attempt is worth starting with. Below this the
+ * generation cannot plausibly finish before the caller's deadline, so burning
+ * a provider call (and paying for tokens that get discarded) is pure waste.
+ */
+declare const MIN_STREAM_ATTEMPT_MS = 10000;
 declare function parseModelString(model: string): {
     provider: Provider;
     modelId: string;
 };
 declare function callWithRetries(id: string | string[], aiPayload: GenericPayload, aiConfig?: OpenAIConfig | AnthropicAIConfig, retries?: number, chunkTimeoutMs?: number): Promise<ParsedResponseMessage>;
 
-export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, OPENROUTER_NONSTREAM_TIMEOUT_MS, OPENROUTER_STREAM_TIMEOUT_MS, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };
+export { type AnyModel, ClaudeModel, type FunctionCall, type FunctionDefinition, GPTModel, GeminiModel, type GenericMessage, type GenericPayload, GroqModel, MIN_STREAM_ATTEMPT_MS, OPENROUTER_NONSTREAM_TIMEOUT_MS, OPENROUTER_STREAM_TIMEOUT_MS, type OpenAIConfig, OpenRouterModel, type OpenRouterProviderPreferences, type ParsedResponseMessage, type Provider, type ToolResult, callWithRetries, parseModelString };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(proof_exports, {
   GPTModel: () => GPTModel,
   GeminiModel: () => GeminiModel,
   GroqModel: () => GroqModel,
+  MIN_STREAM_ATTEMPT_MS: () => MIN_STREAM_ATTEMPT_MS,
   OPENROUTER_NONSTREAM_TIMEOUT_MS: () => OPENROUTER_NONSTREAM_TIMEOUT_MS,
   OPENROUTER_STREAM_TIMEOUT_MS: () => OPENROUTER_STREAM_TIMEOUT_MS,
   OpenRouterModel: () => OpenRouterModel,
@@ -1492,7 +1493,9 @@ async function callOpenRouterStream(id, payload, streamTimeoutMs = OPENROUTER_ST
   var _a, _b, _c, _d, _e, _f, _g;
   const controller = new AbortController();
   let abortReason = null;
-  const abortWith = (reason) => {
+  let abortKind = null;
+  const abortWith = (kind, reason) => {
+    abortKind = kind;
     abortReason = reason;
     controller.abort();
   };
@@ -1504,6 +1507,7 @@ async function callOpenRouterStream(id, payload, streamTimeoutMs = OPENROUTER_ST
   const totalTimer = unref(
     setTimeout(
       () => abortWith(
+        "deadline",
         `OpenRouter stream exceeded total deadline of ${streamTimeoutMs}ms`
       ),
       streamTimeoutMs
@@ -1515,6 +1519,7 @@ async function callOpenRouterStream(id, payload, streamTimeoutMs = OPENROUTER_ST
     stallTimer = unref(
       setTimeout(
         () => abortWith(
+          "stall",
           `OpenRouter stream stalled: no useful chunk for ${chunkTimeoutMs}ms`
         ),
         chunkTimeoutMs
@@ -1681,7 +1686,31 @@ async function callOpenRouterStream(id, payload, streamTimeoutMs = OPENROUTER_ST
     });
   } catch (error2) {
     if (abortReason && !(signal == null ? void 0 : signal.aborted)) {
-      logger_default.error(id, abortReason);
+      const kept = paragraph.trim();
+      if (abortKind === "deadline" && kept && !toolCalls.length) {
+        try {
+          const message = finalizeOpenRouterMessage(id, {
+            content: kept,
+            toolCalls: [],
+            reasoning,
+            reasoningDetails: reasoningDetails.length ? reasoningDetails : void 0,
+            provider,
+            usage,
+            forLog: () => JSON.stringify({ provider, kept: kept.slice(0, 500) })
+          });
+          message.truncated = true;
+          logger_default.log(
+            id,
+            `${abortReason} \u2014 returning truncated answer (${kept.length} chars, ~${estimateTokens(kept)} tokens kept)`
+          );
+          return message;
+        } catch (e) {
+        }
+      }
+      logger_default.error(
+        id,
+        `${abortReason} \u2014 discarding ~${estimateTokens(paragraph + reasoning)} generated tokens (content ${paragraph.length} chars, reasoning ${reasoning.length} chars, ${dataChunks} chunks)`
+      );
       throw new Error(abortReason);
     }
     throw error2;
@@ -1753,18 +1782,39 @@ function moderationEvictionSlug(error2, payload) {
   );
   return fromOrder ? fromOrder.split("/")[0] : display.toLowerCase();
 }
+var MIN_STREAM_ATTEMPT_MS = 1e4;
+var estimateTokens = (text) => Math.round(text.length / 4);
+function streamAttemptBudgetMs(options) {
+  if (options.streamDeadlineAt === void 0)
+    return options.streamTimeoutMs;
+  const remaining = options.streamDeadlineAt - Date.now();
+  if (remaining < MIN_STREAM_ATTEMPT_MS)
+    return null;
+  return Math.min(options.streamTimeoutMs, remaining);
+}
 async function callOpenRouterWithRetries(id, payload, retries = 5, options, signal) {
   const evicted = [];
   return withRetries(
     id,
     "OpenRouter",
-    () => (options.streaming ? callOpenRouterStream(
-      id,
-      payload,
-      options.streamTimeoutMs,
-      options.chunkTimeoutMs,
-      signal
-    ) : callOpenRouterNonStreaming(
+    () => (options.streaming ? (() => {
+      const budget = streamAttemptBudgetMs(options);
+      if (budget === null) {
+        const error2 = new Error(
+          "OpenRouter stream skipped: caller deadline leaves too little time for another attempt"
+        );
+        error2.deadlineExceeded = true;
+        logger_default.error(id, error2.message);
+        throw error2;
+      }
+      return callOpenRouterStream(
+        id,
+        payload,
+        budget,
+        options.chunkTimeoutMs,
+        signal
+      );
+    })() : callOpenRouterNonStreaming(
       id,
       payload,
       options.requestTimeoutMs,
@@ -1884,6 +1934,7 @@ async function callWithRetries(id, aiPayload, aiConfig, retries = 5, chunkTimeou
           {
             streaming: (_b = aiPayload.streaming) != null ? _b : true,
             streamTimeoutMs: (_c = aiPayload.streamTimeoutMs) != null ? _c : OPENROUTER_STREAM_TIMEOUT_MS,
+            streamDeadlineAt: aiPayload.streamDeadlineAt,
             requestTimeoutMs: (_d = aiPayload.requestTimeoutMs) != null ? _d : OPENROUTER_NONSTREAM_TIMEOUT_MS,
             chunkTimeoutMs
           },
@@ -1926,6 +1977,7 @@ async function callWithRetries(id, aiPayload, aiConfig, retries = 5, chunkTimeou
   GPTModel,
   GeminiModel,
   GroqModel,
+  MIN_STREAM_ATTEMPT_MS,
   OPENROUTER_NONSTREAM_TIMEOUT_MS,
   OPENROUTER_STREAM_TIMEOUT_MS,
   OpenRouterModel,