@prometheus-ai/ai 0.5.4 → 0.5.8

package/src/utils/openai-http.ts

@@ -0,0 +1,157 @@
+/**
+ * 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 { fetchWithRetry, readSseJson, type SseEventObserver } from "@prometheus-ai/utils";
+import { ProviderHttpError } from "../errors";
+import type { FetchImpl } from "../types";
+import type { CapturedHttpErrorResponse } from "./http-inspector";
+
+/**
+ * Total attempts when the caller has no first-event deadline armed. The
+ * removed SDK clients ran `maxRetries: 5`, i.e. 6 requests.
+ */
+const DEFAULT_MAX_ATTEMPTS = 6;
+
+/** Bound the `Error.message` allocation for proxy HTML error pages and the like. */
+const MAX_DETAIL_CHARS = 4096;
+
+/** Non-2xx response from an OpenAI-wire endpoint, with the decoded body attached. */
+export class OpenAIHttpError extends ProviderHttpError {
+	readonly captured: CapturedHttpErrorResponse;
+
+	constructor(message: string, captured: CapturedHttpErrorResponse, code: string | undefined) {
+		super(message, captured.status, { headers: captured.headers, code });
+		this.name = "OpenAIHttpError";
+		this.captured = captured;
+	}
+}
+
+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 async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): Promise<OpenAIStreamHandle<TEvent>> {
+	const response = await fetchWithRetry(init.url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json", Accept: "text/event-stream", ...init.headers },
+		body: JSON.stringify(init.body),
+		signal: init.signal,
+		fetch: init.fetch,
+		maxAttempts: init.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+		// Bun's native fetch enforces a hard ~300s pre-response timeout (issue #2422).
+		// Cold large-context streams legitimately exceed it; the caller's
+		// `firstEventTimeoutMs`/`AbortSignal` already govern stuck requests.
+		timeout: false,
+	});
+	if (!response.ok) {
+		throw await captureOpenAIHttpError(response);
+	}
+	if (!response.body) {
+		throw new Error(`OpenAI stream response has no body (status ${response.status})`);
+	}
+	return {
+		events: readSseJson<TEvent>(response.body, init.signal, init.onSseEvent),
+		response,
+		requestId: response.headers.get("x-request-id"),
+	};
+}
+
+/** Decode a non-2xx response into an {@link OpenAIHttpError} without consuming it twice. */
+export async function captureOpenAIHttpError(response: Response): Promise<OpenAIHttpError> {
+	let bodyText: string | undefined;
+	let bodyJson: unknown;
+	try {
+		bodyText = await response.text();
+		if (bodyText.trim().length > 0) {
+			try {
+				bodyJson = JSON.parse(bodyText);
+			} catch {}
+		} else {
+			bodyText = undefined;
+		}
+	} catch {}
+	const captured: CapturedHttpErrorResponse = {
+		status: response.status,
+		headers: response.headers,
+		bodyText,
+		bodyJson,
+	};
+	const { detail, code } = extractErrorDetail(bodyJson, bodyText);
+	// "status code (no body)" matches the SDK's former APIError phrasing;
+	// `finalizeErrorMessage` keys a repair path on that exact wording.
+	const message = detail
+		? `${response.status} ${detail.length > MAX_DETAIL_CHARS ? detail.slice(0, MAX_DETAIL_CHARS) : detail}`
+		: `${response.status} status code (no body)`;
+	return new OpenAIHttpError(message, captured, code);
+}
+
+/**
+ * Pull a human-readable message and machine code out of an OpenAI-style error
+ * envelope (`{ error: { message, code, type } }`), tolerating the flat shapes
+ * compat hosts return (`{ error: "..." }`, `{ message: "..." }`) and falling
+ * back to the raw body text.
+ */
+function extractErrorDetail(
+	bodyJson: unknown,
+	bodyText: string | undefined,
+): { detail: string | undefined; code: string | undefined } {
+	if (typeof bodyJson === "object" && bodyJson !== null) {
+		const envelope = bodyJson as { error?: unknown; message?: unknown };
+		const error = envelope.error;
+		if (typeof error === "object" && error !== null) {
+			const { message, code, type } = error as { message?: unknown; code?: unknown; type?: unknown };
+			return {
+				detail: typeof message === "string" && message.length > 0 ? message : bodyText,
+				code: typeof code === "string" ? code : typeof type === "string" ? type : undefined,
+			};
+		}
+		if (typeof error === "string" && error.length > 0) {
+			return { detail: error, code: undefined };
+		}
+		if (typeof envelope.message === "string" && envelope.message.length > 0) {
+			return { detail: envelope.message, code: undefined };
+		}
+	}
+	return { detail: bodyText, code: undefined };
+}

