jeopi-ai 16.2.13

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,118 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model, ToolCall } from "../types";
+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,30 @@
+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;
+};
+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 routing rollout gap for our OAuth client.
+ *        A preview model (gpt-5.3-codex, gpt-5.4*, ...) flaps between 200 and
+ *        400 because only some of Copilot's backends have the model. 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,137 @@
+/**
+ * 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 local OpenAI-compatible
+ * servers are not undercut by a shorter `PI_STREAM_FIRST_EVENT_TIMEOUT_MS`
+ * or the global default during prompt processing.
+ *
+ * Returns `undefined` when an explicit env knob disables the watchdog.
+ */
+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 `fetchWithRetry` resolves (headers in) so
+ * the body stream is left to the iterator-level idle watchdog. The timer aborts
+ * with a `TimeoutError` matching `AbortSignal.timeout`, so a genuine pre-response
+ * stall behaves exactly as the prior code did — `fetchWithRetry` normalizes the
+ * abort to "Request was aborted" either way (only a post-headers abort ever
+ * surfaced the raw `"The operation timed out."`, which clearing now prevents).
+ *
+ * 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;
+    /**
+     * 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,29 @@
+/**
+ * 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 any
+ * provider stream into a fresh {@link AssistantMessageEventStream}, splitting the
+ * leaked fences out into proper `thinking` blocks *live* as deltas arrive — so
+ * every provider gets the same healing, not just the three with provider-local
+ * {@link StreamMarkupHealing} loops.
+ *
+ * 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";
+/**
+ * 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,54 @@
+/**
+ * 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 "jeopi-utils";
+import * as AIError from "../error";
+import { OpenAIHttpError } from "../error";
+export { OpenAIHttpError };
+import type { FetchImpl } from "../types";
+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;
+    /**
+     * Total attempts (initial + retries). Defaults to {@link DEFAULT_MAX_ATTEMPTS}.
+     * Pass `1` when a first-event watchdog is armed so retries cannot silently
+     * extend the caller's deadline (mirrors the old `maxRetries: 0` hint).
+     */
+    maxAttempts?: number;
+    /** 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";
+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,29 @@
+import * as tls from "node:tls";
+import type { FetchImpl } from "../types";
+/**
+ * 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;
+/**
+ * Wraps a fetch implementation to inject proxy options for non-local hosts.
+ */
+export declare function wrapFetchForProxy(fetchImpl: FetchImpl, provider: string): FetchImpl;
+/**
+ * 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): Promise<tls.TLSSocket>;

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

@@ -0,0 +1,29 @@
+import type { FetchImpl } from "../types";
+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";
+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;
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Schema compatibility audits.
+ *
+ * Each provider has a different idea of what JSON Schema features it accepts
+ * for tool definitions. The normalizers in `normalize.ts`, `strict-mode`,
+ * and `adapt.ts` rewrite incoming schemas to fit. This module is the
+ * *audit* counterpart: it walks a (presumably already-sanitized) schema and
+ * reports any feature the target provider would reject. Tests use it to lock
+ * down the contract; the runtime uses it to fail-open with diagnostic logs
+ * rather than silently shipping a broken tool definition.
+ */
+export type SchemaCompatibilityProvider = "openai-strict" | "google" | "cloud-code-assist-claude";
+export interface SchemaCompatibilityViolation {
+    path: string;
+    rule: string;
+    message: string;
+    key?: string;
+    value?: unknown;
+}
+export interface SchemaCompatibilityResult {
+    provider: SchemaCompatibilityProvider;
+    compatible: boolean;
+    violations: SchemaCompatibilityViolation[];
+}
+export interface StrictSchemaEnforcementResult {
+    schema: Record<string, unknown>;
+    strict: boolean;
+}
+export declare function validateSchemaCompatibility(schema: unknown, provider: SchemaCompatibilityProvider): SchemaCompatibilityResult;
+export declare function validateStrictSchemaEnforcement(originalSchema: Record<string, unknown>, result: StrictSchemaEnforcementResult): SchemaCompatibilityResult;

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

@@ -0,0 +1,11 @@
+/**
+ * Dereference all local `$ref` pointers in a JSON Schema, inlining definitions
+ * from `$defs` / `definitions`. The `$defs` block is stripped from the output.
+ *
+ * Non-local refs (e.g. `http://...`) are left untouched.
+ * Circular references are broken with `{}`.
+ *
+ * @returns A new schema object with all local refs inlined, or the input unchanged
+ *          if it's not an object or has no `$defs`/`definitions`.
+ */
+export declare function dereferenceJsonSchema(schema: unknown): unknown;

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

