@wrongstack/providers 0.109.1 → 0.141.0

package/dist/index.d.ts

@@ -21,12 +21,35 @@ interface SSEMessage {
 }
 declare function parseSSE(body: ReadableStream<Uint8Array> | NodeJS.ReadableStream | null): AsyncIterable<SSEMessage>;
 
+/** Configuration for WireAdapter stream-level debugging and hang detection. */
+interface WireAdapterStreamOptions {
+    /**
+     * When true, accumulate per-chunk stats into the shared debug-sink
+     * (stream-debug-state.ts). The sink batches every 200 ms and pushes to
+     * a registered callback. The CLI default callback writes to stderr; the
+     * TUI replaces it with a reducer dispatch that renders in StatusBar line 3,
+     * keeping all output inside Ink's layout.
+     *
+     * Controlled by WRONGSTACK_DEBUG_STREAM=1 env var or the runtime
+     * /settings debug-stream toggle.
+     */
+    debugStream?: boolean | undefined;
+    /**
+     * Maximum time (ms) to wait for the next chunk of data before declaring
+     * a stream hang. Default: 60_000 (60 seconds). Set to 0 to disable.
+     * When a hang is detected, a StreamHangError is thrown so the agent
+     * loop can retry the iteration.
+     */
+    streamHangTimeoutMs?: number | undefined;
+}
 /**
  * Shared HTTP mechanics for streaming providers.
  * Providers extend this to get:
  *   - canonical error handling (ProviderError with retryable flag)
  *   - SSE body parsing via parseSSE()
  *   - abort signal wiring
+ *   - optional raw-stream debug logging
+ *   - optional stream hang detection
  *
  * Subclasses implement the abstract members to provide their specific wire format.
  */
