@celestea/llm 2.7.1

package/dist/stream.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SSE stream -> seam events (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::{raw_chunk_stream, stream_events}`:
+ *   * the body is read chunk by chunk with the SSE idle guard applied to the
+ *     gap between any two chunks (including the wait for the first one);
+ *   * frames are decoded incrementally, `[DONE]` terminates, keepalive and
+ *     non-JSON frames are skipped, and an upstream error frame terminates the
+ *     stream as failed{kind:"stream"} (never a fake done);
+ *   * reasoning deltas stream as thinking events, content as text deltas, tool
+ *     calls accumulate per index, usage is surfaced just before the terminal
+ *     event;
+ *   * the terminal event is exactly one of done / failed / interrupted — an
+ *     idle stall yields failed{kind:"timeout"}, a mid-stream decode error
+ *     failed{kind:"stream"}, and a stream that ends without [DONE] yields
+ *     interrupted. Never a fake done (R1).
+ */
+import type http from "node:http";
+import { type RawChunk } from "./sse/chunks.js";
+import type { Message, StreamEvent } from "./seam.js";
+import type { Usage } from "./usage.js";
+/** Internal signal: the idle guard tripped and terminated the body read. */
+export declare class StreamIdleAbort extends Error {
+}
+/** Accumulates one turn's deltas and assembles the terminal assistant message. */
+export declare class TurnAccumulator {
+    #private;
+    /** Fold one decoded chunk in; returns the live events it produced. */
+    push(chunk: RawChunk): StreamEvent[];
+    /** The last seen provider usage (usage-only final frame or last chunk). */
+    get usage(): Usage | null;
+    /** The assembled assistant turn (text first, then tool calls by index). */
+    doneMessage(): Message;
+}
+/**
+ * Byte chunks of the response body with the SSE idle guard applied to the gap
+ * between any two chunks. Throws StreamIdleAbort when the upstream stalls and
+ * the transport error itself when the body read fails mid-stream.
+ */
+export declare function readBodyChunks(response: http.IncomingMessage, idleMs: number | null): AsyncGenerator<Buffer>;
+/**
+ * Decode a 2xx SSE response into seam events. The generator always ends with
+ * exactly one terminal event (done | failed | interrupted) or an empty stream
+ * only when the caller stops iterating early.
+ */
+export declare function streamEvents(response: http.IncomingMessage, idleMs: number | null): AsyncGenerator<StreamEvent>;

package/dist/stream.js

@@ -0,0 +1,240 @@
+/**
+ * SSE stream -> seam events (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::{raw_chunk_stream, stream_events}`:
+ *   * the body is read chunk by chunk with the SSE idle guard applied to the
+ *     gap between any two chunks (including the wait for the first one);
+ *   * frames are decoded incrementally, `[DONE]` terminates, keepalive and
+ *     non-JSON frames are skipped, and an upstream error frame terminates the
+ *     stream as failed{kind:"stream"} (never a fake done);
+ *   * reasoning deltas stream as thinking events, content as text deltas, tool
+ *     calls accumulate per index, usage is surfaced just before the terminal
+ *     event;
+ *   * the terminal event is exactly one of done / failed / interrupted — an
+ *     idle stall yields failed{kind:"timeout"}, a mid-stream decode error
+ *     failed{kind:"stream"}, and a stream that ends without [DONE] yields
+ *     interrupted. Never a fake done (R1).
+ */
+import { StringDecoder } from "node:string_decoder";
+import { streamIdleTimeoutMessage } from "./errors.js";
+import { SseDecoder } from "./sse/frames.js";
+import { parseArguments, parseRawChunk, parseStreamError, thinkingEvent, } from "./sse/chunks.js";
+/** Internal signal: the idle guard tripped and terminated the body read. */
+export class StreamIdleAbort extends Error {
+}
+/** Accumulates one turn's deltas and assembles the terminal assistant message. */
+export class TurnAccumulator {
+    #text = "";
+    #usage = null;
+    #calls = new Map();
+    /** Fold one decoded chunk in; returns the live events it produced. */
+    push(chunk) {
+        const events = [];
+        if (chunk.reasoning !== undefined) {
+            const event = thinkingEvent(chunk.reasoning);
+            if (event !== null)
+                events.push(event);
+        }
+        for (const choice of chunk.choices) {
+            if (choice.text !== undefined && choice.text !== "") {
+                this.#text += choice.text;
+                events.push({ kind: "text", text: choice.text });
+            }
+            for (const fragment of choice.toolCalls)
+                this.#addFragment(fragment);
+        }
+        if (chunk.usage !== undefined)
+            this.#usage = chunk.usage;
+        return events;
+    }
+    #addFragment(fragment) {
+        const entry = this.#calls.get(fragment.index) ?? { id: "", name: "", arguments: "" };
+        if (fragment.id !== undefined)
+            entry.id = fragment.id;
+        if (fragment.name !== undefined)
+            entry.name += fragment.name;
+        if (fragment.arguments !== undefined)
+            entry.arguments += fragment.arguments;
+        this.#calls.set(fragment.index, entry);
+    }
+    /** The last seen provider usage (usage-only final frame or last chunk). */
+    get usage() {
+        return this.#usage;
+    }
+    /** The assembled assistant turn (text first, then tool calls by index). */
+    doneMessage() {
+        const content = [];
+        if (this.#text !== "")
+            content.push({ type: "text", content: this.#text });
+        for (const index of [...this.#calls.keys()].sort((a, b) => a - b)) {
+            const entry = this.#calls.get(index);
+            if (entry === undefined)
+                continue;
+            content.push({
+                type: "tool_call",
+                content: { id: entry.id, name: entry.name, args: parseArguments(entry.arguments) },
+            });
+        }
+        return { role: "assistant", content, tool_call_id: null };
+    }
+}
+/**
+ * Fold a batch of frames in; `done` reports the [DONE] sentinel and `failure`
+ * an upstream error frame (W835 R3 batch C / P1-1).
+ */
+function processFrames(frames, turn) {
+    const events = [];
+    for (const frame of frames) {
+        if (frame.data === "[DONE]")
+            return { events, done: true, failure: null };
+        if (frame.event === "keepalive")
+            continue;
+        const chunk = parseRawChunk(frame.data);
+        if (chunk !== undefined) {
+            events.push(...turn.push(chunk));
+            continue;
+        }
+        const error = parseStreamError(frame.data);
+        if (error !== undefined) {
+            // An upstream error frame is a terminal failure, never skippable noise:
+            // a following [DONE] must not turn it into a fake `done`.
+            return {
+                events,
+                done: false,
+                failure: { kind: "failed", kindOf: "stream", message: "upstream stream error: " + error },
+            };
+        }
+    }
+    return { events, done: false, failure: null };
+}
+/**
+ * Byte chunks of the response body with the SSE idle guard applied to the gap
+ * between any two chunks. Throws StreamIdleAbort when the upstream stalls and
+ * the transport error itself when the body read fails mid-stream.
+ */
+export async function* readBodyChunks(response, idleMs) {
+    const queue = [];
+    let ended = false;
+    let failure = null;
+    let notify = null;
+    const wake = () => {
+        const fn = notify;
+        notify = null;
+        if (fn !== null)
+            fn();
+    };
+    const onData = (chunk) => {
+        queue.push(chunk);
+        wake();
+    };
+    const onEnd = () => {
+        ended = true;
+        wake();
+    };
+    const onError = (err) => {
+        failure = err;
+        wake();
+    };
+    const onClose = () => {
+        ended = true;
+        wake();
+    };
+    response.on("data", onData);
+    response.on("end", onEnd);
+    response.on("error", onError);
+    response.on("close", onClose);
+    response.resume();
+    try {
+        for (;;) {
+            if (queue.length > 0) {
+                const chunk = queue.shift();
+                if (chunk !== undefined)
+                    yield chunk;
+                continue;
+            }
+            if (failure !== null)
+                throw failure;
+            if (ended)
+                return;
+            await waitForData(idleMs, (resume) => (notify = resume));
+        }
+    }
+    finally {
+        response.off("data", onData);
+        response.off("end", onEnd);
+        response.off("error", onError);
+        response.off("close", onClose);
+    }
+}
+/** Wait for the next chunk; rejects with StreamIdleAbort on an idle gap. */
+function waitForData(idleMs, register) {
+    return new Promise((resolve, reject) => {
+        let timer = null;
+        register(() => {
+            if (timer !== null)
+                clearTimeout(timer);
+            resolve();
+        });
+        if (idleMs !== null) {
+            timer = setTimeout(() => {
+                register(() => { });
+                reject(new StreamIdleAbort(streamIdleTimeoutMessage(idleMs)));
+            }, idleMs);
+        }
+    });
+}
+/**
+ * Decode a 2xx SSE response into seam events. The generator always ends with
+ * exactly one terminal event (done | failed | interrupted) or an empty stream
+ * only when the caller stops iterating early.
+ */
+export async function* streamEvents(response, idleMs) {
+    const decoder = new SseDecoder();
+    const textDecoder = new StringDecoder("utf8");
+    const turn = new TurnAccumulator();
+    let sawDone = false;
+    let failure = null;
+    try {
+        for await (const bytes of readBodyChunks(response, idleMs)) {
+            const result = processFrames(decoder.push(textDecoder.write(bytes)), turn);
+            yield* result.events;
+            if (result.failure !== null) {
+                failure = result.failure;
+                break;
+            }
+            if (result.done) {
+                sawDone = true;
+                break;
+            }
+        }
+    }
+    catch (err) {
+        failure = streamFailure(err);
+    }
+    finally {
+        response.destroy();
+    }
+    // Usage rides just before the terminal event, so consumers that
+    // treat the terminal event as the end still observe it.
+    if (turn.usage !== null)
+        yield { kind: "usage", usage: turn.usage };
+    if (failure !== null) {
+        yield failure;
+        return;
+    }
+    if (!sawDone) {
+        // The upstream ended before the [DONE] sentinel: torn stream.
+        yield { kind: "interrupted" };
+        return;
+    }
+    yield { kind: "done", message: turn.doneMessage() };
+}
+/** Map a body-read failure onto its terminal event (R1: never a fake done). */
+function streamFailure(err) {
+    if (err instanceof StreamIdleAbort) {
+        // W266: a stalled stream is a terminal timeout with its own kindOf.
+        return { kind: "failed", kindOf: "timeout", message: err.message };
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return { kind: "failed", kindOf: "stream", message: `sse decode error: ${detail}` };
+}

package/dist/timeouts.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The three LLM timeout tiers (P2a).
+ *
+ * Mirrors `crates/llm/src/config.rs` +
+ * `crates/runtime/src/config.rs::resolve_llm_timeout_ms`:
+ *
+ *   * connect timeout      — TCP/TLS handshake only (15s default);
+ *   * response-header time — send() -> response headers (60s default);
+ *   * stream idle time     — gap between any two SSE data chunks (90s default).
+ *
+ * There is deliberately NO total-request timeout: a long generation streams
+ * tokens continuously and must never be killed by a response-idle guard.
+ *
+ * Precedence per tier: CELESTEA_LLM_* env var > profile key > built-in default;
+ * 0 disables that stage; blank/unparseable env values are ignored (lenient).
+ */
+export type EnvLike = Record<string, string | undefined>;
+/** Env overrides for the three timeout tiers (milliseconds). */
+export declare const CONNECT_TIMEOUT_ENV = "CELESTEA_LLM_CONNECT_TIMEOUT_MS";
+export declare const RESPONSE_TIMEOUT_ENV = "CELESTEA_LLM_RESPONSE_TIMEOUT_MS";
+export declare const STREAM_IDLE_TIMEOUT_ENV = "CELESTEA_LLM_STREAM_IDLE_TIMEOUT_MS";
+/** Default TCP/TLS connect timeout (connects are fast when healthy). */
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+/** Default send() -> response-headers timeout. */
+export declare const DEFAULT_RESPONSE_TIMEOUT_MS = 60000;
+/** Default SSE inter-chunk idle timeout. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90000;
+/** Profile JSON keys for the three tiers. */
+export declare const PROFILE_TIMEOUT_KEYS: {
+    readonly connect: "llm_connect_timeout_ms";
+    readonly response: "llm_response_timeout_ms";
+    readonly idle: "llm_stream_idle_timeout_ms";
+};
+/** The three timeout tiers as configured in a runtime profile (all optional). */
+export interface TimeoutProfile {
+    llm_connect_timeout_ms?: number | null;
+    llm_response_timeout_ms?: number | null;
+    llm_stream_idle_timeout_ms?: number | null;
+}
+/** Effective timeouts; null means "this stage is disabled" (configured 0). */
+export interface TimeoutTiers {
+    connectMs: number | null;
+    responseMs: number | null;
+    idleMs: number | null;
+}
+/** Built-in defaults (nothing configured). */
+export declare const DEFAULT_TIMEOUTS: TimeoutTiers;
+/**
+ * Milliseconds -> tier value; 0 disables (null); absent/invalid -> fallback.
+ *
+ * W835 (R3 batch D / P2-6): this is the ONE "0 = disabled" mapping, shared by
+ * the client constructor (`client.ts`) and by [tiersFromConfig]. It replaced
+ * the unused, duplicate legacy helper so a 0/null fix cannot be applied in one
+ * place and missed in the other.
+ */
+export declare function timeoutMsOf(ms: number | null | undefined, fallbackMs: number | null): number | null;
+/** Is this a usable profile/env value (non-negative integer of ms)? */
+export declare function isTimeoutMs(value: unknown): value is number;
+/**
+ * Resolve one tier: env (set, trimmed, parseable) > profile value > default.
+ */
+export declare function resolveTimeoutMs(profileValue: number | null | undefined, envValue: string | undefined, defaultMs: number): number;
+/** Resolve all three tiers (profile keys + CELESTEA_LLM_* env overrides). */
+export declare function resolveTimeoutTiers(profile?: TimeoutProfile | null, env?: EnvLike): TimeoutTiers;
+/**
+ * Lenient profile reader: non-negative integers pass through, everything else
+ * is reported (never fatal) — mirrors the strict parse in
+ * `crates/runtime/src/config.rs`.
+ */
+export declare function readTimeoutProfile(raw: unknown): {
+    profile: TimeoutProfile;
+    errors: string[];
+};

package/dist/timeouts.js

@@ -0,0 +1,121 @@
+/**
+ * The three LLM timeout tiers (P2a).
+ *
+ * Mirrors `crates/llm/src/config.rs` +
+ * `crates/runtime/src/config.rs::resolve_llm_timeout_ms`:
+ *
+ *   * connect timeout      — TCP/TLS handshake only (15s default);
+ *   * response-header time — send() -> response headers (60s default);
+ *   * stream idle time     — gap between any two SSE data chunks (90s default).
+ *
+ * There is deliberately NO total-request timeout: a long generation streams
+ * tokens continuously and must never be killed by a response-idle guard.
+ *
+ * Precedence per tier: CELESTEA_LLM_* env var > profile key > built-in default;
+ * 0 disables that stage; blank/unparseable env values are ignored (lenient).
+ */
+/** Env overrides for the three timeout tiers (milliseconds). */
+export const CONNECT_TIMEOUT_ENV = "CELESTEA_LLM_CONNECT_TIMEOUT_MS";
+export const RESPONSE_TIMEOUT_ENV = "CELESTEA_LLM_RESPONSE_TIMEOUT_MS";
+export const STREAM_IDLE_TIMEOUT_ENV = "CELESTEA_LLM_STREAM_IDLE_TIMEOUT_MS";
+/** Default TCP/TLS connect timeout (connects are fast when healthy). */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
+/** Default send() -> response-headers timeout. */
+export const DEFAULT_RESPONSE_TIMEOUT_MS = 60_000;
+/** Default SSE inter-chunk idle timeout. */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90_000;
+/** Profile JSON keys for the three tiers. */
+export const PROFILE_TIMEOUT_KEYS = {
+    connect: "llm_connect_timeout_ms",
+    response: "llm_response_timeout_ms",
+    idle: "llm_stream_idle_timeout_ms",
+};
+/** Built-in defaults (nothing configured). */
+export const DEFAULT_TIMEOUTS = {
+    connectMs: DEFAULT_CONNECT_TIMEOUT_MS,
+    responseMs: DEFAULT_RESPONSE_TIMEOUT_MS,
+    idleMs: DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+};
+/**
+ * Milliseconds -> tier value; 0 disables (null); absent/invalid -> fallback.
+ *
+ * W835 (R3 batch D / P2-6): this is the ONE "0 = disabled" mapping, shared by
+ * the client constructor (`client.ts`) and by [tiersFromConfig]. It replaced
+ * the unused, duplicate legacy helper so a 0/null fix cannot be applied in one
+ * place and missed in the other.
+ */
+export function timeoutMsOf(ms, fallbackMs) {
+    if (ms === null || ms === undefined)
+        return fallbackMs;
+    if (!Number.isFinite(ms) || ms < 0)
+        return fallbackMs;
+    return ms === 0 ? null : Math.floor(ms);
+}
+/** Parse an env value as a non-negative integer of milliseconds. */
+function parseEnvMs(envValue) {
+    if (envValue === undefined)
+        return undefined;
+    const trimmed = envValue.trim();
+    if (!/^[0-9]+$/.test(trimmed))
+        return undefined;
+    const value = Number(trimmed);
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+/** Is this a usable profile/env value (non-negative integer of ms)? */
+export function isTimeoutMs(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/**
+ * Resolve one tier: env (set, trimmed, parseable) > profile value > default.
+ */
+export function resolveTimeoutMs(profileValue, envValue, defaultMs) {
+    const fromEnv = parseEnvMs(envValue);
+    if (fromEnv !== undefined)
+        return fromEnv;
+    if (isTimeoutMs(profileValue))
+        return profileValue;
+    return defaultMs;
+}
+/** Resolve all three tiers (profile keys + CELESTEA_LLM_* env overrides). */
+export function resolveTimeoutTiers(profile, env = process.env) {
+    return {
+        connectMs: resolveTimeoutMs(profile?.llm_connect_timeout_ms, env[CONNECT_TIMEOUT_ENV], DEFAULT_CONNECT_TIMEOUT_MS),
+        responseMs: resolveTimeoutMs(profile?.llm_response_timeout_ms, env[RESPONSE_TIMEOUT_ENV], DEFAULT_RESPONSE_TIMEOUT_MS),
+        idleMs: resolveTimeoutMs(profile?.llm_stream_idle_timeout_ms, env[STREAM_IDLE_TIMEOUT_ENV], DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+    };
+}
+/**
+ * Lenient profile reader: non-negative integers pass through, everything else
+ * is reported (never fatal) — mirrors the strict parse in
+ * `crates/runtime/src/config.rs`.
+ */
+export function readTimeoutProfile(raw) {
+    const profile = {};
+    const errors = [];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { profile, errors };
+    }
+    const obj = raw;
+    const fields = [
+        ["llm_connect_timeout_ms", PROFILE_TIMEOUT_KEYS.connect],
+        ["llm_response_timeout_ms", PROFILE_TIMEOUT_KEYS.response],
+        ["llm_stream_idle_timeout_ms", PROFILE_TIMEOUT_KEYS.idle],
+    ];
+    for (const [field, key] of fields) {
+        const value = obj[key];
+        if (value === undefined || value === null)
+            continue;
+        if (isTimeoutMs(value))
+            profile[field] = value;
+        else
+            errors.push(`profile field '${key}' must be a non-negative integer (ms), got ${jsonKind(value)}`);
+    }
+    return { profile, errors };
+}
+function jsonKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist/transport.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HTTP transport for the streaming request (P2a).
+ *
+ * Owns the two pre-stream guards of the three-tier timeout contract:
+ *   * connect timeout      — the TCP/TLS handshake must complete in time;
+ *   * response-header time — send() -> response headers must arrive in time.
+ * Beyond the headers the body is guarded per chunk by the stream idle timeout
+ * (see stream.ts). There is deliberately NO total-request timeout, so a long
+ * generation is never killed by a pre-stream guard.
+ *
+ * The API key rides only in the request's Authorization header; error messages
+ * carry the HTTP status plus a body snippet, never a credential.
+ */
+import http from "node:http";
+/** Max bytes of a non-2xx body echoed in the error message. */
+export declare const ERROR_BODY_SNIPPET_BYTES = 2048;
+export interface SendOptions {
+    url: string;
+    apiKey: string;
+    body: string;
+    /** null = connect guard disabled. */
+    connectMs: number | null;
+    /** null = response-header guard disabled. */
+    responseMs: number | null;
+}
+/** POST the request; resolve once the response HEADERS are in. */
+export declare function sendChatRequest(options: SendOptions): Promise<http.IncomingMessage>;
+/** Read at most `limit` bytes of a body for error reporting. */
+export declare function readBodySnippet(response: http.IncomingMessage, limit?: number): Promise<string>;
+/** "500 Internal Server Error" style label for an error message. */
+export declare function httpStatusLabel(status: number, statusText: string | undefined): string;
+/**
+ * Belt-and-braces: never let a credential-shaped token ride out in an error.
+ *
+ * W824 (W811 P0-1 + N2): the shape rule tolerates whitespace after "Bearer"
+ * (the standard "Bearer <token>" form) and is case-insensitive. knownSecrets
+ * are the client's OWN keys and are replaced literally, because an arbitrary
+ * provider key echoed as "invalid api key: 9f8e..." has no recognizable shape;
+ * this mirrors core's registered-secret pass.
+ */
+export declare function redact(text: string, knownSecrets?: readonly string[]): string;

package/dist/transport.js

@@ -0,0 +1,147 @@
+/**
+ * HTTP transport for the streaming request (P2a).
+ *
+ * Owns the two pre-stream guards of the three-tier timeout contract:
+ *   * connect timeout      — the TCP/TLS handshake must complete in time;
+ *   * response-header time — send() -> response headers must arrive in time.
+ * Beyond the headers the body is guarded per chunk by the stream idle timeout
+ * (see stream.ts). There is deliberately NO total-request timeout, so a long
+ * generation is never killed by a pre-stream guard.
+ *
+ * The API key rides only in the request's Authorization header; error messages
+ * carry the HTTP status plus a body snippet, never a credential.
+ */
+import http from "node:http";
+import https from "node:https";
+import { connectTimeoutError, networkError, responseHeaderTimeoutError } from "./errors.js";
+/** Max bytes of a non-2xx body echoed in the error message. */
+export const ERROR_BODY_SNIPPET_BYTES = 2048;
+/** Settle-once state machine owning the pending timers and the request. */
+class StageGuard {
+    #settled = false;
+    #timers = [];
+    #request = null;
+    #reject;
+    constructor(reject) {
+        this.#reject = reject;
+    }
+    attach(request) {
+        this.#request = request;
+    }
+    settle(fn) {
+        if (this.#settled)
+            return;
+        this.#settled = true;
+        for (const timer of this.#timers)
+            clearTimeout(timer);
+        this.#timers.length = 0;
+        fn();
+    }
+    /** Reject with a timeout/transport error and tear the request down. */
+    abort(err) {
+        if (this.#settled)
+            return;
+        const request = this.#request;
+        this.settle(() => this.#reject(err));
+        request?.destroy();
+    }
+    /** Abort when the TCP/TLS handshake has not completed within `ms`. */
+    armConnect(ms, url) {
+        if (ms === null)
+            return;
+        let connected = false;
+        this.#request?.on("socket", (socket) => {
+            if (socket.connecting)
+                socket.once("connect", () => (connected = true));
+            else
+                connected = true;
+        });
+        this.#timers.push(setTimeout(() => {
+            if (!connected)
+                this.abort(connectTimeoutError(ms, url));
+        }, ms));
+    }
+    /** Abort when the response headers have not arrived within `ms`. */
+    armResponse(ms, url) {
+        if (ms === null)
+            return;
+        this.#timers.push(setTimeout(() => {
+            this.abort(responseHeaderTimeoutError(ms, url));
+        }, ms));
+    }
+}
+function requestHeaders(options) {
+    return {
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        "content-length": String(Buffer.byteLength(options.body)),
+        authorization: `Bearer ${options.apiKey}`,
+    };
+}
+/** POST the request; resolve once the response HEADERS are in. */
+export async function sendChatRequest(options) {
+    let parsed;
+    try {
+        parsed = new URL(options.url);
+    }
+    catch {
+        // W835 (R3 batch E / P2-4): a bad base_url is a pre-stream config failure
+        // and MUST reject as an LlmError (the client.ts contract), not a bare
+        // TypeError. It stays retryable so a fallback chain can hand over to a
+        // healthy target; the url is redacted so a credential inside it never
+        // reaches the message.
+        throw networkError("invalid base_url for llm request: " + redact(options.url));
+    }
+    const transport = parsed.protocol === "https:" ? https : http;
+    return await new Promise((resolve, reject) => {
+        const guard = new StageGuard(reject);
+        const request = transport.request(parsed, { method: "POST", headers: requestHeaders(options), agent: false }, (response) => guard.settle(() => resolve(response)));
+        guard.attach(request);
+        request.on("error", (err) => {
+            guard.settle(() => reject(networkError(`failed to start stream: ${err.message}`)));
+        });
+        guard.armConnect(options.connectMs, options.url);
+        guard.armResponse(options.responseMs, options.url);
+        request.end(options.body);
+    });
+}
+/** Read at most `limit` bytes of a body for error reporting. */
+export async function readBodySnippet(response, limit = ERROR_BODY_SNIPPET_BYTES) {
+    const parts = [];
+    let size = 0;
+    try {
+        for await (const chunk of response) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            parts.push(buf);
+            size += buf.byteLength;
+            if (size >= limit)
+                break;
+        }
+    }
+    catch {
+        // Best effort: an unreadable body still yields a status-bearing error.
+    }
+    return Buffer.concat(parts).subarray(0, limit).toString("utf8");
+}
+/** "500 Internal Server Error" style label for an error message. */
+export function httpStatusLabel(status, statusText) {
+    return statusText === undefined || statusText === "" ? String(status) : `${status} ${statusText}`;
+}
+/**
+ * Belt-and-braces: never let a credential-shaped token ride out in an error.
+ *
+ * W824 (W811 P0-1 + N2): the shape rule tolerates whitespace after "Bearer"
+ * (the standard "Bearer <token>" form) and is case-insensitive. knownSecrets
+ * are the client's OWN keys and are replaced literally, because an arbitrary
+ * provider key echoed as "invalid api key: 9f8e..." has no recognizable shape;
+ * this mirrors core's registered-secret pass.
+ */
+export function redact(text, knownSecrets = []) {
+    let out = text;
+    const keys = [...new Set(knownSecrets.filter((s) => typeof s === "string" && s.length >= 8))].sort((a, b) => b.length - a.length);
+    for (const key of keys) {
+        if (out.includes(key))
+            out = out.split(key).join("<redacted>");
+    }
+    return out.replace(/\b(?:sk|bearer)\s*[-_A-Za-z0-9._~+/=]{8,}/gi, "<redacted>");
+}