@linxiraos/pi-ai 1.0.0

package/dist/types/utils/empty-completion-retry.d.ts

@@ -0,0 +1,21 @@
+import type { AssistantMessage, Context } from "../types.js";
+import { AssistantMessageEventStream } from "./event-stream.js";
+export declare const MAX_EMPTY_COMPLETION_RETRIES = 2;
+export declare const EMPTY_COMPLETION_BASE_DELAY_MS = 500;
+/**
+ * Whether a completed assistant message carries content worth delivering: an
+ * image, tool call, or any non-whitespace text. An empty/whitespace-only message
+ * — or one that only ever produced thinking — is the "empty response" failure.
+ */
+export declare function hasVisibleAssistantContent(message: AssistantMessage): boolean;
+interface EmptyCompletionRetryOptions {
+    signal?: AbortSignal;
+    providerRetryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap a single-attempt provider stream with bounded empty-completion retries.
+ * `attempt` MUST create a fresh request (and its own output message) on each
+ * call so a retry never inherits stale metadata from an empty attempt.
+ */
+export declare function withEmptyCompletionRetry<M, O extends EmptyCompletionRetryOptions>(model: M, context: Context, options: O | undefined, attempt: (model: M, context: Context, options?: O) => AssistantMessageEventStream): AssistantMessageEventStream;
+export {};

package/dist/types/utils/event-stream.d.ts

@@ -0,0 +1,39 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types.js";
+export declare class EventStream<T, R = T> implements AsyncIterable<T> {
+    #private;
+    queue: T[];
+    waiting: Array<{
+        resolve: (value: IteratorResult<T>) => void;
+        reject: (err: unknown) => void;
+    }>;
+    done: boolean;
+    /** True once finalResultPromise has been resolved or rejected. */
+    resultSettled: boolean;
+    finalResultPromise: Promise<R>;
+    resolveFinalResult: (result: R) => void;
+    rejectFinalResult: (err: unknown) => void;
+    isComplete: (event: T) => boolean;
+    extractResult: (event: T) => R;
+    constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R);
+    push(event: T): void;
+    deliver(event: T): void;
+    end(result?: R): void;
+    endWaiting(): void;
+    fail(err: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    result(): Promise<R>;
+    /** True while local work tracked via {@link trackLocalWork} is pending. */
+    get hasPendingLocalWork(): boolean;
+    /**
+     * Track a local-work promise so idle watchdogs on this stream do not treat
+     * the event silence while it is pending as a provider stall.
+     */
+    trackLocalWork<TWork>(work: Promise<TWork>): Promise<TWork>;
+}
+export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor();
+    push(event: AssistantMessageEvent): void;
+    end(result?: AssistantMessage): void;
+}
+/** Create an assistant-message event stream for legacy extension providers. */
+export declare function createAssistantMessageEventStream(): AssistantMessageEventStream;

package/dist/types/utils/foundry.d.ts

@@ -0,0 +1 @@
+export declare function isFoundryEnabled(): boolean;

package/dist/types/utils/google-validation.d.ts

@@ -0,0 +1,2 @@
+export declare function extractGoogleValidationUrl(errorBody: string): string | undefined;
+export declare function formatGoogleValidationRequiredMessage(validationUrl: string, nextAction: string, email?: string): string;

package/dist/types/utils/harmony-leak.d.ts