@@ -36,13 +59,32 @@ declare abstract class WireAdapter implements Provider {
     readonly fetchImpl: typeof fetch;
     abstract readonly id: string;
     abstract readonly capabilities: Capabilities;
-    constructor(apiKey: string, baseUrl: string, fetchImpl?: typeof fetch);
+    protected readonly debugStream: boolean;
+    protected readonly streamHangTimeoutMs: number;
+    constructor(apiKey: string, baseUrl: string, fetchImpl?: typeof fetch, streamOpts?: WireAdapterStreamOptions);
     complete(req: Request, opts: {
         signal: AbortSignal;
     }): Promise<Response>;
     stream(req: Request, opts: {
         signal: AbortSignal;
     }): AsyncIterable<StreamEvent>;
+    /**
+     * Wrap a readable stream body to log a compact status line per incoming
+     * byte chunk to stderr. This is a diagnostic tool for tracking stream
+     * activity — chunk count, sizes, and inter-chunk deltas — without
+     * printing payload contents.
+     */
+    private wrapDebugStream;
+    private wrapDebugNodeStream;
+    private wrapDebugWebStream;
+    /**
+     * Wrap a readable stream to detect hangs — when no data arrives for
+     * longer than `streamHangTimeoutMs`. When a hang is detected, throws
+     * `StreamHangError` so the caller can retry or fall back.
+     */
+    private wrapWithHangDetection;
+    private wrapHangNodeStream;
+    private wrapHangWebStream;
     /** HTTP endpoint for this provider's chat completions / messages API. */
     protected abstract buildUrl(req: Request): string;
     /** Per-request headers. `apiKey` is already in scope — call `super.buildHeaders` first. */
@@ -61,6 +103,8 @@ interface AnthropicProviderOptions {
     apiVersion?: string | undefined;
     beta?: string[] | undefined;
     fetchImpl?: typeof fetch | undefined;
+    /** Raw stream debugging and hang-detection options. */
+    streamOpts?: WireAdapterStreamOptions | undefined;
 }
 declare class AnthropicProvider extends WireAdapter {
     readonly id = "anthropic";
@@ -135,6 +179,8 @@ interface OpenAIProviderOptions {
     } | undefined;
     id?: string | undefined;
     capabilities?: Partial<Capabilities> | undefined;
+    /** Raw stream debugging and hang-detection options. */
+    streamOpts?: WireAdapterStreamOptions | undefined;
 }
 declare class OpenAIProvider extends WireAdapter {
     readonly id: string;
@@ -179,6 +225,8 @@ interface OpenAICompatibleOptions {
      * URL structures (e.g. Google with model-in-path, Anthropic with /v1/messages).
      */
     urlOverride?: ((baseUrl: string, req: Request) => string) | undefined;
+    /** Raw stream debugging and hang-detection options. */
+    streamOpts?: WireAdapterStreamOptions | undefined;
 }
 declare class OpenAICompatibleProvider extends OpenAIProvider {
     private readonly extraHeaders?;
@@ -212,6 +260,8 @@ interface GoogleProviderOptions {
     fetchImpl?: typeof fetch | undefined;
     id?: string | undefined;
     capabilities?: Partial<Capabilities> | undefined;
+    /** Raw stream debugging and hang-detection options. */
+    streamOpts?: WireAdapterStreamOptions | undefined;
 }
 declare class GoogleProvider extends WireAdapter {
     readonly id: string;
@@ -225,6 +275,59 @@ declare class GoogleProvider extends WireAdapter {
     private buildGenConfig;
 }
 
+/**
+ * Singleton gate for stream debug logging.
+ *
+ * WireAdapter reads this on every stream() call, so runtime toggles
+ * (via /settings debug-stream on|off) take effect on the next request
+ * without recreating provider instances.
+ *
+ * When enabled, WireAdapter accumulates per-chunk stats and pushes them
+ * through a registered callback. In CLI (non-TUI) mode the default
+ * callback writes a compact status line to stderr. The TUI replaces
+ * the callback with one that dispatches to its reducer so the debug
+ * info renders inside Ink's StatusBar line 3 instead of bypassing it.
+ *
+ * The CLI boot path seeds this from config.debugStream at startup.
+ */
+interface DebugStreamStats {
+    /** Monotonic chunk counter, resets per-stream. */
+    chunkCount: number;
+    /** Bytes of the most recent chunk. */
+    lastChunkSize: number;
+    /** Millisecond delta since the PREVIOUS chunk (reveals think gaps). */
+    lastDeltaMs: number;
+    /** Cumulative bytes received for this stream. */
+    totalBytes: number;
+    /** ISO timestamp of the most recent chunk. */
+    lastChunkAt: string;
+}
+type DebugStreamCallback = (stats: DebugStreamStats) => void;
+/** Check whether raw SSE stream debugging is currently active. */
+declare function isDebugStreamEnabled(): boolean;
+/** Flip the stream debug flag at runtime. Persisted separately via ConfigStore. */
+declare function setDebugStreamEnabled(enabled: boolean): void;
+/**
+ * Register a callback that receives THROTTLED debug-chunk stats (~5 Hz).
+ * WireAdapter calls `pushDebugChunkStats()` on every raw chunk; this module
+ * batches them and calls `cb` at most once per THROTTLE_MS.
+ *
+ * Pass `null` to restore the default stderr behaviour.
+ */
+declare function setDebugStreamCallback(cb: DebugStreamCallback | null): void;
+/**
+ * Called by WireAdapter on every raw chunk. Not throttled — call it as
+ * often as chunks arrive; it's cheap (a few integer assigns + a debounced
+ * setTimeout). The registered callback receives aggregated stats at most
+ * once per THROTTLE_MS.
+ */
+declare function pushDebugChunkStats(bytes: number, deltaMs: number): void;
+/**
+ * Default callback: write a compact status line to stderr (used in CLI /
+ * headless mode where Ink isn't painting the terminal).
+ */
+declare function defaultDebugStreamCallback(stats: DebugStreamStats): void;
+
 /**
  * Declarative wire-format definition. Sufficient to add a new HTTP+SSE
  * provider without subclassing `WireAdapter` — the boilerplate (HTTP errors,
@@ -287,6 +390,7 @@ declare class WireFormatProvider<S = Record<string, unknown>> extends WireAdapte
         apiKey: string;
         baseUrl?: string | undefined;
         fetchImpl?: typeof fetch | undefined;
+        streamOpts?: WireAdapterStreamOptions | undefined;
     });
     protected buildUrl(req: Request): string;
     protected buildHeaders(req: Request): Record<string, string>;
@@ -497,4 +601,4 @@ declare function buildProviderFactoriesFromRegistry(opts: BuildFactoriesOptions)
  */
 declare function makeProviderFromConfig(id: string, cfg: ProviderConfig): Provider;
 
-export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, CAPABILITIES_BY_FAMILY, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, capabilitiesForFamily, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };
+export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, CAPABILITIES_BY_FAMILY, type CompatibilityQuirks, type ConvertOptions, type DebugStreamCallback, type DebugStreamStats, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, type WireAdapterStreamOptions, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, capabilitiesForFamily, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defaultDebugStreamCallback, defineWireFormat, googleWireFormat, isDebugStreamEnabled, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, pushDebugChunkStats, setDebugStreamCallback, setDebugStreamEnabled, toolsToAnthropic, toolsToOpenAI };

package/dist/index.js

@@ -1,4 +1,5 @@
-import { expectDefined, ProviderError, safeParse, sanitizeJsonString, WrongStackError, ERROR_CODES } from '@wrongstack/core';
+import { expectDefined, ProviderError, StreamHangError, safeParse, sanitizeJsonString, WrongStackError, ERROR_CODES } from '@wrongstack/core';
+import { Readable } from 'stream';
 import { randomUUID } from 'crypto';
 
 var __defProp = Object.defineProperty;
@@ -539,6 +540,60 @@ function toolsToAnthropic(tools) {
     }
   }));
 }