@@ -0,0 +1,10 @@
+export declare const JSON_SCHEMA_DRAFT_2020_12_URI = "https://json-schema.org/draft/2020-12/schema";
+/** Pre-check entrypoint. Exposed so callers can decide whether to take the upgrade path at all. */
+export declare function schemaNeedsDraft202012Upgrade(schema: unknown): boolean;
+/**
+ * Upgrade legacy JSON Schema shapes to the draft 2020-12 form emitted by Zod.
+ *
+ * This keeps extension/MCP/TypeBox schemas compatible with providers whose tool
+ * validators reject draft-07 tuple and dependency keywords.
+ */
+export declare function upgradeJsonSchemaTo202012(schema: unknown): unknown;

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

@@ -0,0 +1,4 @@
+import type { JsonObject } from "./types";
+export declare function areJsonValuesEqual(left: unknown, right: unknown): boolean;
+export declare function mergeCompatibleEnumSchemas(existing: unknown, incoming: unknown): JsonObject | null;
+export declare function mergePropertySchemas(existing: unknown, incoming: unknown): unknown;

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

@@ -0,0 +1,54 @@
+/**
+ * Field classification sets for JSON Schema sanitization across providers.
+ *
+ * Each set serves a different provider need. They overlap intentionally —
+ * co-locating them makes the overlap visible and maintainable.
+ *
+ * All keysets here are static and small (≤ ~40 entries) so they live as
+ * `Record<string, true>` literals — `k in REC` resolves through hidden
+ * class inline caches without the per-call hashtable cost of `Set.has`.
+ */
+/**
+ * Google Generative AI unsupported schema fields.
+ * Stripped during normalizeSchemaForGoogle / normalizeSchemaForCCA.
+ */
+export declare const UNSUPPORTED_SCHEMA_FIELDS: Record<string, true>;
+/**
+ * Human-meaningful validation/decorative keywords that can be preserved in a
+ * sibling description when a provider-specific normalizer strips them from the
+ * wire schema.
+ */
+export declare const LIFTABLE_TO_DESCRIPTION_FIELDS: Record<string, true>;
+/**
+ * Non-structural schema keys stripped during OpenAI strict mode sanitization.
+ * These are decorative/validation-only keywords that don't affect the structural
+ * shape OpenAI's strict mode enforces.
+ */
+export declare const NON_STRUCTURAL_SCHEMA_KEYS: Record<string, true>;
+/**
+ * Cloud Code Assist type-specific allowed keys per JSON Schema type.
+ * Used when collapsing mixed-type combiner variants for CCA Claude.
+ */
+export declare const CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS: Record<string, Record<string, true>>;
+/**
+ * Flat set of every type-specific key across all CCA types.
+ * Used to identify sibling keys that need filtering during mixed-type collapse.
+ */
+export declare const ALL_CCA_TYPE_SPECIFIC_KEYS: Record<string, true>;
+/**
+ * Cloud Code Assist shared schema keys allowed on any type.
+ * Used alongside CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS for CCA combiner collapsing.
+ */
+export declare const CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS: Record<string, true>;
+/**
+ * Combinator keys used across schema sanitization modules.
+ * Defined once to avoid duplication in strict-mode.ts and normalize.ts.
+ */
+export declare const COMBINATOR_KEYS: readonly ["anyOf", "allOf", "oneOf"];
+/**
+ * Cloud Code Assist Claude unsupported schema fields.
+ * Much smaller than UNSUPPORTED_SCHEMA_FIELDS (Google) because CCA supports
+ * validation keywords like additionalProperties, minLength, pattern, etc.
+ * Meta/reference keywords plus object-key validators that CCA cannot resolve are stripped.
+ */
+export declare const CCA_UNSUPPORTED_SCHEMA_FIELDS: Record<string, true>;

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

@@ -0,0 +1,15 @@
+export * from "./adapt";
+export * from "./compatibility";
+export * from "./dereference";
+export * from "./draft";
+export * from "./equality";
+export * from "./fields";
+export * from "./json-schema-validator";
+export * from "./meta-validator";
+export * from "./normalize";
+export * from "./spill";
+export * from "./strict-tool-validation";
+export * from "./types";
+export * from "./typescript";
+export * from "./wire";
+export * from "./zod-decontaminate";