@prometheus-ai/ai 0.5.0

package/src/utils/retry-after.ts

@@ -0,0 +1,110 @@
+export type HeadersLike = Headers | Record<string, string | undefined> | undefined | null;
+
+const RETRY_AFTER_HINT = "retry-after-ms=";
+
+export function formatErrorMessageWithRetryAfter(error: unknown, headers?: HeadersLike): string {
+	const message = error instanceof Error ? error.message : JSON.stringify(error);
+	if (message.includes(RETRY_AFTER_HINT)) {
+		return message;
+	}
+
+	const retryAfterMs = getRetryAfterMsFromHeaders(headers ?? getHeadersFromError(error));
+	if (retryAfterMs === undefined) {
+		return message;
+	}
+
+	return `${message} ${RETRY_AFTER_HINT}${retryAfterMs}`;
+}
+
+export function getRetryAfterMsFromHeaders(headers: HeadersLike): number | undefined {
+	if (!headers) return undefined;
+
+	const retryAfter = parseRetryAfterHeader(getHeaderValue(headers, "retry-after"));
+	const resetMs = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset-ms"), "ms");
+	const resetSeconds = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset"), "s");
+
+	const candidates = [retryAfter, resetMs, resetSeconds].filter((value): value is number => value !== undefined);
+	if (candidates.length === 0) return undefined;
+	return Math.max(...candidates);
+}
+
+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);
+	if (direct) return direct;
+	if (record.cause) return getHeadersFromError(record.cause);
+	return undefined;
+}
+
+function extractHeaders(value: unknown): HeadersLike {
+	if (!value) return undefined;
+	if (value instanceof Headers) return value;
+	if (typeof value === "object") return value as Record<string, string | undefined>;
+	return undefined;
+}
+
+function getHeaderValue(headers: Headers | Record<string, string | undefined>, name: string): string | undefined {
+	if (headers instanceof Headers) {
+		const value = headers.get(name);
+		return value ?? undefined;
+	}
+
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === target && typeof value === "string") {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+function parseRetryAfterHeader(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+
+	const numeric = Number(trimmed);
+	if (Number.isFinite(numeric)) {
+		if (numeric <= 0) return undefined;
+		return Math.ceil(numeric * 1000);
+	}
+
+	const dateMs = Date.parse(trimmed);
+	if (!Number.isNaN(dateMs)) {
+		const delay = dateMs - Date.now();
+		return delay > 0 ? Math.ceil(delay) : undefined;
+	}
+
+	return undefined;
+}
+
+function parseResetHeader(value: string | undefined, unit: "ms" | "s"): number | undefined {
+	if (!value) return undefined;
+	const numeric = Number(value);
+	if (!Number.isFinite(numeric) || numeric <= 0) return undefined;
+
+	const nowMs = Date.now();
+	let targetMs: number | undefined;
+
+	if (unit === "ms") {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric);
+		}
+	} else {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric * 1000);
+		}
+	}
+
+	if (targetMs <= nowMs) return undefined;
+	return Math.ceil(targetMs - nowMs);
+}

package/src/utils/retry.ts