@@ -0,0 +1,135 @@
+import type { AssistantMessage, Model, ToolCall } from "../types.js";
+/**
+ * Escape reserved Harmony control tokens in arbitrary text so it can be
+ * transported as data to a harmony-dialect model. Returns the input unchanged
+ * when it carries no reserved spelling.
+ *
+ * Callers MUST gate on a harmony target and escape only the transport copy —
+ * the persisted transcript keeps the byte-for-byte original.
+ */
+export declare function escapeHarmonyControlTokens(text: string): string;
+/**
+ * Escape reserved Harmony control tokens inside a JSON document string (e.g.
+ * `function_call.arguments`). Doubles the backslash so the document remains
+ * valid JSON whose *decoded* strings carry the inert `<\|token\|>` spelling.
+ * `<|` cannot occur outside a string literal in valid JSON, so the blanket
+ * replace never corrupts structure; malformed documents are escaped
+ * best-effort.
+ */
+export declare function escapeHarmonyControlTokensInJson(text: string): string;
+/**
+ * Whether requests to `model` are served by a Harmony-dialect backend
+ * (gpt-5.x / gpt-oss), which rejects reserved control-token spellings appearing
+ * as data in the request. Resolves the wire model id (`requestModelId ?? id`)
+ * so deployment/catalog aliases — e.g. an Azure alias whose `requestModelId` is
+ * `gpt-5.4` — are detected even when the local id is opaque.
+ */
+export declare function isHarmonyDialectModel(model: Model): boolean;
+declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
+export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+export interface HarmonySignal {
+    classes: HarmonySignalClass[];
+    start: number;
+    end: number;
+    text: string;
+}
+export interface HarmonyDetection {
+    surface: HarmonySurface;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+    signals: HarmonySignal[];
+}
+export interface HarmonyAuditEvent {
+    action: "truncate_resume" | "abort_retry" | "escalated";
+    surface: HarmonySurface;
+    signal: string;
+    retryN: number;
+    model: string;
+    provider: string;
+    toolName?: string;
+    removedLen: number;
+    removedSha8: string;
+    removedPreview: string;
+    removedBlob?: string;
+}
+export interface HarmonyRecoveredToolCall {
+    message: AssistantMessage;
+    removed: string;
+}
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every openai-codex model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export declare function isHarmonyLeakMitigationTarget(model: Model): boolean;
+export declare function signalListLabel(signals: readonly HarmonySignal[]): string;
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * The `tool_arg` surface is held to a stricter rule. A tool argument is
+ * arbitrary file/data content that can legitimately carry the marker, a
+ * channel word, harmony control tokens, or a non-Latin script run (editing
+ * these very fixtures does exactly that). The only robust leak signal there
+ * is content trailing the structurally-valid parse, so a `tool_arg` detection
+ * additionally requires the `T` co-signal. Absent a `parsedEnd` boundary `T`
+ * is never set, so `tool_arg` scanning stays inert and a legitimate codex tool
+ * call is never hard-aborted. `assistant_text`/`assistant_thinking` keep the
+ * base rule.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers at or past it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export declare function detectHarmonyLeak(text: string, surface: HarmonySurface, options?: {
+    parsedEnd?: number;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+}): HarmonyDetection | undefined;
+/**
+ * Scan an assistant message's content blocks; return the first detection.
+ *
+ * `toolArgParseEnd`, when supplied, resolves the byte offset at which a tool
+ * call's structurally-valid argument parse ends (the `T` co-signal in
+ * {@link detectHarmonyLeak}). Callers that can parse a tool's argument DSL pass
+ * it to enable `tool_arg` leak detection; omitting it keeps that surface inert
+ * — the safe default the agent loop relies on, since it cannot bound a streamed
+ * tool DSL and must never hard-abort a legitimate tool call.
+ */
+export declare function detectHarmonyLeakInAssistantMessage(message: AssistantMessage, toolArgParseEnd?: (toolCall: ToolCall) => number | undefined): HarmonyDetection | undefined;
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for Codex the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export declare function recoverHarmonyToolCall(message: AssistantMessage, detection: HarmonyDetection): HarmonyRecoveredToolCall | undefined;
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export declare function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string;
+export declare function createHarmonyAuditEvent(params: {
+    action: HarmonyAuditEvent["action"];
+    detection: HarmonyDetection;
+    model: Model;
+    retryN: number;
+    removed: string;
+}): HarmonyAuditEvent;
+export {};

package/dist/types/utils/http-inspector.d.ts

