@linxiraos/pi-ai 1.0.0

package/src/utils/retry-after.ts

@@ -0,0 +1,121 @@
+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 retryAfterMs = parseRetryAfterMsHeader(getHeaderValue(headers, "retry-after-ms"));
+	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 = [retryAfterMs, retryAfter, resetMs, resetSeconds].filter(
+		(value): value is number => value !== undefined,
+	);
+	if (candidates.length === 0) return undefined;
+	return Math.max(...candidates);
+}
+
+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);
+	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;
+}
+
+/** `retry-after-ms` (Anthropic-style): a plain millisecond delta. */
+function parseRetryAfterMsHeader(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const ms = Number(value.trim());
+	if (!Number.isFinite(ms) || ms <= 0) return undefined;
+	return Math.ceil(ms);
+}
+
+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,77 @@
+import { scheduler } from "node:timers/promises";
+import { isRetryableError } from "@linxiraos/pi-utils";
+import { isCopilotTransientModelError, status } from "../error/flags";
+import { getHeadersFromError, getRetryAfterMsFromHeaders } from "./retry-after";
+
+// `isCopilotTransientModelError` now lives in the error module (its classifier
+// home). Re-exported here so existing `../utils/retry` importers keep working.
+export { isCopilotTransientModelError };
+
+// Copilot's model-availability flap is a per-request coin flip across fleet
+// replicas, not backpressure. Measured per-attempt rejection rates for models
+// mid-rollout reach ~70% (gpt-5.4, 2026-08-04), and a live 10-turn run needed 6
+// attempts on one turn — so a small budget just pushes the failure up to the
+// agent-level retry, which restarts the whole turn. Eight attempts on a flat
+// delay keep the residual near 5% at p=0.7 and under 1% at p=0.5, bounded at
+// ~2.8s of dead time in the pathological case.
+const COPILOT_MODEL_RETRY_MAX_ATTEMPTS = 8;
+// Transport blips and status-bearing failures keep the pre-flap budget: they are
+// not coin flips, so a longer ramp only delays surfacing a persistent fault.
+const COPILOT_GENERIC_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
+ * 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;
+			// 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;
+			// Budget is per failure kind, counted over attempts already spent: the
+			// eight-attempt allowance only covers the cheap model-availability reroll.
+			const maxAttempts = transientModelError
+				? COPILOT_MODEL_RETRY_MAX_ATTEMPTS
+				: COPILOT_GENERIC_RETRY_MAX_ATTEMPTS;
+			if (attempt >= maxAttempts - 1) break;
+			// Reroll the model flap on a flat delay: a ramp only adds dead time to a
+			// coin flip the next attempt is equally likely to win. Generic retryable
+			// failures (429/5xx/transport) keep the linear backoff below.
+			let delayMs = transientModelError ? retryBaseDelayMs : retryBaseDelayMs * (attempt + 1);
+			if (!transientModelError) {
+				const errorStatus = status(error);
+				if (errorStatus !== 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

@@ -0,0 +1,168 @@
+# 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 `PI_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 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**
+   - 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`).
+   - Callers MUST preserve an author's explicit `tool.strict === false` on the wire so that `strict: false` and omitted `strict` remain distinguishable — some OpenAI-compat backends over-fill optional fields when the flag is absent but respect it when set to `false` (#4336). Exceptions: `openai-responses` emits explicit `false` only while its `strictMode` gate and `PI_NO_STRICT` permit sending the strict field; `openai-codex-responses` gates explicit `false` on `!PI_NO_STRICT` so the documented global bypass keeps the `strict` key off the wire for Codex proxies that reject it; `openai-completions` emits explicit `false` only in `toolStrictMode === "mixed"` with `compat.supportsStrictMode !== false`, because the `all_strict → none` collapse and providers that reject the `strict` key rely on uniform absence.
+
+---
+
+## 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`
+     - `dependencies`, `dependentSchemas`, `dependentRequired`
+   - 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 "@linxiraos/pi-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("PI_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);
+}