@@ -0,0 +1,54 @@
+import { scheduler } from "node:timers/promises";
+import { extractHttpStatusFromError, isRetryableError } from "@prometheus-ai/utils";
+
+/**
+ * GitHub Copilot intermittently rejects preview models (gpt-5.3-codex,
+ * gpt-5.4, gpt-5.4-mini, ...) with HTTP 400 `model_not_supported`, even
+ * though the model is listed as enabled on the user's account via `/models`.
+ *
+ * Root cause: Copilot's request-routing backend is rolled out per OAuth
+ * client. Our OAuth client id is shared with opencode; VS Code uses its own
+ * client and sees full availability, so the same account may succeed in VS
+ * Code and flap between 200/400 here. See opencode#13313 and copilot-cli#2597.
+ *
+ * Retrying the identical request 2-3 times almost always lands on a backend
+ * that has the model, so we wrap the initial request with a short retry loop.
+ */
+export function isCopilotTransientModelError(error: unknown): boolean {
+	if (extractHttpStatusFromError(error) !== 400) return false;
+	if (!error || typeof error !== "object") return false;
+	const info = error as { code?: unknown; error?: { code?: unknown } | null };
+	const code = typeof info.code === "string" ? info.code : info.error?.code;
+	return code === "model_not_supported";
+}
+
+const COPILOT_MODEL_RETRY_MAX_ATTEMPTS = 3;
+const COPILOT_MODEL_RETRY_BASE_DELAY_MS = 400;
+
+/**
+ * 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 async function callWithCopilotModelRetry<T>(
+	fn: () => Promise<T>,
+	options: { provider: string; signal?: AbortSignal; retryBaseDelayMs?: number },
+): Promise<T> {
+	if (options.provider !== "github-copilot") return fn();
+
+	let lastError: unknown;
+	const retryBaseDelayMs = options.retryBaseDelayMs ?? COPILOT_MODEL_RETRY_BASE_DELAY_MS;
+	for (let attempt = 0; attempt < COPILOT_MODEL_RETRY_MAX_ATTEMPTS; attempt++) {
+		try {
+			return await fn();
+		} catch (error) {
+			lastError = error;
+			if (!isCopilotTransientModelError(error) && !isRetryableError(error)) throw error;
+			if (attempt === COPILOT_MODEL_RETRY_MAX_ATTEMPTS - 1) break;
+			await scheduler.wait(retryBaseDelayMs * (attempt + 1), { signal: options.signal });
+		}
+	}
+	throw lastError;
+}

package/src/utils/schema/CONSTRAINTS.md

@@ -0,0 +1,164 @@
+# Schema Constraints
+
+This document is the operational contract for schema normalization/strictness in `packages/ai/src/utils/schema`.
+
+## Scope
+
+- Applies to provider-facing tool schemas produced by:
+  - `normalize.ts` — Google, CCA, MCP, OpenAI Responses, and OpenAI strict-mode (sanitize + enforce) sanitization. All schema walkers live here.
+  - `adapt.ts` — thin composer wrapping `tryEnforceStrictSchema` for provider call sites, plus the `PROMETHEUS_NO_STRICT` env flag callers consult to opt out of strict mode.
+  - `fields.ts` — keyword classification sets used by the walkers.
+- Covers OpenAI-style strict mode, OpenAI Responses `oneOf` rejection, Google schema constraints, and Cloud Code Assist Claude constraints.
+---
+
+## 1) OpenAI-style strict mode (`adaptSchemaForStrict` / `tryEnforceStrictSchema`)
+
+When strict mode is requested (`strict=true` at call site), the schema MUST satisfy all of the following after adaptation:
+
+1. **Non-structural keywords are removed before strict enforcement**
+   - Sanitization uses `sanitizeSchemaForStrictMode`.
+   - Removed keys include formatting/validation/decorative keywords and unsupported structural extras:
+     - `format`, `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
+     - `minItems`, `maxItems`, `uniqueItems`, `multipleOf`
+     - `$schema`, `examples`, `default`, `title`, `$comment`
+     - `if`, `then`, `else`, `not`
+     - `unevaluatedProperties`, `unevaluatedItems`, `patternProperties`
+     - `propertyNames`, `contains`, `minContains`, `maxContains`
+     - `dependentRequired`, `dependentSchemas`
+     - `contentEncoding`, `contentMediaType`, `contentSchema`
+     - `deprecated`, `readOnly`, `writeOnly`
+     - `minProperties`, `maxProperties`
+     - `$dynamicRef`, `$dynamicAnchor`
+   - Before stripping `default`, its value is inlined into the sibling `description` as ` (default: X)` so that strict-mode providers retain the default hint in free-form text. Inlining is skipped when `description` already contains `(default:` or when no sibling `description` is present.
+
+2. **`const` is normalized to `enum`**
+   - If a node contains `const`, strict sanitization converts it to `enum: [const]`.
+
+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" }]`.
+   - Tuple entries in `prefixItems` are strictified recursively.
+
+4. **Schema nodes must be representable in strict mode**
+   - Nodes without `type`, combinator, `$ref`, or `not` are invalid in strict enforcement and MUST throw.
+   - Example invalid node: `{}` or `{ items: {} }`.
+
+5. **Failure mode is fail-open to non-strict**
+   - `tryEnforceStrictSchema` MUST return `{ strict: false, schema: original }` when strict enforcement throws.
+   - It MUST NOT emit partially-broken strict schema.
+
+6. **Provider payload strict flag must match effective strictness**
+   - Callers MUST send `strict: true` only if enforcement succeeded (`effectiveStrict === true`).
+
+---
+
+## 2) Google Gemini / Vertex / Gemini CLI (`normalizeSchemaForGoogle`)
+
+Schemas sent on the Google JSON Schema path MUST follow:
+
+1. **Unsupported JSON Schema keywords are stripped (except property names under `properties`)**
+   - Unsupported keys (`UNSUPPORTED_SCHEMA_FIELDS`):
+     - `$schema`, `$ref`, `$defs`, `$dynamicRef`, `$dynamicAnchor`
+     - `examples`, `prefixItems`, `unevaluatedProperties`, `unevaluatedItems`
+     - `patternProperties`, `additionalProperties`
+     - `minItems`, `maxItems`, `minLength`, `maxLength`
+     - `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
+     - `pattern`, `format`
+   - Important: keys inside a `properties` object are treated as property names and MUST NOT be stripped by keyword match.
+   - Human-meaningful stripped keys (`pattern`, `format`, min/max constraints, `default`, `examples`, etc.) are appended to the sibling `description` as an Anthropic-style spill block: `{pattern: "^foo$", minimum: 0}`. Structural/meta keys such as `$ref`, `$defs`, and `additionalProperties` are not spilled.
+
+2. **`type` arrays are normalized to scalar type + nullable marker**
+   - `type: ["T", "null"]` becomes `type: "T"` and `nullable: true`.
+   - Google expects scalar type, not `type[]`.
+
+3. **`const` is converted to `enum`**
+   - If `const` exists, schema uses/merges `enum` with the const value.
+
+4. **Object schemas get an explicit properties map**
+   - `{ "type": "object" }` becomes `{ "type": "object", "properties": {} }`.
+---
+
+## 3) Claude via Cloud Code Assist (`normalizeSchemaForCCA`)
+
+For Cloud Code Assist Claude tool declarations, schema MUST satisfy stricter constraints than generic Google path.
+
+### 3.1 Transport contract
+
+1. **Use legacy `parameters` field** (not `parametersJsonSchema`) for CCA Claude.
+2. CCA path uses the full `normalizeSchemaForCCA` pipeline.
+
+### 3.2 Sanitization contract
+
+1. Start with Google unsupported-key stripping behavior.
+2. **`nullable` keyword MUST be stripped** in CCA Claude path.
+3. `type: ["T", "null"]` becomes `type: "T"` with no `nullable` marker.
+4. Human-meaningful stripped keys are appended to `description` with the same spill format used by the Google dispatcher.
+
+### 3.3 Combiner/union normalization contract
+
+1. Object-only `anyOf`/`oneOf` variants SHOULD be merged into a single object shape where safe.
+2. Same-type combiner variants SHOULD be collapsed to one schema.
+3. Mixed-type combiner variants MAY be lossy-collapsed to first non-null scalar type when required for CCA acceptance.
+4. Residual combiners are recursively stripped where collapsible (`stripResidualCombiners`).
+
+### 3.4 Nullable property normalization contract
+
+1. Property-local nullability expressed as:
+   - `nullable: true`, or
+   - `type` union including `null`, or
+   - `anyOf`/`oneOf` with one `{ "type": "null" }` branch
+     MUST be converted to non-required property semantics where possible.
+2. If a property is detected nullable after normalization, it MUST be removed from `required`.
+
+### 3.5 Residual incompatibility gate (hard stop)
+
+After normalization, schema MUST NOT contain any of:
+
+- `type` as array
+- `type: "null"`
+- `nullable` key
+- `anyOf`, `oneOf`, `allOf` arrays
+
+If any remain, schema is incompatible.
+
+### 3.6 Validation + fallback contract
+
+1. Normalized schema is validated with AJV 2020 schema validation.
+2. If invalid OR residual incompatibilities exist, output MUST fallback to:
+
+```json
+{ "type": "object", "properties": {} }
+```
+
+3. Fallback is per-tool and fail-open; one bad tool schema MUST NOT fail the whole request.
+
+---
+
+## 4) Practical provider mapping
+
+- **OpenAI-compatible strict paths** (`openai-completions`, `openai-responses`, `openai-codex-responses`):
+  - Use `adaptSchemaForStrict`.
+  - Emit `strict: true` only when effective strict enforcement succeeded.
+
+- **Google Gemini/Vertex/Gemini CLI (non-CCA Claude)**:
+  - Use `normalizeSchemaForGoogle` and send schema on `parametersJsonSchema` path.
+
+- **Cloud Code Assist Claude models (`model.id` starts with `claude-`)**:
+  - Use `normalizeSchemaForCCA` and send sanitized normalized schema in `parameters`.
+
+---
+
+## 5) Maintenance rules
+
+When adding/changing provider adapters:
+
+1. Any new unsupported keyword MUST be added to the appropriate set in `fields.ts`.
+2. Any new normalization rule MUST include regression tests under `packages/ai/test`.
+3. Never bypass adapter helpers (`adaptSchemaForStrict`, `normalizeSchemaForGoogle`, `normalizeSchemaForCCA`, `normalizeSchemaForMCP`) in provider code.
+4. If a provider rejects schema with partial support, prefer deterministic per-tool fallback over request-wide failure.
+
+## 6) Gemini CLI / Antigravity CCA parity
+
+The Gemini CLI / Antigravity Claude path MUST run the same full `normalizeSchemaForCCA` pipeline as the shared Google Claude path. It MUST NOT call only the first keyword-stripping pass, because that leaves object combiners, nullable unions, residual combiners, and fallback gating inconsistent between transports.

package/src/utils/schema/adapt.ts

@@ -0,0 +1,36 @@
+import { $flag } from "@prometheus-ai/utils";
+import { upgradeJsonSchemaTo202012 } from "./draft";
+import { tryEnforceStrictSchema } from "./normalize";
+
+/**
+ * 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 const NO_STRICT = $flag("PROMETHEUS_NO_STRICT");
+
+/**
+ * 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 function adaptSchemaForStrict(
+	schema: Record<string, unknown>,
+	strict: boolean,
+): { schema: Record<string, unknown>; strict: boolean } {
+	const upgraded = upgradeJsonSchemaTo202012(schema) as Record<string, unknown>;
+	if (!strict) {
+		return { schema: upgraded, strict: false };
+	}
+
+	return tryEnforceStrictSchema(upgraded);
+}