+
+// src/stream-debug-state.ts
+var _debugStreamEnabled = false;
+var _debugStreamCallback = null;
+var _throttleTimer = null;
+var _pendingStats = null;
+var THROTTLE_MS = 200;
+function _flush() {
+  if (_pendingStats && _debugStreamCallback) {
+    _debugStreamCallback({ ..._pendingStats });
+    _pendingStats = null;
+  }
+  _throttleTimer = null;
+}
+function _scheduleFlush() {
+  if (_throttleTimer) return;
+  _throttleTimer = setTimeout(_flush, THROTTLE_MS);
+  if (_throttleTimer.unref) _throttleTimer.unref();
+}
+function isDebugStreamEnabled() {
+  return _debugStreamEnabled;
+}
+function setDebugStreamEnabled(enabled) {
+  _debugStreamEnabled = enabled;
+}
+function setDebugStreamCallback(cb) {
+  if (_throttleTimer) {
+    clearTimeout(_throttleTimer);
+    _flush();
+  }
+  _debugStreamCallback = cb;
+}
+function pushDebugChunkStats(bytes, deltaMs) {
+  if (!_debugStreamEnabled) return;
+  _pendingStats = {
+    chunkCount: (_pendingStats?.chunkCount ?? 0) + 1,
+    lastChunkSize: bytes,
+    lastDeltaMs: deltaMs,
+    totalBytes: (_pendingStats?.totalBytes ?? 0) + bytes,
+    lastChunkAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  _scheduleFlush();
+}
+function defaultDebugStreamCallback(stats) {
+  process.stderr.write(
+    `[DEBUG-STREAM] chunk #${stats.chunkCount} (${stats.lastChunkSize}B, +${stats.lastDeltaMs}ms) \xB7 ${fmtBytes(stats.totalBytes)} total \xB7 ${stats.lastChunkAt}
+`
+  );
+}
+function fmtBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1048576) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1048576).toFixed(1)}MB`;
+}
 function validateResponse(res) {
   const r = res;
   if (r === void 0 || typeof r.ok !== "boolean" || typeof r.status !== "number") {
@@ -558,16 +613,24 @@ async function safeText(res) {
     return "";
   }
 }
+function logRawChunk(_providerId, _chunkIndex, bytes, deltaMs) {
+  pushDebugChunkStats(bytes.length, deltaMs);
+}
+var DEFAULT_STREAM_HANG_TIMEOUT_MS = 6e4;
 var WireAdapter = class {
-  constructor(apiKey, baseUrl, fetchImpl = fetch) {
+  constructor(apiKey, baseUrl, fetchImpl = fetch, streamOpts = {}) {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl;
     this.fetchImpl = fetchImpl;
     if (!apiKey) throw new Error(`${this.constructor.name}: apiKey required`);
+    this.debugStream = streamOpts.debugStream ?? false;
+    this.streamHangTimeoutMs = streamOpts.streamHangTimeoutMs ?? DEFAULT_STREAM_HANG_TIMEOUT_MS;
   }
   apiKey;
   baseUrl;
   fetchImpl;
+  debugStream;
+  streamHangTimeoutMs;
   async complete(req, opts) {
     const { aggregateStream: aggregateStream2 } = await Promise.resolve().then(() => (init_aggregate(), aggregate_exports));
     return aggregateStream2(this.stream(req, opts));
@@ -597,7 +660,124 @@ var WireAdapter = class {
       const text = await safeText(httpRes);
       throw this.translateError(httpRes.status, text);
     }
-    yield* this.parseStream(httpRes.body, req.model);
+    let sseBody = httpRes.body;
+    if (!sseBody) {
+      return;
+    }
+    if (this.debugStream || isDebugStreamEnabled()) {
+      sseBody = this.wrapDebugStream(sseBody);
+    }
+    if (this.streamHangTimeoutMs > 0) {
+      sseBody = this.wrapWithHangDetection(sseBody, req.model);
+    }
+    yield* this.parseStream(sseBody, req.model);
+  }
+  /**
+   * Wrap a readable stream body to log a compact status line per incoming
+   * byte chunk to stderr. This is a diagnostic tool for tracking stream
+   * activity — chunk count, sizes, and inter-chunk deltas — without
+   * printing payload contents.
+   */
+  wrapDebugStream(body) {
+    if (isNodeReadable2(body)) {
+      return this.wrapDebugNodeStream(body);
+    }
+    return this.wrapDebugWebStream(body);
+  }
+  wrapDebugNodeStream(body) {
+    let lastChunkTime = Date.now();
+    let chunkIndex = 0;
+    const providerId = this.id;
+    return Readable.from(
+      (async function* () {
+        for await (const chunk of body) {
+          const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+          const now = Date.now();
+          logRawChunk(providerId, chunkIndex++, bytes, now - lastChunkTime);
+          lastChunkTime = now;
+          yield chunk;
+        }
+      })()
+    );
+  }
+  wrapDebugWebStream(body) {
+    let lastChunkTime = Date.now();
+    let chunkIndex = 0;
+    const self = this;
+    const reader = body.getReader();
+    return new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          return;
+        }
+        if (value) {
+          const now = Date.now();
+          logRawChunk(self.id, chunkIndex++, value, now - lastChunkTime);
+          lastChunkTime = now;
+        }
+        controller.enqueue(value);
+      },
+      cancel(reason) {
+        reader.cancel(reason);
+      }
+    });
+  }
+  /**
+   * Wrap a readable stream to detect hangs — when no data arrives for
+   * longer than `streamHangTimeoutMs`. When a hang is detected, throws
+   * `StreamHangError` so the caller can retry or fall back.
+   */
+  wrapWithHangDetection(body, model) {
+    if (isNodeReadable2(body)) {
+      return this.wrapHangNodeStream(body, model);
+    }
+    return this.wrapHangWebStream(body, model);
+  }
+  wrapHangNodeStream(body, model) {
+    const webStream = Readable.toWeb(body);
+    const wrappedWeb = this.wrapHangWebStream(webStream, model);
+    return Readable.fromWeb(wrappedWeb);
+  }
+  wrapHangWebStream(body, model) {
+    const startTime = Date.now();
+    let bytesReceived = 0;
+    const timeout = this.streamHangTimeoutMs;
+    const providerId = this.id;
+    const reader = body.getReader();
+    return new ReadableStream({
+      async pull(controller) {
+        const readPromise = reader.read();
+        const timeoutPromise = new Promise((resolve) => {
+          setTimeout(() => resolve({ timedOut: true }), timeout);
+        });
+        const result = await Promise.race([readPromise, timeoutPromise]);
+        if ("timedOut" in result && result.timedOut) {
+          reader.cancel("stream hang detected").catch((err) => console.debug(`[wire-adapter] cancel after stream hang failed: ${err}`));
+          const elapsedMs = Date.now() - startTime;
+          throw new StreamHangError({
+            providerId,
+            model,
+            hangTimeoutMs: timeout,
+            bytesReceived,
+            elapsedMs
+          });
+        }
+        const { done, value } = result;
+        if (done) {
+          controller.close();
+          return;
+        }
+        if (value) {
+          bytesReceived += value.length;
+        }
+        controller.enqueue(value);
+      },
+      cancel(reason) {
+        reader.cancel(reason);
+      }
+    });
   }
   /** Per-request headers. `apiKey` is already in scope — call `super.buildHeaders` first. */
   buildHeaders(_req) {
@@ -611,6 +791,9 @@ var WireAdapter = class {
     return parseProviderHttpError(this.id, status, body);
   }
 };
+function isNodeReadable2(b) {
+  return !!b && typeof b === "object" && typeof b.pipe === "function" && typeof b.on === "function";
+}
 
 // src/anthropic.ts
 var DEFAULT_BASE = "https://api.anthropic.com";
@@ -628,7 +811,7 @@ var AnthropicProvider = class extends WireAdapter {
   capabilities = capabilitiesForFamily("anthropic");
   opts;
   constructor(opts) {
-    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE, opts.fetchImpl);
+    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE, opts.fetchImpl, opts.streamOpts);
     this.opts = opts;
   }
   buildUrl(_req) {
@@ -787,7 +970,7 @@ var GoogleProvider = class extends WireAdapter {
   id;
   capabilities;
   constructor(opts) {
-    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE2, opts.fetchImpl);
+    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE2, opts.fetchImpl, opts.streamOpts);
     this.id = opts.id ?? "google";
     this.capabilities = capabilitiesForFamily("google", {
       ...opts.capabilities
@@ -1111,7 +1294,7 @@ var OpenAIProvider = class extends WireAdapter {
   capabilities;
   opts;
   constructor(opts) {
-    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE3, opts.fetchImpl);
+    super(opts.apiKey, opts.baseUrl ?? DEFAULT_BASE3, opts.fetchImpl, opts.streamOpts);
     this.opts = opts;
     this.id = opts.id ?? "openai";
     this.capabilities = capabilitiesForFamily("openai", {
@@ -1330,7 +1513,8 @@ var OpenAICompatibleProvider = class extends OpenAIProvider {
         systemPrompt: !opts.quirks?.systemAsMessage,
         ...opts.capabilities
       }),
-      quirks: opts.quirks
+      quirks: opts.quirks,
+      streamOpts: opts.streamOpts
     });
     this.extraHeaders = opts.headers;
     this.urlOverride = opts.urlOverride;
@@ -1363,7 +1547,7 @@ var WireFormatProvider = class extends WireAdapter {
   capabilities;
   cfg;
   constructor(cfg, opts) {
-    super(opts.apiKey, opts.baseUrl ?? cfg.defaultBaseUrl, opts.fetchImpl);
+    super(opts.apiKey, opts.baseUrl ?? cfg.defaultBaseUrl, opts.fetchImpl, opts.streamOpts);
     this.id = cfg.id;
     this.capabilities = cfg.capabilities;
     this.cfg = cfg;
@@ -2290,6 +2474,8 @@ function makeProvider(p, cfg) {
       });
     case "google":
       return new GoogleProvider({ id: p.id, apiKey: expectDefined(apiKey), baseUrl });
+    default:
+      throw new Error(`Unknown provider family: ${String(family)}`);
   }
 }
 function makeProviderFromConfig(id, cfg) {
@@ -2329,6 +2515,6 @@ function validateQuirks(providerId, quirks) {
   });
 }
 
-export { AnthropicProvider, CAPABILITIES_BY_FAMILY, GoogleProvider, OpenAICompatibleProvider, OpenAIProvider, WireAdapter, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, capabilitiesForFamily, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };
+export { AnthropicProvider, CAPABILITIES_BY_FAMILY, GoogleProvider, OpenAICompatibleProvider, OpenAIProvider, WireAdapter, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, capabilitiesForFamily, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defaultDebugStreamCallback, defineWireFormat, googleWireFormat, isDebugStreamEnabled, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, pushDebugChunkStats, setDebugStreamCallback, setDebugStreamEnabled, toolsToAnthropic, toolsToOpenAI };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map