@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/llm/providers/openai.js

@@ -0,0 +1,606 @@
+/**
+ * OpenAI GPT provider using openai SDK.
+ *
+ * Serves every OpenAI-compatible endpoint we support (OpenAI, DeepSeek,
+ * OpenRouter, Z.AI, xAI, Mistral, Groq, Gemini-OpenAI-compat, Ollama,
+ * custom). Per-(provider, model) request-shape divergence — token-limit
+ * field name, rejected sampling params, thinking knob, reasoning echo —
+ * is resolved through `capabilitiesFor()`, not hardcoded.
+ */
+import OpenAI from "openai";
+import { LLMClientBase } from "../client-base.js";
+import { ContextLimitError, LLMError, LLMRateLimitError } from "../../exceptions.js";
+import { logger } from "../../logging/logger.js";
+import { countTokens } from "../token-counter.js";
+import { capabilitiesFor } from "../capabilities/index.js";
+import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watchdog.js";
+/**
+ * Consume an async iterable of stream chunks with an idle watchdog.
+ * Returns the accumulated text — either from onChunk return values, or
+ * by extracting choices[0].delta.content from raw chunks (useful in tests
+ * that call runStreamWithWatchdog directly without an onChunk handler).
+ *
+ * The watchdog is active whenever opts.idleTimeoutMs is explicitly provided,
+ * or when STREAM_WATCHDOG_CONFIG.enabled is true. When active, each call to
+ * iterator.next() races against an idle deadline; if the deadline fires first
+ * the function rejects with StreamIdleTimeoutError.
+ */
+export async function runStreamWithWatchdog(stream, opts = {}) {
+    const watchdogActive = STREAM_WATCHDOG_CONFIG.enabled || opts.idleTimeoutMs !== undefined;
+    const idleTimeoutMs = opts.idleTimeoutMs ?? STREAM_WATCHDOG_CONFIG.idleTimeoutMs;
+    let text = "";
+    // Fast path: watchdog disabled AND caller did not override → no overhead.
+    if (!watchdogActive) {
+        for await (const chunk of stream) {
+            if (opts.onChunk) {
+                text += opts.onChunk(chunk) ?? "";
+            }
+            else {
+                text += chunk?.choices?.[0]?.delta?.content ?? "";
+            }
+        }
+        return text;
+    }
+    // Watchdog path: race each iterator.next() against a per-chunk idle timer.
+    // This ensures the for-await cannot block forever between chunks.
+    const iterator = stream[Symbol.asyncIterator]();
+    try {
+        while (true) {
+            const nextPromise = iterator.next();
+            // Build a timeout promise that rejects if no chunk arrives in time.
+            let timeoutHandle = null;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => {
+                    reject(new StreamIdleTimeoutError(idleTimeoutMs, opts.requestId));
+                }, idleTimeoutMs);
+            });
+            let result;
+            try {
+                result = await Promise.race([nextPromise, timeoutPromise]);
+            }
+            finally {
+                if (timeoutHandle !== null)
+                    clearTimeout(timeoutHandle);
+            }
+            if (result.done)
+                break;
+            const chunk = result.value;
+            if (opts.onChunk) {
+                text += opts.onChunk(chunk) ?? "";
+            }
+            else {
+                text += chunk?.choices?.[0]?.delta?.content ?? "";
+            }
+        }
+    }
+    finally {
+        // Best-effort cleanup: signal iterator to stop. Do NOT await — if the
+        // generator is stuck (e.g., wedged HTTP stream), awaiting return() would
+        // itself hang. Fire-and-forget is intentional here.
+        iterator.return?.();
+    }
+    return text;
+}
+export class OpenAIClient extends LLMClientBase {
+    _client = null;
+    // Sticky override: once the endpoint tells us `max_tokens` is rejected for
+    // this model, switch to `max_completion_tokens` for the lifetime of the
+    // client. Cheaper and more reliable than re-deriving from the model id when
+    // a new variant ships before our regex knows about it.
+    _forceMaxCompletionTokens = false;
+    constructor(config) {
+        super(config);
+    }
+    initClient() {
+        // Lazy init — client created on first use
+    }
+    get client() {
+        if (!this._client) {
+            this._client = new OpenAI({
+                apiKey: this.config.apiKey ?? process.env.OPENAI_API_KEY,
+                ...(this.config.baseUrl ? { baseURL: this.config.baseUrl } : {}),
+                timeout: this.timeout,
+            });
+        }
+        return this._client;
+    }
+    /**
+     * Resolve the capability descriptor for the current (provider kind, model)
+     * pair. Cached for the lifetime of the client — model never changes
+     * mid-client. `providerKind` defaults to "openai" because legacy LLMConfig
+     * paths (arena, env-derived) don't always populate it; for those, the
+     * built-in rules table treats them as plain OpenAI.
+     */
+    _capability = null;
+    get capability() {
+        if (!this._capability) {
+            const kind = (this.config.providerKind ?? "openai");
+            this._capability = capabilitiesFor(kind, this.model);
+        }
+        return this._capability;
+    }
+    async createMessage(options) {
+        return this.withRetry(async () => {
+            // Per-call thinking wins; otherwise fall back to provider default
+            // (settings.providers[].thinking, threaded through LLMConfig).
+            const thinking = options.thinking ?? this.config.thinking;
+            const messages = this.buildMessages(options.systemPrompt, options.messages, thinking);
+            const tools = options.tools?.length ? this.convertTools(options.tools) : undefined;
+            const span = logger.span("llm.request", {
+                cat: "llm",
+                provider: this.provider,
+                model: this.model,
+                stream: !!(options.stream && options.onChunk),
+                messageCount: messages.length,
+                toolCount: tools?.length ?? 0,
+            });
+            try {
+                const response = options.stream && options.onChunk
+                    ? await this.streamMessage(options, messages, tools, thinking)
+                    : await this.nonStreamMessage(options, messages, tools, thinking);
+                span.end({
+                    stopReason: response.stopReason,
+                    promptTokens: response.usage?.promptTokens,
+                    completionTokens: response.usage?.completionTokens,
+                    cacheReadTokens: response.usage?.cacheReadTokens,
+                    cacheCreationTokens: response.usage?.cacheCreationTokens,
+                });
+                return response;
+            }
+            catch (err) {
+                span.fail(err);
+                throw err;
+            }
+        });
+    }
+    /**
+     * Build the request body honoring the model's capability descriptor.
+     * Centralized so both streaming and non-streaming paths agree on the
+     * exact shape.
+     */
+    buildRequestBody(options, messages, tools, thinking, stream) {
+        const cap = this.capability;
+        const maxTokens = options.maxTokens ?? this.maxTokens;
+        // Token-limit field — capability picks `max_tokens` vs `max_completion_tokens`.
+        // Sticky fallback (set by handleApiError on a 400) overrides the rule for
+        // ids the regex hasn't learned about yet.
+        const useCompletion = this._forceMaxCompletionTokens || cap.tokenLimitField === "max_completion_tokens";
+        const tokenLimit = useCompletion
+            ? { max_completion_tokens: maxTokens }
+            : { max_tokens: maxTokens };
+        // Sampling params — only include if the model accepts them.
+        const sampling = {};
+        if (!cap.rejectedParams.has("temperature")) {
+            sampling.temperature =
+                options.temperature !== undefined ? options.temperature : this.temperature;
+        }
+        // Reasoning shape — different vendors, different fields, never combine.
+        // We treat `options.thinking` as the user's intent ("enabled"/"disabled")
+        // and translate to whichever wire shape the model expects.
+        const reasoning = {};
+        if (thinking) {
+            switch (cap.reasoning.kind) {
+                case "deepseek-thinking":
+                    // DeepSeek V4, Z.AI GLM-4.5+ — top-level {thinking: {type}}.
+                    reasoning.thinking = { type: thinking };
+                    break;
+                case "openai-effort":
+                    // OpenAI o-series, gpt-5+, Gemini OpenAI-compat, xAI grok-4.3,
+                    // Mistral magistral, Groq reasoning models — `reasoning_effort`.
+                    // "enabled" → "medium" (safe middle). "disabled" → the capability's
+                    // `disabledEffort` value; defaults to "minimal" (OpenAI), but xAI
+                    // uses "low" (no minimal) and Mistral uses "none" (only high|none).
+                    reasoning.reasoning_effort =
+                        thinking === "disabled"
+                            ? (cap.reasoning.disabledEffort ?? "minimal")
+                            : "medium";
+                    break;
+                case "openrouter-reasoning":
+                    // OpenRouter normalized shape — {reasoning: {effort, exclude}}.
+                    reasoning.reasoning =
+                        thinking === "disabled"
+                            ? { effort: "minimal", exclude: true }
+                            : { effort: "medium" };
+                    break;
+                case "anthropic-budget":
+                case "anthropic-adaptive":
+                case "none":
+                    // OpenAI client doesn't serve Anthropic-direct; nothing to do.
+                    // `none` means the model doesn't expose a knob — skip silently.
+                    break;
+            }
+        }
+        return {
+            model: this.model,
+            messages,
+            ...tokenLimit,
+            ...sampling,
+            ...reasoning,
+            ...(tools ? { tools } : {}),
+            ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
+        };
+    }
+    async nonStreamMessage(options, messages, tools, thinking) {
+        try {
+            const response = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, thinking, false), { signal: options.signal });
+            const choice = response.choices[0];
+            if (!choice)
+                throw new LLMError("No response from OpenAI", "openai");
+            const usage = {
+                promptTokens: response.usage?.prompt_tokens ?? 0,
+                completionTokens: response.usage?.completion_tokens ?? 0,
+                totalTokens: response.usage?.total_tokens ?? 0,
+            };
+            this.recordUsage(usage, options);
+            return this.processChoice(choice, usage);
+        }
+        catch (err) {
+            this.handleApiError(err);
+            throw err;
+        }
+    }
+    async streamMessage(options, messages, tools, thinking) {
+        try {
+            const stream = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, thinking, true), { signal: options.signal });
+            let text = "";
+            let reasoningContent = "";
+            const toolCallsMap = new Map();
+            let streamUsage;
+            // TTFT — first chunk that actually carried text. Tool-call-only chunks
+            // earlier in the stream don't count: the user-visible "text starts now"
+            // moment is what we want to compare across providers.
+            const streamStartedAt = Date.now();
+            let firstByteLogged = false;
+            const requestId = stream.request_id;
+            const handleChunk = (chunk) => {
+                // Capture usage from the final chunk
+                if (chunk.usage) {
+                    streamUsage = chunk.usage;
+                }
+                const delta = chunk.choices[0]?.delta;
+                if (!delta)
+                    return "";
+                // DeepSeek thinking-mode streams reasoning as a separate delta
+                // field. Accumulate it so we can echo it back next turn.
+                const reasoningDelta = delta.reasoning_content;
+                if (typeof reasoningDelta === "string" && reasoningDelta.length > 0) {
+                    reasoningContent += reasoningDelta;
+                }
+                if (delta.content) {
+                    if (!firstByteLogged) {
+                        firstByteLogged = true;
+                        logger.debug("llm.first_byte", {
+                            cat: "llm",
+                            provider: this.provider,
+                            model: this.model,
+                            ttft_ms: Date.now() - streamStartedAt,
+                        });
+                    }
+                    text += delta.content;
+                    options.onChunk?.({
+                        type: "text",
+                        text: delta.content,
+                        tokens: countTokens(delta.content),
+                    });
+                }
+                if (delta.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index;
+                        if (!toolCallsMap.has(idx)) {
+                            toolCallsMap.set(idx, { id: tc.id ?? "", name: tc.function?.name ?? "", args: "" });
+                            options.onChunk?.({
+                                type: "tool_use_start",
+                                toolCall: { id: tc.id, toolName: tc.function?.name },
+                            });
+                        }
+                        const existing = toolCallsMap.get(idx);
+                        if (tc.id)
+                            existing.id = tc.id;
+                        if (tc.function?.name)
+                            existing.name = tc.function.name;
+                        if (tc.function?.arguments) {
+                            existing.args += tc.function.arguments;
+                            // Best-effort partial-JSON parse: succeeds once a complete
+                            // top-level object has streamed in (typical for short args)
+                            // and silently waits otherwise.
+                            if (existing.id) {
+                                try {
+                                    const parsed = JSON.parse(existing.args || "{}");
+                                    options.onChunk?.({
+                                        type: "tool_use_delta",
+                                        toolCall: { id: existing.id, toolName: existing.name, args: parsed },
+                                    });
+                                }
+                                catch {
+                                    // partial JSON — wait for more deltas
+                                }
+                            }
+                        }
+                    }
+                }
+                if (chunk.choices[0]?.finish_reason) {
+                    options.onChunk?.({ type: "stop", stopReason: chunk.choices[0].finish_reason });
+                }
+                return delta.content ?? "";
+            };
+            await runStreamWithWatchdog(stream, {
+                idleTimeoutMs: STREAM_WATCHDOG_CONFIG.enabled
+                    ? STREAM_WATCHDOG_CONFIG.idleTimeoutMs
+                    : undefined,
+                requestId,
+                onChunk: handleChunk,
+            });
+            const toolCalls = [];
+            for (const [, tc] of toolCallsMap) {
+                let args = {};
+                try {
+                    args = JSON.parse(tc.args || "{}");
+                }
+                catch { }
+                toolCalls.push({ id: tc.id, toolName: tc.name, args });
+            }
+            const usage = {
+                promptTokens: streamUsage?.prompt_tokens ?? 0,
+                completionTokens: streamUsage?.completion_tokens ?? 0,
+                totalTokens: streamUsage?.total_tokens ?? 0,
+            };
+            this.recordUsage(usage, options);
+            return {
+                text,
+                toolCalls,
+                usage,
+                stopReason: "stop",
+                ...(reasoningContent ? { reasoningContent } : {}),
+            };
+        }
+        catch (err) {
+            this.handleApiError(err);
+            throw err;
+        }
+    }
+    processChoice(choice, usage) {
+        const text = choice.message.content ?? "";
+        const toolCalls = [];
+        if (choice.message.tool_calls) {
+            for (const tc of choice.message.tool_calls) {
+                let args = {};
+                try {
+                    args = JSON.parse(tc.function.arguments || "{}");
+                }
+                catch { }
+                toolCalls.push({
+                    id: tc.id,
+                    toolName: tc.function.name,
+                    args,
+                });
+            }
+        }
+        const reasoningContent = extractReasoningContent(choice.message);
+        return {
+            text,
+            toolCalls,
+            usage,
+            stopReason: choice.finish_reason ?? undefined,
+            ...(reasoningContent ? { reasoningContent } : {}),
+        };
+    }
+    buildMessages(systemPrompt, messages, thinking) {
+        const result = [{ role: "system", content: systemPrompt }];
+        // Reasoning-content echo-back contract — driven by capability:
+        //   "when-tools"  : backfill an empty placeholder if the prior assistant
+        //                   turn doesn't carry one (DeepSeek V4 + tools 400s
+        //                   otherwise). Skip when thinking is explicitly disabled,
+        //                   because empty-string in that mode can degenerate into
+        //                   an empty reply on the *next* turn.
+        //   "never"       : drop any reasoning_content (deepseek-reasoner 400s
+        //                   if input messages contain it).
+        //   "optional"    : pass through when we have it, never synthesize.
+        const cap = this.capability;
+        const hasTools = messages.some((m) => Array.isArray(m.content) &&
+            m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
+        const needsReasoningBackfill = thinking !== "disabled" &&
+            cap.echoReasoning === "when-tools" &&
+            hasTools;
+        const stripReasoning = cap.echoReasoning === "never";
+        for (const msg of messages) {
+            if (msg.role === "system")
+                continue;
+            if (msg.role === "assistant") {
+                const param = { role: "assistant" };
+                let reasoningContent;
+                if (typeof msg.content === "string") {
+                    param.content = msg.content;
+                }
+                else {
+                    const textParts = [];
+                    const toolCalls = [];
+                    for (const block of msg.content) {
+                        if (block.type === "text" && block.text) {
+                            textParts.push(block.text);
+                        }
+                        else if (block.type === "tool_use" && block.id && block.name) {
+                            toolCalls.push({
+                                id: block.id,
+                                type: "function",
+                                function: {
+                                    name: block.name,
+                                    arguments: JSON.stringify(block.input ?? {}),
+                                },
+                            });
+                        }
+                        else if (block.type === "reasoning" && block.reasoningContent) {
+                            reasoningContent = block.reasoningContent;
+                        }
+                        // Reasoning may also ride alongside another block (e.g. on a
+                        // text block) — pick it up wherever it appears so we never
+                        // silently drop it.
+                        if (!reasoningContent && block.reasoningContent) {
+                            reasoningContent = block.reasoningContent;
+                        }
+                    }
+                    if (textParts.length)
+                        param.content = textParts.join("\n");
+                    if (toolCalls.length)
+                        param.tool_calls = toolCalls;
+                }
+                if (stripReasoning) {
+                    // Some endpoints (deepseek-reasoner) 400 if reasoning_content
+                    // appears in input history. Don't attach the field at all.
+                    reasoningContent = undefined;
+                }
+                else if (!reasoningContent && needsReasoningBackfill) {
+                    reasoningContent = "";
+                }
+                if (reasoningContent !== undefined) {
+                    param.reasoning_content = reasoningContent;
+                }
+                // OpenAI rejects { role: "assistant" } with no content AND no
+                // tool_calls ("Invalid assistant message: content or tool_calls
+                // must be set"). This shape can arise from a transcript where
+                // the assistant produced only reasoning blocks (no text, no tool
+                // calls) before the stream was cut off, or from a synthetic
+                // message left behind by an interrupted retry. Drop these so
+                // the API call doesn't 400 on a structurally-empty turn.
+                // reasoning_content alone does NOT satisfy OpenAI's requirement —
+                // it's an extension field and not counted as "content".
+                if (param.content === undefined && param.tool_calls === undefined) {
+                    continue;
+                }
+                result.push(param);
+            }
+            else if (msg.role === "tool") {
+                result.push({
+                    role: "tool",
+                    tool_call_id: msg.tool_call_id ?? "",
+                    content: typeof msg.content === "string" ? msg.content : "",
+                });
+            }
+            else {
+                // user messages — may contain tool_result blocks mixed with text
+                // and image blocks (P2-6: image input).
+                if (typeof msg.content === "string") {
+                    result.push({ role: "user", content: msg.content });
+                }
+                else {
+                    // Separate tool_result blocks from text/image blocks. tool_result
+                    // must become its own `role: "tool"` message (OpenAI's wire format
+                    // doesn't allow tool_result inside a user content array); text and
+                    // image stay together so the model sees "this text refers to this
+                    // image" without an intervening tool turn.
+                    const textParts = [];
+                    const imageParts = [];
+                    const toolResults = [];
+                    for (const block of msg.content) {
+                        if (block.type === "tool_result" && block.tool_use_id) {
+                            toolResults.push({
+                                tool_use_id: block.tool_use_id,
+                                content: typeof block.content === "string" ? block.content : "",
+                            });
+                        }
+                        else if (block.type === "text" && block.text) {
+                            textParts.push(block.text);
+                        }
+                        else if (block.type === "image" && block.source) {
+                            // OpenAI-compat image_url: every supported provider (OpenAI,
+                            // OpenRouter, OpenAI-compatible proxies for Gemini/xAI/etc)
+                            // accepts a base64 data URL as the URL. Per-(provider, model)
+                            // vision-capability gating happens earlier in Engine.run —
+                            // by the time we reach here, the model supports vision.
+                            imageParts.push({
+                                type: "image_url",
+                                image_url: {
+                                    url: `data:${block.source.media_type};base64,${block.source.data}`,
+                                },
+                            });
+                        }
+                    }
+                    // Emit tool_result blocks as separate tool messages
+                    for (const tr of toolResults) {
+                        result.push({
+                            role: "tool",
+                            tool_call_id: tr.tool_use_id,
+                            content: tr.content,
+                        });
+                    }
+                    // Emit the user-visible turn. With images present, content MUST be
+                    // an array — putting a stringified version into `content: "..."`
+                    // strips the images. Without images we keep the legacy string form
+                    // so requests for vanilla text turns are byte-identical to before.
+                    if (imageParts.length > 0) {
+                        const parts = [];
+                        if (textParts.length > 0) {
+                            parts.push({ type: "text", text: textParts.join("\n") });
+                        }
+                        parts.push(...imageParts);
+                        result.push({ role: "user", content: parts });
+                    }
+                    else if (textParts.length > 0) {
+                        result.push({ role: "user", content: textParts.join("\n") });
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    convertTools(tools) {
+        return tools.map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.inputSchema,
+            },
+        }));
+    }
+    handleApiError(err) {
+        if (err instanceof OpenAI.APIError) {
+            if (err.status === 429) {
+                throw new LLMRateLimitError("openai");
+            }
+            const msg = (err.message ?? "").toLowerCase();
+            // o-series / gpt-5+ reject `max_tokens` and demand
+            // `max_completion_tokens`. The id-based regex catches the common
+            // cases; this is the belt-and-suspenders path for ids that ship
+            // before the regex knows about them (e.g. new `gpt-5.x` variants
+            // routed via OpenAI-compatible proxies). Flip a sticky flag so the
+            // next request — including `withRetry`'s next attempt — sends the
+            // right field, instead of looping on the same 400.
+            if (err.status === 400 &&
+                msg.includes("max_tokens") &&
+                msg.includes("max_completion_tokens")) {
+                this._forceMaxCompletionTokens = true;
+            }
+            if (msg.includes("context_length_exceeded") ||
+                msg.includes("maximum context length") ||
+                msg.includes("too many tokens") ||
+                msg.includes("prompt is too long")) {
+                throw new ContextLimitError("openai");
+            }
+            // OpenRouter and other compatible endpoints often return 401 "Provider
+            // returned error" when the routed backend disables function calling for
+            // the selected model. A real auth failure is also possible — surface
+            // both possibilities so users don't blindly swap models.
+            if (err.status === 401 && msg.includes("provider returned error")) {
+                throw new LLMError(`OpenAI-compatible endpoint returned 401 "Provider returned error". ` +
+                    `Two likely causes: (1) the API key is invalid/revoked, or ` +
+                    `(2) the upstream provider rejects tool calls for this model ` +
+                    `(common on OpenRouter's gpt-4o-mini route). Verify the key, ` +
+                    `then try a tool-capable model such as openai/gpt-4.1-mini or ` +
+                    `anthropic/claude-3.5-haiku.`, "openai", { status: err.status });
+            }
+            throw new LLMError(`OpenAI API error: ${err.message}`, "openai", { status: err.status });
+        }
+        throw err;
+    }
+}
+/**
+ * Pull a non-empty reasoning payload out of a provider message.
+ *
+ * DeepSeek thinking mode emits this on the assistant message; the
+ * spec requires that the same value be echoed back on the next
+ * request. Some routers also surface it under `reasoning`.
+ */
+function extractReasoningContent(msg) {
+    const candidate = msg.reasoning_content ?? msg.reasoning;
+    return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+}

package/dist/llm/retry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Retry classification — which errors trigger an automatic retry of the
+ * streaming LLM call?
+ *
+ * Stream-idle timeouts are retried — the upstream may have just recovered.
+ * User-initiated aborts (AbortError) are never retried — the user explicitly
+ * asked for the work to stop.
+ *
+ * Other transient errors (5xx, 429, ECONNRESET) are out of scope for this
+ * iteration; add them here as they become observed.
+ */
+export declare function isRetryable(err: unknown): boolean;

package/dist/llm/retry.js

@@ -0,0 +1,17 @@
+/**
+ * Retry classification — which errors trigger an automatic retry of the
+ * streaming LLM call?
+ *
+ * Stream-idle timeouts are retried — the upstream may have just recovered.
+ * User-initiated aborts (AbortError) are never retried — the user explicitly
+ * asked for the work to stop.
+ *
+ * Other transient errors (5xx, 429, ECONNRESET) are out of scope for this
+ * iteration; add them here as they become observed.
+ */
+import { StreamIdleTimeoutError } from "./stream-watchdog.js";
+export function isRetryable(err) {
+    if (err instanceof StreamIdleTimeoutError)
+        return true;
+    return false;
+}

package/dist/llm/stream-watchdog.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stream Idle Watchdog — guarantees an upper bound on the time a streaming
+ * LLM call can spend with no bytes arriving. Without this, a wedged HTTP/2
+ * connection can hang the session indefinitely; the SDK's request timeout
+ * only covers the initial fetch, not the streaming body.
+ *
+ * Disabled by default. Enabled via env CODESHELL_ENABLE_STREAM_WATCHDOG=1.
+ */
+export interface StreamWatchdogOptions {
+    /** Abort the stream when no chunks arrive within this window. */
+    idleTimeoutMs: number;
+    /** Called when the watchdog decides to abort. */
+    onTimeout: () => void;
+    /**
+     * Called at idleTimeoutMs/2 (or warningMs if provided). Logging only —
+     * the watchdog does not abort on warning. The argument is the configured
+     * warning threshold (NOT real-time elapsed) so callers can format the log
+     * without re-deriving it.
+     */
+    onWarning?: (warnThresholdMs: number) => void;
+    /** Override the warning trigger; defaults to idleTimeoutMs / 2. */
+    warningMs?: number;
+}
+export interface StreamWatchdog {
+    /** Re-arm both timers — call after every chunk. */
+    reset(): void;
+    /** Clear all timers permanently — call in finally. */
+    dispose(): void;
+}
+export declare class StreamIdleTimeoutError extends Error {
+    idleMs: number;
+    requestId?: string | undefined;
+    readonly kind = "stream-idle-timeout";
+    constructor(idleMs: number, requestId?: string | undefined);
+}
+export declare function createStreamWatchdog(opts: StreamWatchdogOptions): StreamWatchdog;
+/** Environment-driven defaults. Read once at import time is fine — these never change inside a process. */
+export declare const STREAM_WATCHDOG_CONFIG: {
+    enabled: boolean;
+    idleTimeoutMs: number;
+    retries: number;
+};