@@ -0,0 +1,49 @@
+export type RawHttpRequestDump = {
+    provider: string;
+    api: string;
+    model: string;
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+export type CapturedHttpErrorResponse = {
+    status: number;
+    headers?: Headers;
+    bodyText?: string;
+    bodyJson?: unknown;
+};
+/**
+ * Build the JSON persisted for a rejected request. Request fields stay at the
+ * top level (so existing dump parsers still read `body`); the provider's error
+ * is added under `errorResponse` so a failed request is diagnosable from the
+ * dump file rather than the request alone.
+ */
+export declare function buildHttp400DumpPayload(dump: RawHttpRequestDump, error: unknown, message: string): RawHttpRequestDump & {
+    errorResponse: {
+        status: number | undefined;
+        message: string;
+    };
+};
+/** HTTP statuses whose rejected request we persist for post-hoc diagnosis: the
+ *  request-content rejections that wedge a session. 400 (bad request) and 413
+ *  (payload too large — an oversized image / snapcompact frame payload that 413s
+ *  and empties the turn). Auth (401/403), not-found (404), rate limits and 5xx
+ *  are excluded: 429/5xx are retried, so persisting them here would write one
+ *  dump per attempt. */
+export declare function shouldDumpRejectedRequest(error: unknown): boolean;
+export declare function appendRawHttpRequestDumpFor400(message: string, error: unknown, dump: RawHttpRequestDump | undefined): Promise<string>;
+export declare function finalizeErrorMessage(error: unknown, rawRequestDump: RawHttpRequestDump | undefined, capturedErrorResponse?: CapturedHttpErrorResponse): Promise<string>;
+/**
+ * Rewrite error message for GitHub Copilot request failures.
+ * Must run AFTER finalizeErrorMessage since it replaces the message entirely.
+ *
+ * 400 `model_not_supported` = Copilot fleet skew. A model that `/models`
+ *        advertises can flap between 200 and 400 because only part of
+ *        Copilot's fleet has it in the integrator allowlist. After the
+ *        in-request retry exhausts, surface guidance rather than the raw error.
+ * 401 = token invalid/expired → credential removal is safe, prompt re-login.
+ * 403 = token valid but access denied (plan, model policy, org restriction) →
+ *       do NOT reuse the auth-failed string (which triggers credential removal).
+ */
+export declare function rewriteCopilotError(errorMessage: string, error: unknown, provider: string): string;

package/dist/types/utils/idle-iterator.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Returns the idle timeout used for provider streaming transports.
+ *
+ * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * Set `PI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers that legitimately stream much slower than the global default can pass
+ * `fallbackMs` to widen the floor used when neither env var nor caller option is set.
+ * Caller options still take precedence; env overrides still trump the fallback.
+ */
+export declare function getStreamIdleTimeoutMs(fallbackMs?: number): number | undefined;
+/**
+ * Returns the idle timeout used for OpenAI-family streaming transports.
+ *
+ * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` takes precedence over the generic
+ * `PI_STREAM_IDLE_TIMEOUT_MS` because some deployments tune OpenAI-compatible
+ * backends separately from Anthropic/Gemini-style transports.
+ *
+ * Set `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ */
+export declare function getOpenAIStreamIdleTimeoutMs(fallbackMs?: number): number | undefined;
+/**
+ * Returns the timeout used while waiting for the first stream event.
+ * The first token can legitimately take longer than later inter-event gaps,
+ * so the default never undershoots the steady-state idle timeout.
+ *
+ * Set `PI_STREAM_FIRST_EVENT_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers whose first response can legitimately take longer (heavy reasoning,
+ * slow cold-start proxies) can pass `fallbackMs` to widen the floor used when
+ * neither env var nor caller option is set. Caller options still take precedence;
+ * env overrides still trump the fallback.
+ */
+export declare function getStreamFirstEventTimeoutMs(idleTimeoutMs?: number, fallbackMs?: number): number | undefined;
+/**
+ * Returns the first-event timeout used for OpenAI-family streaming transports.
+ *
+ * Precedence: explicit `PI_OPENAI_STREAM_FIRST_EVENT_TIMEOUT_MS` (including a
+ * `"0"` disable) wins outright. Otherwise the resolved idle (caller-supplied
+ * `idleTimeoutMs` — which itself already encompasses per-call
+ * `streamIdleTimeoutMs` or `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` resolved
+ * upstream) floors the first-event budget so slow OpenAI-compatible servers
+ * are not undercut by a shorter `PI_STREAM_FIRST_EVENT_TIMEOUT_MS` or the
+ * global default during prompt processing. A zero per-provider fallback
+ * disables the first-event watchdog unless an environment override is set.
+ *
+ * Returns `0` when an explicit env knob or per-provider fallback disables the
+ * watchdog, preserving the sentinel through iterator timeout resolution.
+ */
+export declare function getOpenAIStreamFirstEventTimeoutMs(idleTimeoutMs?: number, fallbackMs?: number): number | undefined;
+/**
+ * Arms a clearable pre-response (time-to-first-byte) abort guard for a streaming
+ * fetch, combined with the caller's signal.
+ *
+ * `AbortSignal.timeout(ms)` is an *absolute* wall-clock deadline: once handed to
+ * `fetch` it keeps governing the request after the response headers arrive, so
+ * it aborts an actively-streaming body the moment it fires — not just a stalled
+ * pre-response request (issue #2422 regression: large `write` tool-call streams
+ * died at the budget with `TimeoutError: The operation timed out.` despite
+ * deltas actively flowing). This arms a `clearTimeout`-able timer instead;
+ * callers MUST `clear()` as soon as the guarded transport attempt settles so
+ * the body stream is left to the iterator-level idle watchdog.
+ *
+ * Retrying callers MUST arm a fresh guard for each transport attempt and keep
+ * the retry loop's base signal reserved for caller cancellation. Reusing the
+ * guard as the loop signal makes its timeout indistinguishable from cancellation.
+ *
+ * Returns the caller signal unchanged (and a no-op `clear`) when no positive
+ * timeout is configured.
+ */
+export declare function armPreResponseTimeout(callerSignal: AbortSignal | undefined, timeoutMs: number | undefined): {
+    signal: AbortSignal | undefined;
+    clear: () => void;
+};
+export interface IdleTimeoutIteratorOptions {
+    idleTimeoutMs?: number;
+    firstItemTimeoutMs?: number;
+    errorMessage: string;
+    firstItemErrorMessage?: string;
+    onIdle?: () => void;
+    onFirstItemTimeout?: () => void;
+    /**
+     * Optional semantic-progress predicate. Non-progress items are still yielded,
+     * but they do not reset the idle deadline. This prevents provider
+     * keepalive/no-op events from keeping a stalled tool call alive forever.
+     */
+    isProgressItem?: (item: unknown) => boolean;
+    /**
+     * Reports consumer-side local work in flight for the stream: the provider
+     * transport is waiting on a server-requested local tool bridge (e.g. the
+     * Cursor exec channel) before anything can flow upstream again. While it
+     * returns true, an expired idle / first-item deadline slides forward
+     * instead of aborting — the silence is ours, not a provider stall. The
+     * watchdog re-arms with a full budget once the local work completes, so a
+     * provider that stalls afterwards is still caught.
+     */
+    hasPendingLocalWork?: () => boolean;
+    /**
+     * Cancel iteration as soon as this signal aborts. Required for caller-driven
+     * cancellation (ESC) when the underlying transport does not surface signal
+     * aborts to the iterator (HTTP/2 proxies, native sockets, mocked fetch).
+     * Without this, the consumer sleeps on iterator.next() until the idle/first
+     * -event watchdog fires — observable as the issue #912 "Working… forever"
+     * symptom on the github-copilot provider.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Yields items from an async iterable while enforcing a maximum idle gap between items.
+ *
+ * The first item may use a shorter timeout so stuck requests can be aborted and retried
+ * before any user-visible content has streamed.
+ */
+export declare function iterateWithIdleTimeout<T>(iterable: AsyncIterable<T>, options: IdleTimeoutIteratorOptions): AsyncGenerator<T>;
+export interface TerminalGraceIteratorOptions {
+    /**
+     * Epoch-ms timestamp at which the consumer observed a logically terminal
+     * item (e.g. a chat-completions chunk carrying `finish_reason`), or
+     * `undefined` while the stream is still mid-response. Read before every
+     * pull, so the consumer can flip it between yields.
+     */
+    finishedAtMs: () => number | undefined;
+    /**
+     * Post-terminal budget: how long after `finishedAtMs()` to keep draining
+     * trailing items (e.g. a usage-only chunk or the `[DONE]` sentinel) before
+     * ending the iteration cleanly. The deadline is fixed at
+     * `finishedAtMs() + graceMs`; trailing items do not extend it, so
+     * keepalive-only servers cannot hold the stream open.
+     */
+    graceMs: number;
+    /**
+     * Invoked when the grace window closes with the source still open. Use it
+     * to abort the underlying request: the source generator is typically parked
+     * mid-`next()` (not at a yield), so a queued `.return()` alone cannot reach
+     * the transport until that pending read settles.
+     */
+    onGraceEnd?: () => void;
+}
+/**
+ * Yields items from an async iterable until the consumer marks the stream
+ * logically finished AND the source stays silent past a short grace window.
+ *
+ * Misbehaving OpenAI-compatible servers deliver the terminal chunk but never
+ * send `[DONE]` nor close the connection; without this guard the consumer
+ * hangs on `iterator.next()` until the idle watchdog converts an
+ * already-successful turn into a timeout error. Grace expiry is a clean end
+ * of iteration, never an error.
+ */
+export declare function iterateWithTerminalGrace<T>(iterable: AsyncIterable<T>, options: TerminalGraceIteratorOptions): AsyncGenerator<T>;

package/dist/types/utils/leaked-thinking-stream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Central live healing for leaked reasoning markup in the visible text channel.
+ *
+ * Some providers emit their canonical reasoning idioms (` ```thinking `,
+ * `<think>`, Gemma/Harmony channels, …) into the *visible* text stream instead
+ * of a structured thinking part. {@link wrapLeakedThinkingStream} re-projects a
+ * provider stream into a fresh {@link AssistantMessageEventStream}, splitting the
+ * leaked fences out into proper `thinking` blocks *live* as deltas arrive.
+ *
+ * Applied to every provider stream *except* official first-party endpoints
+ * (the official Anthropic API and the official OpenAI / OpenAI-Codex endpoints),
+ * which return structured thinking and never leak — `healLeakedThinking` in
+ * `../stream.ts` gates the wrap so the healer cannot misfire on legitimate
+ * fenced content those models emit as visible text.
+ *
+ * The healing is idempotent: a second pass over already-clean text finds no
+ * fences, so wrapping a provider that already heals (or wrapping twice) is a
+ * harmless pass-through. Signatures are load-bearing for Google/Gemini/Vertex
+ * thought round-tripping, so text sub-blocks carry the source `textSignature`,
+ * forwarded thinking blocks their `thinkingSignature`, and forwarded tool calls
+ * their `thoughtSignature`.
+ *
+ * Modeled on {@link wrapInbandToolStream} / `InbandStreamProjector` in
+ * `../dialect/owned-stream.ts`, minus all in-band tool-call grammar: tool-call
+ * events are forwarded verbatim.
+ */
+import { AssistantMessageEventStream } from "./event-stream.js";
+/**
+ * Wrap a provider stream so leaked reasoning fences are healed into thinking
+ * blocks live, for every provider. Returns a new stream that re-projects the
+ * inner one; the inner stream is fully consumed.
+ */
+export declare function wrapLeakedThinkingStream(inner: AssistantMessageEventStream): AssistantMessageEventStream;

package/dist/types/utils/openai-http.d.ts

@@ -0,0 +1,48 @@
+/**
+ * JSON-POST → SSE transport for OpenAI-wire streaming endpoints (chat
+ * completions, responses, azure responses). Replaces the `openai` SDK client:
+ *
+ * - Retries: `fetchWithRetry` (Retry-After/quota-hint aware; 5xx/408/429 and
+ *   transient network errors). Default 6 total attempts — parity with the
+ *   SDK's former `maxRetries: 5`.
+ * - SSE decode: `readSseJson` (spec-compliant framing, `[DONE]`-aware).
+ *   `onSseEvent` observers now receive real wire frames instead of events
+ *   re-synthesized from decoded SDK objects.
+ * - Errors: {@link OpenAIHttpError} exposes `status`/`headers`/`code`
+ *   structurally (ProviderHttpError contract — `extractHttpStatusFromError`,
+ *   retry-after extraction, copilot transient classification) and carries the
+ *   captured response body for the strict-tools fallback and the responses
+ *   chain-state detectors, which regex over `error.message`.
+ */
+import { type SseEventObserver } from "@linxiraos/pi-utils";
+import * as AIError from "../error/index.js";
+import { OpenAIHttpError } from "../error/index.js";
+export { OpenAIHttpError };
+import type { FetchImpl } from "../types.js";
+export interface OpenAIStreamRequestInit {
+    url: string;
+    headers: Record<string, string>;
+    /** JSON request body; serialized once per call (retries resend the same bytes). */
+    body: unknown;
+    signal: AbortSignal;
+    fetch?: FetchImpl;
+    /** Raw wire-frame observer (`onSseEvent` debug pipeline). */
+    onSseEvent?: SseEventObserver;
+}
+export interface OpenAIStreamHandle<TEvent> {
+    /** Decoded `data:` payloads; terminates on `[DONE]` or stream end. */
+    events: AsyncGenerator<TEvent>;
+    response: Response;
+    /** `x-request-id` response header (the SDK's former `request_id`). */
+    requestId: string | null;
+}
+/**
+ * POST a JSON body and stream back decoded SSE events.
+ *
+ * Throws {@link OpenAIHttpError} on a non-2xx terminal response. Aborts on
+ * `signal` propagate from `fetchWithRetry`/`readSseJson`; callers own the
+ * watchdog timers and abort-reason bookkeeping.
+ */
+export declare function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): Promise<OpenAIStreamHandle<TEvent>>;
+/** Decode a non-2xx response into an {@link OpenAIHttpError} without consuming it twice. */
+export declare function captureOpenAIHttpError(response: Response): Promise<AIError.OpenAIHttpError>;

package/dist/types/utils/openrouter-headers.d.ts

@@ -0,0 +1 @@
+export declare function getOpenRouterHeaders(): Record<string, string>;

package/dist/types/utils/parse-bind.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared `host:port` parser used by the auth-broker and auth-gateway boot
+ * paths. Centralized so the two servers can't drift on what they accept (the
+ * gateway used to silently allow empty hostnames; this fixes it).
+ */
+export interface ParsedBind {
+    hostname: string;
+    port: number;
+}
+/**
+ * Parse a `host:port` (or bare `port`, which assumes loopback) string.
+ *
+ * Accepts:
+ *   - `"4000"`            → `127.0.0.1:4000`
+ *   - `"0.0.0.0:4000"`    → as written
+ *   - `"[::1]:4000"`      → as written (brackets retained, Bun handles them)
+ *
+ * Rejects:
+ *   - empty input
+ *   - empty hostname (`":4000"`)
+ *   - non-integer / out-of-range port
+ */
+export declare function parseBind(raw: string): ParsedBind;

package/dist/types/utils/provider-response.d.ts

@@ -0,0 +1,3 @@
+import type { Api, Model, ProviderResponseMetadata, StreamOptions } from "../types.js";
+export declare function normalizeProviderResponse(response: Response, requestId?: string | null, metadata?: Record<string, unknown>): ProviderResponseMetadata;
+export declare function notifyProviderResponse(options: Pick<StreamOptions, "onResponse"> | undefined, response: Response, model?: Model<Api>, requestId?: string | null, metadata?: Record<string, unknown>): Promise<void>;

package/dist/types/utils/proxy.d.ts

@@ -0,0 +1,39 @@
+import * as tls from "node:tls";
+import type { FetchImpl } from "../types.js";
+/**
+ * Checks if a host is local or cloud metadata, which should always bypass the proxy
+ * (e.g. localhost, 127/8, ::1, 169.254.169.254, metadata.google.internal).
+ */
+export declare function isLocalOrMetadataHost(host: string): boolean;
+/**
+ * Check if the url should bypass the proxy due to hard-coded localhost/metadata checks
+ * or custom NO_PROXY/no_proxy environment variables rules.
+ */
+export declare function shouldBypassProxy(urlObj: URL): boolean;
+/** Test seam: clears the provider proxy cache. */
+export declare function __resetProxyCache(): void;
+/**
+ * Normalizes provider id (e.g. github-copilot -> PI_PROXY_GITHUB_COPILOT) and looks it up.
+ * If not found, falls back to PI_PROXY. Results are memoized because env values are static
+ * for the lifetime of the process and this function is called for every outgoing request.
+ */
+export declare function getProxyForProvider(provider: string): string | undefined;
+/** Resolves provider-specific and standard proxy variables for a target URL, honoring NO_PROXY. */
+export declare function getProxyForUrl(provider: string, url: URL): string | undefined;
+/**
+ * Wraps a fetch implementation to inject proxy options for non-local hosts.
+ */
+export declare function wrapFetchForProxy(fetchImpl: FetchImpl, provider: string): FetchImpl;
+export interface ConnectProxiedSocketOptions {
+    /** Caller cancellation for the proxy TCP/TLS handshake and CONNECT tunnel. */
+    signal?: AbortSignal;
+    /** Maximum wall-clock time to establish the final TLS tunnel. Disabled when absent or non-positive. */
+    timeoutMs?: number;
+    /** Target TLS profile. Cursor defaults to HTTP/2 when this is absent. */
+    tls?: tls.ConnectionOptions;
+}
+/**
+ * Tunnel a socket connection through an HTTP CONNECT proxy.
+ * This is used specifically to wrap Node's `http2.connect(baseUrl, { createConnection })` for Cursor.
+ */
+export declare function connectProxiedSocket(proxyUrlStr: string, targetUrlStr: string, options?: ConnectProxiedSocketOptions): Promise<tls.TLSSocket>;

package/dist/types/utils/request-debug.d.ts

@@ -0,0 +1,29 @@
+import type { FetchImpl } from "../types.js";
+export type RequestDebugHeaders = Headers | Record<string, string | string[] | number | undefined | null> | undefined;
+export interface RequestDebugPayload {
+    method: string;
+    url: string;
+    headers?: RequestDebugHeaders;
+    body?: unknown;
+    bodyText?: string;
+    bodyBase64?: string;
+    bodyUnavailable?: string;
+    protocol?: string;
+}
+export interface RequestDebugResponseLog {
+    write(chunk: Uint8Array | string): void;
+    close(): Promise<void>;
+}
+export interface RequestDebugSession {
+    readonly id: number;
+    readonly requestPath: string;
+    readonly responsePath: string;
+    openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog>;
+    wrapResponse(response: Response): Promise<Response>;
+}
+export declare function isRequestDebugEnabled(): boolean;
+export declare function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl;
+export declare function withRequestDebugFetch<T extends {
+    fetch?: FetchImpl;
+} | undefined>(options: T): T;
+export declare function createRequestDebugSession(payload: RequestDebugPayload): Promise<RequestDebugSession>;

package/dist/types/utils/retry-after.d.ts

@@ -0,0 +1,4 @@
+export type HeadersLike = Headers | Record<string, string | undefined> | undefined | null;
+export declare function formatErrorMessageWithRetryAfter(error: unknown, headers?: HeadersLike): string;
+export declare function getRetryAfterMsFromHeaders(headers: HeadersLike): number | undefined;
+export declare function getHeadersFromError(error: unknown): HeadersLike;

package/dist/types/utils/retry.d.ts

@@ -0,0 +1,14 @@
+import { isCopilotTransientModelError } from "../error/flags.js";
+export { isCopilotTransientModelError };
+/**
+ * Wrap an initial Copilot request so transient `model_not_supported` 400s are
+ * retried a small number of times. No-op for non-Copilot providers.
+ *
+ * The callback **MUST** create a fresh in-flight request each invocation — a
+ * once-consumed AsyncIterable cannot be re-iterated.
+ */
+export declare function callWithCopilotModelRetry<T>(fn: () => Promise<T>, options: {
+    provider: string;
+    signal?: AbortSignal;
+    retryBaseDelayMs?: number;
+}): Promise<T>;

package/dist/types/utils/schema/adapt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Set when callers want to globally bypass OpenAI strict-mode enforcement
+ * (e.g. for debugging a provider that misreports strict support, or when
+ * comparing strict vs non-strict outputs).
+ *
+ * Honored by every provider that emits `strict: true` on its function tools —
+ * see `openai-completions`, `openai-responses`, `openai-codex-responses`, and
+ * the strict candidate selection in `anthropic`.
+ */
+export declare const NO_STRICT: boolean;
+/**
+ * Consolidated helper for OpenAI-style strict schema enforcement.
+ *
+ * Each provider computes its own `strict` boolean (logic differs), then calls
+ * this to handle the tryEnforceStrictSchema dance uniformly:
+ * - Draft-07-shaped inputs are upgraded to draft 2020-12 first.
+ * - If `strict` is false, passes the upgraded schema through unchanged.
+ * - If `strict` is true, attempts to enforce strict mode; falls back to
+ *   non-strict if the schema isn't representable.
+ */
+export declare function adaptSchemaForStrict(schema: Record<string, unknown>, strict: boolean): {
+    schema: Record<string, unknown>;
+    strict: boolean;
+};