package/src/utils/request-debug.ts

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import type { FetchImpl } from "../types";
 
 const REQUEST_DEBUG_ENV = "PROMETHEUS_REQ_DEBUG";
@@ -8,6 +9,7 @@ const textEncoder = new TextEncoder();
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
 
 let nextSessionId = 1;
+let nextRequestDebugPath: string | undefined;
 
 type DebugFetch = FetchImpl & { [DEBUG_FETCH_MARKER]?: true };
 type RequestBodyInit = NonNullable<RequestInit["body"]>;
@@ -27,6 +29,14 @@ export interface RequestDebugPayload {
 	protocol?: string;
 }
 
+interface ReservedRequestDebugFile {
+	id: number;
+	requestPath: string;
+	responsePath: string;
+	handle: fs.FileHandle;
+	overwrite: boolean;
+}
+
 export interface RequestDebugResponseLog {
 	write(chunk: Uint8Array | string): void;
 	close(): Promise<void>;
@@ -40,10 +50,32 @@ export interface RequestDebugSession {
 	wrapResponse(response: Response): Promise<Response>;
 }
 
-export function isRequestDebugEnabled(): boolean {
+function isRequestDebugEnvEnabled(): boolean {
 	return Bun.env[REQUEST_DEBUG_ENV] === "1";
 }
 
+export function isRequestDebugEnabled(): boolean {
+	return isRequestDebugEnvEnabled() || nextRequestDebugPath !== undefined;
+}
+
+export function setNextRequestDebugPath(requestPath: string): void {
+	nextRequestDebugPath = requestPath;
+}
+
+export function clearNextRequestDebugPath(): void {
+	nextRequestDebugPath = undefined;
+}
+
+export function getNextRequestDebugPath(): string | undefined {
+	return nextRequestDebugPath;
+}
+
+function consumeNextRequestDebugPath(): string | undefined {
+	const requestPath = nextRequestDebugPath;
+	nextRequestDebugPath = undefined;
+	return requestPath;
+}
+
 export function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl {
 	if (!isRequestDebugEnabled()) return fetchImpl;
 	const maybeWrapped = fetchImpl as DebugFetch;
@@ -51,6 +83,7 @@ export function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl {
 
 	const wrapped = Object.assign(
 		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			if (!isRequestDebugEnabled()) return fetchImpl(input, init);
 			const session = await createFetchRequestDebugSession(input, init);
 			const response = await fetchImpl(input, init);
 			return session.wrapResponse(response);
@@ -69,7 +102,7 @@ export function withRequestDebugFetch<T extends { fetch?: FetchImpl } | undefine
 }
 
 export async function createRequestDebugSession(payload: RequestDebugPayload): Promise<RequestDebugSession> {
-	const { id, requestPath, responsePath, handle } = await reserveRequestDebugFile();
+	const { id, requestPath, responsePath, handle, overwrite } = await reserveRequestDebugFile();
 	const requestDump: Record<string, unknown> = {
 		id,
 		protocol: payload.protocol ?? "http",
@@ -89,7 +122,7 @@ export async function createRequestDebugSession(payload: RequestDebugPayload): P
 		await handle.close();
 	}
 
-	return new FileRequestDebugSession(id, requestPath, responsePath);
+	return new FileRequestDebugSession(id, requestPath, responsePath, overwrite);
 }
 
 async function createFetchRequestDebugSession(
@@ -110,15 +143,17 @@ class FileRequestDebugSession implements RequestDebugSession {
 	readonly id: number;
 	readonly requestPath: string;
 	readonly responsePath: string;
+	readonly #overwriteResponseLog: boolean;
 
-	constructor(id: number, requestPath: string, responsePath: string) {
+	constructor(id: number, requestPath: string, responsePath: string, overwriteResponseLog: boolean) {
 		this.id = id;
 		this.requestPath = requestPath;
 		this.responsePath = responsePath;
+		this.#overwriteResponseLog = overwriteResponseLog;
 	}
 
 	async openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog> {
-		const handle = await fs.open(this.responsePath, "wx");
+		const handle = await fs.open(this.responsePath, this.#overwriteResponseLog ? "w" : "wx");
 		const headerBlock = formatResponseHeaderBlock(statusLine, headers);
 		await handle.write(textEncoder.encode(headerBlock));
 		return new FileRequestDebugResponseLog(handle);
@@ -170,6 +205,7 @@ class FileRequestDebugSession implements RequestDebugSession {
 class FileRequestDebugResponseLog implements RequestDebugResponseLog {
 	#handle: fs.FileHandle | undefined;
 	#pending: Promise<void> = Promise.resolve();
+	#closed: Promise<void> | undefined;
 
 	constructor(handle: fs.FileHandle) {
 		this.#handle = handle;
@@ -184,15 +220,19 @@ class FileRequestDebugResponseLog implements RequestDebugResponseLog {
 		});
 	}
 
-	async close(): Promise<void> {
+	close(): Promise<void> {
+		if (this.#closed) return this.#closed;
 		const handle = this.#handle;
-		if (!handle) return;
+		if (!handle) return Promise.resolve();
 		this.#handle = undefined;
-		try {
-			await this.#pending;
-		} finally {
-			await handle.close();
-		}
+		this.#closed = (async () => {
+			try {
+				await this.#pending;
+			} finally {
+				await handle.close();
+			}
+		})();
+		return this.#closed;
 	}
 }
 
@@ -208,18 +248,26 @@ function copyResponseMetadata(target: Response, source: Response): void {
 	}
 }
 
-async function reserveRequestDebugFile(): Promise<{
-	id: number;
-	requestPath: string;
-	responsePath: string;
-	handle: fs.FileHandle;
-}> {
+async function reserveRequestDebugFile(): Promise<ReservedRequestDebugFile> {
+	const explicitPath = consumeNextRequestDebugPath();
+	if (explicitPath) {
+		await fs.mkdir(path.dirname(explicitPath), { recursive: true });
+		const handle = await fs.open(explicitPath, "w");
+		return {
+			id: nextSessionId++,
+			requestPath: explicitPath,
+			responsePath: `${explicitPath}.res.log`,
+			handle,
+			overwrite: true,
+		};
+	}
+
 	for (;;) {
 		const id = nextSessionId++;
 		const requestPath = `rr-session-${id}.json`;
 		try {
 			const handle = await fs.open(requestPath, "wx");
-			return { id, requestPath, responsePath: `rr-session-${id}.res.log`, handle };
+			return { id, requestPath, responsePath: `rr-session-${id}.res.log`, handle, overwrite: false };
 		} catch (error) {
 			if (isFileExistsError(error)) continue;
 			throw error;

package/src/utils/retry-after.ts

@@ -28,7 +28,7 @@ export function getRetryAfterMsFromHeaders(headers: HeadersLike): number | undef
 	return Math.max(...candidates);
 }
 
-function getHeadersFromError(error: unknown): HeadersLike {
+export function getHeadersFromError(error: unknown): HeadersLike {
 	if (!error || typeof error !== "object") return undefined;
 	const record = error as { headers?: unknown; response?: { headers?: unknown }; cause?: unknown };
 	const direct = extractHeaders(record.headers) ?? extractHeaders(record.response?.headers);

package/src/utils/retry.ts

@@ -1,5 +1,6 @@
 import { scheduler } from "node:timers/promises";
 import { extractHttpStatusFromError, isRetryableError } from "@prometheus-ai/utils";
+import { getHeadersFromError, getRetryAfterMsFromHeaders } from "./retry-after";
 
 /**
  * GitHub Copilot intermittently rejects preview models (gpt-5.3-codex,
@@ -24,6 +25,8 @@ export function isCopilotTransientModelError(error: unknown): boolean {
 
 const COPILOT_MODEL_RETRY_MAX_ATTEMPTS = 3;
 const COPILOT_MODEL_RETRY_BASE_DELAY_MS = 400;
+/** Longest server-requested backoff we are willing to sit out before giving up. */
+const COPILOT_RETRY_AFTER_MAX_WAIT_MS = 30_000;
 
 /**
  * Wrap an initial Copilot request so transient `model_not_supported` 400s are
@@ -45,9 +48,27 @@ export async function callWithCopilotModelRetry<T>(
 			return await fn();
 		} catch (error) {
 			lastError = error;
-			if (!isCopilotTransientModelError(error) && !isRetryableError(error)) throw error;
+			// A latched abort (caller cancel or local watchdog) makes any retry a
+			// guaranteed-dead attempt — surface the original error, not the
+			// scheduler's AbortError.
+			if (options.signal?.aborted) throw error;
+			const transientModelError = isCopilotTransientModelError(error);
+			if (!transientModelError && !isRetryableError(error)) throw error;
 			if (attempt === COPILOT_MODEL_RETRY_MAX_ATTEMPTS - 1) break;
-			await scheduler.wait(retryBaseDelayMs * (attempt + 1), { signal: options.signal });
+			let delayMs = retryBaseDelayMs * (attempt + 1);
+			if (!transientModelError) {
+				const status = extractHttpStatusFromError(error);
+				if (status !== undefined) {
+					// Status-bearing retryable errors (429/5xx) are only re-sent when
+					// the server told us when to come back — a blind fixed-delay retry
+					// of a rate limit just burns the remaining attempts. Status-less
+					// transport blips (socket close, h2 reset) keep the linear backoff.
+					const retryAfterMs = getRetryAfterMsFromHeaders(getHeadersFromError(error));
+					if (retryAfterMs === undefined || retryAfterMs > COPILOT_RETRY_AFTER_MAX_WAIT_MS) throw error;
+					delayMs = Math.max(delayMs, retryAfterMs);
+				}
+			}
+			await scheduler.wait(delayMs, { signal: options.signal });
 		}
 	}
 	throw lastError;

package/src/utils/schema/CONSTRAINTS.md

@@ -37,8 +37,10 @@ When strict mode is requested (`strict=true` at call site), the schema MUST sati
 3. **Object and tuple strictness is enforced recursively**
    - Every object node gets `additionalProperties: false`.
    - Every property key is included in `required`.
-   - Optional properties are wrapped as nullable unions:
-     - `anyOf: [<original schema>, { "type": "null" }]`.
+   - Optional properties are made nullable:
+     - Pure union nodes (only `anyOf` plus optional `description`) get a `{ "type": "null" }` branch appended in place — never a nested wrapper.
+     - All other nodes are wrapped as `anyOf: [<original schema>, { "type": "null" }]`. Nodes with constraining siblings next to `anyOf` MUST keep the wrapper: sibling keywords are conjunctive with `anyOf`, so appending a null branch would not make the node nullable.
+   - Nested pure unions are spliced into the parent `anyOf` (`(A ∨ B) ∨ C` → `A ∨ B ∨ C`); an inner `description` is hoisted to the parent when the parent has none. Strict output MUST NOT contain an `anyOf` branch that is itself a pure union — some upstream validators (OpenRouter DeepSeek) reject branches without `type`.
    - Tuple entries in `prefixItems` are strictified recursively.
 
 4. **Schema nodes must be representable in strict mode**

package/src/utils/schema/fields.ts

@@ -154,6 +154,22 @@ export const CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS: Record<string, Record<string,
 	null: {},
 };
 
+/**
+ * Flat set of every type-specific key across all CCA types.
+ * Used to identify sibling keys that need filtering during mixed-type collapse.
+ */
+export const ALL_CCA_TYPE_SPECIFIC_KEYS: Record<string, true> = buildAllCcaTypeSpecificKeys();
+
+function buildAllCcaTypeSpecificKeys(): Record<string, true> {
+	const all: Record<string, true> = {};
+	for (const typeKeys of Object.values(CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS)) {
+		for (const key in typeKeys) {
+			all[key] = true;
+		}
+	}
+	return all;
+}
+
 /**
  * Cloud Code Assist shared schema keys allowed on any type.
  * Used alongside CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS for CCA combiner collapsing.

package/src/utils/schema/json-schema-validator.ts

@@ -20,6 +20,14 @@ export interface JsonSchemaValidationIssue {
 	message: string;
 	expectedTypes?: string[];
 	keyword?: string;
+	/**
+	 * Marks issues that originate inside a failed `anyOf` / `oneOf` branch.
+	 * Consumers such as the tool-argument coercion layer use this to avoid
+	 * applying type repairs (e.g. singleton-array wrapping) that would be
+	 * authoritative outside of a combinator but are only one candidate
+	 * branch's expectation here.
+	 */
+	fromUnionBranch?: boolean;
 }
 
 export interface JsonSchemaValidationResult {
@@ -242,7 +250,17 @@ function validateSchemaNode(
 		const branchValid = keyword === "anyOf" ? matches > 0 : matches === 1;
 		if (!branchValid) {
 			if (matches === 0 && firstIssues && firstIssues.length > 0) {
-				issues.push(...firstIssues);
+				// Only tag issues that sit at the combinator's own path as
+				// union-branch; deeper issues describe a specific field within
+				// the failed branch and should remain individually repairable.
+				const unionDepth = path.length;
+				for (const branchIssue of firstIssues) {
+					if (branchIssue.path.length === unionDepth) {
+						issues.push({ ...branchIssue, fromUnionBranch: true });
+					} else {
+						issues.push(branchIssue);
+					}
+				}
 			} else {
 				pushIssue(
 					issues,

package/src/utils/schema/normalize.ts

@@ -11,6 +11,7 @@ import { dereferenceJsonSchema } from "./dereference";
 import { upgradeJsonSchemaTo202012 } from "./draft";
 import { areJsonValuesEqual, mergePropertySchemas } from "./equality";
 import {
+	ALL_CCA_TYPE_SPECIFIC_KEYS,
 	CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS,
 	CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS,
 	COMBINATOR_KEYS,
@@ -51,7 +52,6 @@ export interface NormalizeSchemaOptions {
 
 interface NormalizeSchemaWalkOptions extends NormalizeSchemaOptions {
 	insideProperties: boolean;
-	epoch: number;
 }
 
 interface ResidualIncompatibilityChecks {
@@ -218,13 +218,27 @@ function applyDescriptionSpill(
 
 function normalizeSchemaNode(value: unknown, options: NormalizeSchemaWalkOptions): unknown {
 	if (Array.isArray(value)) {
-		if (!once(value, options.epoch)) return [];
-		return value.map(entry => normalizeSchemaNode(entry, options));
+		if (!enter(value)) return [];
+		try {
+			return value.map(entry => normalizeSchemaNode(entry, options));
+		} finally {
+			exit(value);
+		}
 	}
 	if (!isJsonObject(value)) {
 		return value;
 	}
-	if (!once(value, options.epoch)) return {};
+	// `enter`/`exit` path-tracking (not a visited-set): DAG-shared subtrees are
+	// normalized at every occurrence; only true cycles short-circuit to `{}`.
+	if (!enter(value)) return {};
+	try {
+		return normalizeSchemaObjectNode(value, options);
+	} finally {
+		exit(value);
+	}
+}
+
+function normalizeSchemaObjectNode(value: JsonObject, options: NormalizeSchemaWalkOptions): unknown {
 	let obj = options.normalizeFieldNames && !options.insideProperties ? applySnakeCaseRenames(value) : value;
 	if (options.collapseNullFields && !options.insideProperties) {
 		obj = preHandleNullFields(obj);
@@ -501,12 +515,32 @@ function collapseMixedTypeCombinerVariants(schema: JsonObject, combiner: "anyOf"
 	if (variantTypes.length < 2 || variantTypes.every(type => type === "object")) {
 		return schema;
 	}
-
 	const nextSchema = copySchemaWithout(schema, combiner);
 	const nonNullTypes = variantTypes.filter(t => t !== "null");
-	nextSchema.type = nonNullTypes[0] ?? variantTypes[0];
+	const chosenType: string = nonNullTypes[0] ?? variantTypes[0];
+	nextSchema.type = chosenType;
+	const chosenTypeAllowedKeys = CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS[chosenType] ?? {};
+
+	// Strip sibling keys that were copied from the parent and belong to a
+	// different type (e.g. `items` sibling on a now-string-typed schema).
+	for (const key in nextSchema) {
+		if (!Object.hasOwn(nextSchema, key)) continue;
+		if (key === "type") continue;
+		if (
+			Object.hasOwn(ALL_CCA_TYPE_SPECIFIC_KEYS, key) &&
+			!Object.hasOwn(chosenTypeAllowedKeys, key) &&
+			!Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)
+		) {
+			delete nextSchema[key];
+		}
+	}
+
 	for (const key in mergedVariantFields) {
 		if (!Object.hasOwn(mergedVariantFields, key)) continue;
+		// Drop type-specific keys that don't belong to the chosen type
+		if (!Object.hasOwn(chosenTypeAllowedKeys, key) && !Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)) {
+			continue;
+		}
 		const value = mergedVariantFields[key];
 		const existingValue = nextSchema[key];
 		if (existingValue !== undefined && !areJsonValuesEqual(existingValue, value)) {
@@ -774,7 +808,6 @@ export function normalizeSchema(value: unknown, options: NormalizeSchemaOptions)
 	let normalized = normalizeSchemaNode(dereferenced, {
 		...options,
 		insideProperties: false,
-		epoch: epochNext(),
 	});
 	if (options.stripResidualCombinersFixpoint) {
 		normalized = stripResidualCombiners(normalized);
@@ -1069,7 +1102,7 @@ function inferStrictPrimitiveTypeFromEnumOrConst(node: Record<string, unknown>):
  * so repeated calls (different providers, retries, batching) reuse the same
  * computed pair without re-walking the tree.
  */
-const kStrictSchema = Symbol("pi.schema.strict");
+const kStrictSchema = Symbol("prometheus.schema.strict");
 
 /**
  * Detect schemas that strict mode *cannot* represent.
@@ -1404,6 +1437,21 @@ export function sanitizeSchemaForStrictMode(
 	return sanitized;
 }
 
+/**
+ * A node whose only constraining keyword is `anyOf` (annotations like
+ * `description` aside). Only such nodes can be merged into an enclosing
+ * union without changing semantics: sibling keywords (`type`, `enum`,
+ * `properties`, …) apply conjunctively with `anyOf`, so spreading the
+ * branches of a non-pure node would drop those constraints.
+ */
+function isPureAnyOfNode(value: unknown): value is Record<string, unknown> & { anyOf: unknown[] } {
+	if (!isJsonObject(value) || !Array.isArray(value.anyOf)) return false;
+	for (const key in value) {
+		if (key !== "anyOf" && key !== "description") return false;
+	}
+	return true;
+}
+
 /**
  * Recursively enforces JSON Schema constraints required by OpenAI/Codex strict mode:
  *   - `additionalProperties: false` on every object node
@@ -1472,6 +1520,10 @@ function enforceStrictSchemaBody(
 					strictProperties[key] = processed;
 					continue;
 				}
+				if (isPureAnyOfNode(processed)) {
+					strictProperties[key] = { ...processed, anyOf: [...processed.anyOf, { type: "null" }] };
+					continue;
+				}
 				if (isJsonObject(processed) && typeof processed.description === "string") {
 					const { description, ...withoutDescription } = processed;
 					strictProperties[key] = { anyOf: [withoutDescription, { type: "null" }], description };
@@ -1512,6 +1564,26 @@ function enforceStrictSchemaBody(
 			);
 		}
 	}
+	// Splice nested pure unions into the parent `anyOf`: `(A ∨ B) ∨ C` ≡ `A ∨ B ∨ C`.
+	// Some strict-mode validators (e.g. DeepSeek behind OpenRouter) reject anyOf
+	// branches that carry no `type`, which is exactly what a nested combinator
+	// node looks like (#2270). Branch recursion above already flattened deeper
+	// levels bottom-up, so a single pass suffices.
+	if (Array.isArray(result.anyOf) && result.anyOf.some(isPureAnyOfNode)) {
+		const flattened: unknown[] = [];
+		for (const branch of result.anyOf) {
+			if (!isPureAnyOfNode(branch)) {
+				flattened.push(branch);
+				continue;
+			}
+			flattened.push(...branch.anyOf);
+			// Keep the inner annotation when the parent has none.
+			if (typeof branch.description === "string" && result.description === undefined) {
+				result.description = branch.description;
+			}
+		}
+		result.anyOf = flattened;
+	}
 	for (const defsKey of ["$defs", "definitions"] as const) {
 		if (result[defsKey] != null && typeof result[defsKey] === "object" && !Array.isArray(result[defsKey])) {
 			const defs = result[defsKey] as Record<string, unknown>;

package/src/utils/schema/stamps.ts

@@ -9,11 +9,13 @@
  *
  * Caveats: the stamp lives as long as the host object, even after callers
  * release their references to the cached value — only use this for caches
- * whose lifetime should match the host. Frozen hosts will throw on write in
- * strict mode; callers that may receive frozen input must handle that.
+ * whose lifetime should match the host. Frozen hosts cannot be stamped;
+ * `define` silently skips them, so memoization/visit-tracking degrades to
+ * best-effort (recompute on every call, no cycle protection) instead of
+ * throwing.
  */
-
 function define<T extends object>(target: T, key: symbol, value: unknown): void {
+	if (Object.isFrozen(target)) return;
 	Object.defineProperty(target, key, { value, writable: true, configurable: true });
 }
 
@@ -38,7 +40,7 @@ export function stamp<T extends object, V>(target: T, key: symbol, compute: (tar
  *     for (const child of node.children) walk(child, epoch);
  *   }
  */
-const kEpoch = Symbol("pi.schema.epoch");
+const kEpoch = Symbol("prometheus.schema.epoch");
 let __epoch = 0;
 
 export function epochNext(): number {
@@ -77,9 +79,15 @@ export function once<T extends object>(target: T, epoch: number): boolean {
  *     finally { exit(node); }
  *   }
  */
-const kDepth = Symbol("pi.schema.depth");
+const kDepth = Symbol("prometheus.schema.depth");
 
-/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+/**
+ * Returns `true` on first entry, `false` if `target` is already on the
+ * current path. A `false` return does NOT deepen the counter — callers pair
+ * `exit` only with successful enters (`if (!enter(n)) bail; try {…} finally
+ * { exit(n); }`), so incrementing on the cycle branch would leak depth and
+ * make every later top-level walk of the same object misreport a cycle.
+ */
 export function enter<T extends object>(target: T): boolean {
 	const slot = target as Record<symbol, number | undefined>;
 	const cur = slot[kDepth];
@@ -87,11 +95,15 @@ export function enter<T extends object>(target: T): boolean {
 		define(target, kDepth, 1);
 		return true;
 	}
-	slot[kDepth] = cur + 1;
-	return cur === 0;
+	if (cur !== 0) return false;
+	slot[kDepth] = 1;
+	return true;
 }
 
 export function exit<T extends object>(target: T): void {
-	const slot = target as Record<symbol, number>;
-	slot[kDepth]--;
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kDepth];
+	// Frozen targets never received the kDepth stamp in `enter` — nothing to unwind.
+	if (cur === undefined) return;
+	slot[kDepth] = cur - 1;
 }