@gajae-code/ai 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-06-19
+### Added
+
+- Added opt-in `compat.sendSessionHeaders` for the `openai-completions` provider. When enabled (default off), the agent session id is forwarded as vendor-neutral `session_id` and `x-session-id` request headers to any OpenAI-compatible endpoint, letting relays/proxies do session-affinity routing and reuse a server-side prompt cache keyed by the session. Previously only the `openai-responses` provider injected session headers, and only against a first-party OpenAI base URL. Injection runs after the caller's `headers`/`extraHeaders` are merged and before `requestTransform`, and uses `??=` so any header the caller already set always wins; it is skipped entirely when the flag is off or no session id is available, leaving existing provider behavior byte-identical. The first-party `openai-responses` gating is unchanged.
+
+### Fixed
+
+- Prevented OpenAI Codex Responses `invalid_function_parameters` / tool-schema validation error events from being treated as retryable `server_error`s, so malformed request schemas fail fast instead of burning the full retry budget.
+- Read LM Studio `/v1/models` nested metadata such as `meta.n_ctx`, `meta.n_ctx_train`, and `details.max_tokens` when normalizing dynamically discovered GGUF-backed local models.
+- Corrected the bundled `openai-codex/gpt-5.5` context window from an overstated 400K back to its true 272K (272,000-token) window, so context-cap / auto-compaction thresholds no longer let gpt-5.5 sessions overrun the model's real limit before compaction (#873).
+
+## [0.6.1] - 2026-06-18
+
+### Fixed
+
+- Generalized tool `input_schema` root-combinator flattening across providers so discriminated-union tool inputs (e.g. the `computer` tool, a `z.union`) no longer ship a bare top-level `anyOf`/`oneOf`/`allOf` root that strict validators reject. The Anthropic-only fix from 0.5.4 is now the shared, provider-agnostic `flattenToolRootCombinators` (in `utils/schema`) and is applied by Amazon Bedrock, OpenAI Chat Completions / Responses / Codex-Responses / Azure-Responses, Ollama, and Cursor. Previously only Anthropic flattened the root, so those providers forwarded the union root verbatim and a union-root tool failed upstream — Bedrock Converse (including via Kiro/CodeWhisperer relays) returned `400 TOOL_SCHEMA_INVALID: The value at toolConfig.tools.N.toolSpec.inputSchema.json.type must be one of the following: object`. Anthropic behavior is unchanged (it now calls the shared util), Google / Cloud Code Assist keep their own object-merge, and object-root tools, nested combinators, and runtime Zod validation are all untouched.
+
 ## [0.6.0] - 2026-06-18
 ### Fixed
 

package/README.md

@@ -778,6 +778,7 @@ The `openai-completions` API is implemented by many providers with minor differe
 interface OpenAICompat {
 	supportsStore?: boolean; // Whether provider supports the `store` field (default: true)
 	supportsDeveloperRole?: boolean; // Whether provider supports `developer` role vs `system` (default: true)
+	sendSessionHeaders?: boolean; // Forward the session id as `session_id`/`x-session-id` headers for relay session-affinity & prompt-cache reuse (default: false)
 	supportsReasoningEffort?: boolean; // Whether provider supports `reasoning_effort` (default: true)
 	maxTokensField?: "max_completion_tokens" | "max_tokens"; // Which field name to use (default: max_completion_tokens)
 	extraBody?: Record<string, unknown>; // Extra request-body fields for custom proxy routing or provider-specific options

package/dist/types/providers/anthropic.d.ts

@@ -189,10 +189,4 @@ export declare function convertAnthropicMessages(messages: Message[], model: Mod
  * object, so callers like the resolve tool keep working open-map semantics.
  */
 export declare function normalizeAnthropicToolSchema(schema: unknown): unknown;
-/**
- * Anthropic rejects tool `input_schema` roots containing top-level oneOf/anyOf/allOf.
- * Keep the generic normalizer schema-preserving, then flatten only provider-emitted
- * tool roots into one object while leaving nested combinators untouched.
- */
-export declare function normalizeAnthropicToolRootInputSchema(schema: Record<string, unknown>): Record<string, unknown>;
 export {};

package/dist/types/types.d.ts

@@ -606,6 +606,17 @@ export interface OpenAICompat extends ToolChoiceCompat {
     supportsStore?: boolean;
     /** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
     supportsDeveloperRole?: boolean;
+    /**
+     * Whether to forward the agent session id as vendor-neutral session-identity
+     * headers (`session_id`, `x-session-id`) on every chat-completions request.
+     * Off by default. Opt in for OpenAI-compatible proxies/relays that route on
+     * session affinity or reuse a server-side prompt cache keyed by session.
+     * First-party OpenAI does not need this (it has its own gated injection in
+     * the openai-responses provider). Headers are only added when a non-empty
+     * session id is available and are never allowed to overwrite a header the
+     * caller already set via `headers`/`requestTransform`.
+     */
+    sendSessionHeaders?: boolean;
     /**
      * Whether the provider's chat-completions endpoint accepts multiple
      * leading `system`/`developer` messages. When false, ordered system

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

@@ -7,6 +7,7 @@ export * from "./fields";
 export * from "./json-schema-validator";
 export * from "./meta-validator";
 export * from "./normalize";
+export * from "./root-combinator";
 export * from "./spill";
 export * from "./types";
 export * from "./wire";

package/dist/types/utils/schema/root-combinator.d.ts

@@ -0,0 +1,12 @@
+/** True when a JSON Schema node describes an object (explicit `type` or `properties`). */
+export declare function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean;
+/**
+ * Flatten a provider-emitted tool ROOT whose top level is a `oneOf`/`anyOf`/`allOf`
+ * combinator into one `type: "object"` schema: merge object-branch properties,
+ * derive the discriminant (`action`) enum, keep the common required set, and demote
+ * leftover combinators plus per-branch guidance into the description. Nested
+ * combinators (inside individual properties) are left untouched.
+ *
+ * Idempotent: a root that already lacks top-level combinators is returned unchanged.
+ */
+export declare function flattenToolRootCombinators(schema: Record<string, unknown>): Record<string, unknown>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.6.0",
+		"@gajae-code/utils": "0.6.2",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/models.json

@@ -53332,7 +53332,7 @@
 				"cacheRead": 0.5,
 				"cacheWrite": 0
 			},
-			"contextWindow": 400000,
+			"contextWindow": 272000,
 			"maxTokens": 128000,
 			"preferWebsockets": true,
 			"priority": 9,

package/src/provider-models/openai-compat.ts

@@ -176,6 +176,57 @@ function mapWithBundledReference<TApi extends Api>(
 	};
 }
 
+function getNestedModelValue(entry: OpenAICompatibleModelRecord, path: readonly string[]): unknown {
+	let current: unknown = entry;
+	for (const segment of path) {
+		if (!isRecord(current)) {
+			return undefined;
+		}
+		current = current[segment];
+	}
+	return current;
+}
+
+function firstPositiveModelNumber(fallback: number, ...candidates: readonly unknown[]): number {
+	for (const candidate of candidates) {
+		const value = toNumber(candidate);
+		if (value !== undefined && value > 0) {
+			return value;
+		}
+	}
+	return fallback;
+}
+
+function mapLmStudioModel(
+	entry: OpenAICompatibleModelRecord,
+	defaults: Model<"openai-completions">,
+	reference: Model<"openai-completions"> | undefined,
+): Model<"openai-completions"> {
+	const model = mapWithBundledReference(entry, defaults, reference);
+	return {
+		...model,
+		contextWindow: firstPositiveModelNumber(
+			model.contextWindow,
+			entry.context_length,
+			entry.max_context_length,
+			getNestedModelValue(entry, ["meta", "n_ctx"]),
+			getNestedModelValue(entry, ["details", "context_length"]),
+			getNestedModelValue(entry, ["details", "n_ctx"]),
+			getNestedModelValue(entry, ["meta", "n_ctx_train"]),
+		),
+		maxTokens: firstPositiveModelNumber(
+			model.maxTokens,
+			entry.max_completion_tokens,
+			entry.max_tokens,
+			entry.max_output_tokens,
+			getNestedModelValue(entry, ["details", "max_completion_tokens"]),
+			getNestedModelValue(entry, ["details", "max_tokens"]),
+			getNestedModelValue(entry, ["meta", "max_completion_tokens"]),
+			getNestedModelValue(entry, ["meta", "max_tokens"]),
+		),
+	};
+}
+
 function normalizeAnthropicBaseUrl(baseUrl: string | undefined, fallback: string): string {
 	const value = baseUrl?.trim();
 	if (!value) {
@@ -1215,7 +1266,7 @@ export function lmStudioModelManagerOptions(
 				apiKey,
 				mapModel: (entry, defaults) => {
 					const reference = references.get(defaults.id);
-					return mapWithBundledReference(entry, defaults, reference);
+					return mapLmStudioModel(entry, defaults, reference);
 				},
 			}),
 	};

package/src/providers/amazon-bedrock.ts

@@ -33,7 +33,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { toolWireSchema } from "../utils/schema/wire";
+import { flattenToolRootCombinators, toolWireSchema } from "../utils/schema";
 import {
 	isForcedToolChoiceUnsupportedError,
 	markToolChoiceIncapability,
@@ -808,7 +808,7 @@ export function convertToolConfig(
 		toolSpec: {
 			name: tool.name,
 			description: tool.description || "",
-			inputSchema: { json: toolWireSchema(tool) },
+			inputSchema: { json: flattenToolRootCombinators(toolWireSchema(tool)) },
 		},
 	}));
 

package/src/providers/anthropic.ts

@@ -62,7 +62,13 @@ import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { isCopilotTransientModelError } from "../utils/retry";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { COMBINATOR_KEYS, NO_STRICT, toolWireSchema } from "../utils/schema";
+import {
+	COMBINATOR_KEYS,
+	flattenToolRootCombinators,
+	isJsonSchemaObjectNode,
+	NO_STRICT,
+	toolWireSchema,
+} from "../utils/schema";
 import { spillToDescription } from "../utils/schema/spill";
 import { notifyRawSseEvent, wrapFetchForSseDebug } from "../utils/sse-debug";
 import {
@@ -2406,22 +2412,6 @@ const MAX_ANTHROPIC_STRICT_TOOLS = 20;
 const MAX_ANTHROPIC_STRICT_OPTIONAL_PARAMETERS = 24;
 const MAX_ANTHROPIC_STRICT_UNION_PARAMETERS = 16;
 
-/** `minItems` / `maxItems` apply to arrays; Anthropic rejects them on `type: "object"` (including `minItems: 0`/`1`). */
-function isJsonSchemaArrayNode(schema: Record<string, unknown>): boolean {
-	const t = schema.type;
-	if (t === "array") return true;
-	if (Array.isArray(t) && t.includes("array") && !t.includes("object")) return true;
-	return false;
-}
-
-function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean {
-	if (isJsonSchemaArrayNode(schema)) return false;
-	if (schema.type === "object") return true;
-	if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
-	if (isRecord(schema.properties)) return true;
-	return false;
-}
-
 /**
  * Pick the principal non-null scalar type from a `type` keyword. Anthropic accepts
  * `type` as either a single string or an array (e.g. `["number", "null"]` for a
@@ -2573,111 +2563,6 @@ export function normalizeAnthropicToolSchema(schema: unknown): unknown {
 	return result;
 }
 
-function getRequiredNames(schema: Record<string, unknown>): Set<string> {
-	return new Set(
-		Array.isArray(schema.required)
-			? schema.required.filter((entry): entry is string => typeof entry === "string")
-			: [],
-	);
-}
-
-function getSingleLiteralValue(schema: unknown): unknown | undefined {
-	if (!isRecord(schema)) return undefined;
-	if (Object.hasOwn(schema, "const")) return schema.const;
-	if (Array.isArray(schema.enum) && schema.enum.length === 1) return schema.enum[0];
-	return undefined;
-}
-
-function describeAnthropicRootBranch(index: number, branch: Record<string, unknown>, action: unknown): string {
-	const required = [...getRequiredNames(branch)];
-	const parts = [`Branch ${index + 1}`];
-	if (typeof action === "string" || typeof action === "number" || typeof action === "boolean") {
-		parts.push(`action ${JSON.stringify(action)}`);
-	}
-	if (required.length > 0) parts.push(`branch-required fields: ${required.join(", ")}`);
-	if (typeof branch.description === "string" && branch.description.length > 0) parts.push(branch.description);
-	return parts.join("; ");
-}
-function collectAnthropicRootObjectBranches(schema: unknown): Record<string, unknown>[] | undefined {
-	if (!isRecord(schema)) return undefined;
-	if (isJsonSchemaObjectNode(schema)) return [schema];
-
-	const combinatorKeys = COMBINATOR_KEYS.filter(key => Array.isArray(schema[key]));
-	if (combinatorKeys.length === 0) return undefined;
-
-	const branches: Record<string, unknown>[] = [];
-	for (const key of combinatorKeys) {
-		const variants = schema[key];
-		if (!Array.isArray(variants) || variants.length === 0) return undefined;
-		for (const variant of variants) {
-			const nestedBranches = collectAnthropicRootObjectBranches(variant);
-			if (nestedBranches === undefined) return undefined;
-			branches.push(...nestedBranches);
-		}
-	}
-	return branches;
-}
-
-/**
- * Anthropic rejects tool `input_schema` roots containing top-level oneOf/anyOf/allOf.
- * Keep the generic normalizer schema-preserving, then flatten only provider-emitted
- * tool roots into one object while leaving nested combinators untouched.
- */
-export function normalizeAnthropicToolRootInputSchema(schema: Record<string, unknown>): Record<string, unknown> {
-	const result: Record<string, unknown> = { ...schema };
-	const rootCombinators = COMBINATOR_KEYS.filter(key => Array.isArray(result[key]));
-	if (rootCombinators.length === 0) return result;
-
-	const baseProperties = isRecord(result.properties) ? { ...result.properties } : {};
-	const flattenedBranches = rootCombinators
-		.map(key => ({ key, branches: collectAnthropicRootObjectBranches({ [key]: result[key] }) }))
-		.find(entry => entry.branches !== undefined && entry.branches.length > 0);
-
-	result.type = "object";
-	result.properties = baseProperties;
-	result.additionalProperties = result.additionalProperties === undefined ? false : result.additionalProperties;
-
-	if (flattenedBranches?.branches !== undefined) {
-		const variants = flattenedBranches.branches;
-		const commonRequired = variants.map(variant => getRequiredNames(variant));
-		const required = [...commonRequired[0]].filter(name => commonRequired.every(set => set.has(name)));
-		const actionValues: unknown[] = [];
-		const guidance: string[] = [];
-
-		for (const [index, branch] of variants.entries()) {
-			if (isRecord(branch.properties)) {
-				Object.assign(baseProperties, branch.properties);
-				const actionValue = getSingleLiteralValue(branch.properties.action);
-				if (actionValue !== undefined && !actionValues.includes(actionValue)) actionValues.push(actionValue);
-				guidance.push(describeAnthropicRootBranch(index, branch, actionValue));
-			} else {
-				guidance.push(describeAnthropicRootBranch(index, branch, undefined));
-			}
-		}
-
-		if (actionValues.length > 0) {
-			const existingAction = isRecord(baseProperties.action) ? { ...baseProperties.action } : {};
-			delete existingAction.const;
-			baseProperties.action = { ...existingAction, enum: actionValues };
-		}
-		result.required = required;
-		spillToDescription(result, [
-			["rootCombinatorGuidance", guidance],
-			...rootCombinators
-				.filter(key => key !== flattenedBranches.key)
-				.map(key => [key, result[key]] as [string, unknown]),
-		]);
-	} else {
-		spillToDescription(
-			result,
-			rootCombinators.map(key => [key, result[key]]),
-		);
-	}
-
-	for (const key of COMBINATOR_KEYS) delete result[key];
-	return result;
-}
-
 type AnthropicToolInputSchema = Anthropic.Messages.Tool["input_schema"];
 
 type AnthropicToolSchemaPlan = {
@@ -2845,7 +2730,7 @@ function normalizeAnthropicStrictSchema(
 
 function buildAnthropicBaseToolInputSchema(tool: Tool): Record<string, unknown> {
 	const jsonSchema = toolWireSchema(tool);
-	return normalizeAnthropicToolRootInputSchema(
+	return flattenToolRootCombinators(
 		normalizeAnthropicToolSchema({
 			...jsonSchema,
 			type: "object",

package/src/providers/azure-openai-responses.ts

@@ -27,7 +27,7 @@ import {
 	iterateWithIdleTimeout,
 } from "../utils/idle-iterator";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
+import { flattenToolRootCombinators, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { mapToOpenAIResponsesToolChoice } from "../utils/tool-choice";
 import {
@@ -373,7 +373,7 @@ function convertTools(tools: Tool[]): OpenAITool[] {
 		type: "function",
 		name: tool.name,
 		description: tool.description || "",
-		parameters: sanitizeSchemaForOpenAIResponses(toolWireSchema(tool)),
+		parameters: sanitizeSchemaForOpenAIResponses(flattenToolRootCombinators(toolWireSchema(tool))),
 		strict: false,
 	}));
 }

package/src/providers/cursor.ts

@@ -29,7 +29,7 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { parseStreamingJson } from "../utils/json-parse";
 import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
-import { toolWireSchema } from "../utils/schema/wire";
+import { flattenToolRootCombinators, toolWireSchema } from "../utils/schema";
 import { COMPOSER_EDIT_DISCIPLINE_PROMPT, isComposerHarnessModel } from "./composer-discipline";
 import type { McpToolDefinition } from "./cursor/gen/agent_pb";
 import {
@@ -2183,7 +2183,7 @@ function buildMcpToolDefinitions(tools: Tool[] | undefined): McpToolDefinition[]
 	}
 
 	return advertisedTools.map(tool => {
-		const jsonSchema = toolWireSchema(tool);
+		const jsonSchema = flattenToolRootCombinators(toolWireSchema(tool));
 		const schemaValue: JsonValue =
 			jsonSchema && typeof jsonSchema === "object"
 				? (jsonSchema as JsonValue)

package/src/providers/ollama.ts

@@ -19,7 +19,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { toolWireSchema } from "../utils/schema/wire";
+import { flattenToolRootCombinators, toolWireSchema } from "../utils/schema";
 import {
 	isForcedToolChoiceUnsupportedError,
 	markToolChoiceIncapability,
@@ -253,7 +253,7 @@ function convertTools(tools: Tool[] | undefined): OllamaFunctionTool[] | undefin
 		function: {
 			name: tool.name,
 			description: tool.description,
-			parameters: toolWireSchema(tool),
+			parameters: flattenToolRootCombinators(toolWireSchema(tool)),
 		},
 	}));
 }

package/src/providers/openai-codex-responses.ts

@@ -50,7 +50,13 @@ import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-ins
 import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
+import {
+	adaptSchemaForStrict,
+	flattenToolRootCombinators,
+	NO_STRICT,
+	sanitizeSchemaForOpenAIResponses,
+	toolWireSchema,
+} from "../utils/schema";
 import {
 	isForcedToolChoiceUnsupportedError,
 	markToolChoiceIncapability,
@@ -98,6 +104,14 @@ const CODEX_WEBSOCKET_RETRY_BUDGET = CODEX_MAX_RETRIES;
 const CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX = "Codex websocket transport error";
 const CODEX_PREVIOUS_RESPONSE_STALE_CODES = new Set(["previous_response_not_found", "codex_previous_response_stale"]);
 const CODEX_RETRYABLE_EVENT_CODES = new Set(["model_error", "server_error", "internal_error"]);
+const CODEX_NON_RETRYABLE_EVENT_CODES = new Set([
+	"invalid_function_parameters",
+	"invalid_request_error",
+	"invalid_schema",
+	"invalid_tool_schema",
+]);
+const CODEX_NON_RETRYABLE_EVENT_MESSAGE =
+	/invalid[_ -]function[_ -]parameters|invalid schema for function|invalid[_ -]tool[_ -]schema|schema must have type ["']?object["']?/i;
 const CODEX_RETRYABLE_EVENT_MESSAGE =
 	/processing your request|retry your request|temporar(?:y|ily)|overloaded|service.?unavailable|internal error|server error/i;
 const CODEX_PROVIDER_SESSION_STATE_KEY = "openai-codex-responses";
@@ -2658,7 +2672,7 @@ export function convertOpenAICodexResponsesTools(
 			};
 		}
 		const strict = !!(!NO_STRICT && tool.strict);
-		const baseParameters = sanitizeSchemaForOpenAIResponses(toolWireSchema(tool));
+		const baseParameters = sanitizeSchemaForOpenAIResponses(flattenToolRootCombinators(toolWireSchema(tool)));
 		const { schema: parameters, strict: effectiveStrict } = adaptSchemaForStrict(baseParameters, strict);
 		return {
 			type: "function",
@@ -2703,11 +2717,17 @@ class CodexProviderStreamError extends Error {
 }
 
 function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean {
-	const code = getCodexEventErrorCode(rawEvent);
-	if (code && CODEX_RETRYABLE_EVENT_CODES.has(code.toLowerCase())) {
+	const code = getCodexEventErrorCode(rawEvent).toLowerCase();
+	const message = getCodexEventErrorMessage(rawEvent);
+	if (
+		(code && CODEX_NON_RETRYABLE_EVENT_CODES.has(code)) ||
+		(!!message && CODEX_NON_RETRYABLE_EVENT_MESSAGE.test(message))
+	) {
+		return false;
+	}
+	if (code && CODEX_RETRYABLE_EVENT_CODES.has(code)) {
 		return true;
 	}
-	const message = getCodexEventErrorMessage(rawEvent);
 	return !!message && CODEX_RETRYABLE_EVENT_MESSAGE.test(message);
 }
 

package/src/providers/openai-completions-compat.ts

@@ -189,6 +189,7 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 	return {
 		supportsStore: !isNonStandard,
 		supportsDeveloperRole: !isNonStandard,
+		sendSessionHeaders: false,
 		supportsMultipleSystemMessages: supportsMultipleSystemMessagesDefault,
 		supportsReasoningEffort: !isGrok && !isZai,
 		reasoningEffortMap,
@@ -254,6 +255,7 @@ export function resolveOpenAICompat(
 	return {
 		supportsStore: model.compat.supportsStore ?? detected.supportsStore,
 		supportsDeveloperRole: model.compat.supportsDeveloperRole ?? detected.supportsDeveloperRole,
+		sendSessionHeaders: model.compat.sendSessionHeaders ?? detected.sendSessionHeaders,
 		supportsMultipleSystemMessages:
 			model.compat.supportsMultipleSystemMessages ?? detected.supportsMultipleSystemMessages,
 		supportsReasoningEffort: model.compat.supportsReasoningEffort ?? detected.supportsReasoningEffort,

package/src/providers/openai-completions.ts

@@ -57,7 +57,7 @@ import { getKimiCommonHeaders } from "../utils/oauth/kimi";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { callWithCopilotModelRetry } from "../utils/retry";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { adaptSchemaForStrict, NO_STRICT, toolWireSchema } from "../utils/schema";
+import { adaptSchemaForStrict, flattenToolRootCombinators, NO_STRICT, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { type HealedToolCall, modelMayLeakKimiToolCalls, ToolCallHealer } from "../utils/tool-call-healing";
 import { isForcedToolChoice, mapToOpenAICompletionsToolChoice } from "../utils/tool-choice";
@@ -453,6 +453,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				options?.streamFirstEventTimeoutMs,
 				options?.authCredentialType,
 				options?.requestMaxRetries,
+				options?.sessionId,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			getCapturedErrorResponse = captureErrorResponse;
@@ -943,6 +944,7 @@ async function createClient(
 	streamFirstEventTimeoutOverride?: number,
 	authCredentialType?: OpenAICompletionsOptions["authCredentialType"],
 	requestMaxRetries?: number,
+	sessionId?: string,
 ): Promise<{
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -981,6 +983,14 @@ async function createClient(
 		headers["X-OpenRouter-Cache-TTL"] = "3600";
 	}
 	Object.assign(headers, extraHeaders);
+	if (sessionId && resolveOpenAICompat(model).sendSessionHeaders) {
+		// Forward the agent session id as vendor-neutral session-identity headers so
+		// OpenAI-compatible proxies/relays can do session-affinity routing and reuse a
+		// server-side prompt cache. Opt-in via `compat.sendSessionHeaders`; never
+		// overwrite a header the caller already set (model.headers / requestTransform).
+		headers.session_id ??= sessionId;
+		headers["x-session-id"] ??= sessionId;
+	}
 	if (model.provider === "kimi-code") {
 		headers = { ...getKimiCommonHeaders(), ...headers };
 	}
@@ -1832,7 +1842,7 @@ function convertTools(
 ): BuiltOpenAICompletionTools {
 	const adaptedTools = tools.map(tool => {
 		const strict = !NO_STRICT && compat.supportsStrictMode !== false && tool.strict !== false;
-		const baseParameters = toolWireSchema(tool);
+		const baseParameters = flattenToolRootCombinators(toolWireSchema(tool));
 		const adapted = adaptSchemaForStrict(baseParameters, strict);
 		return {
 			tool,

package/src/providers/openai-responses.ts

@@ -50,7 +50,13 @@ import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { callWithCopilotModelRetry } from "../utils/retry";
 import { resolveRetryBudget } from "../utils/retry-budget";
-import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
+import {
+	adaptSchemaForStrict,
+	flattenToolRootCombinators,
+	NO_STRICT,
+	sanitizeSchemaForOpenAIResponses,
+	toolWireSchema,
+} from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { mapToOpenAIResponsesToolChoice, type OpenAIResponsesToolChoice } from "../utils/tool-choice";
 import {
@@ -724,7 +730,7 @@ export function convertTools(tools: Tool[], strictMode: boolean, model: Model<"o
 			} as unknown as OpenAITool;
 		}
 		const strict = !NO_STRICT && strictMode && tool.strict !== false;
-		const baseParameters = toolWireSchema(tool);
+		const baseParameters = flattenToolRootCombinators(toolWireSchema(tool));
 		const responseParameters = sanitizeSchemaForOpenAIResponses(baseParameters);
 		const { schema: parameters, strict: effectiveStrict } = adaptSchemaForStrict(responseParameters, strict);
 		return {

package/src/types.ts

@@ -742,6 +742,17 @@ export interface OpenAICompat extends ToolChoiceCompat {
 	supportsStore?: boolean;
 	/** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
 	supportsDeveloperRole?: boolean;
+	/**
+	 * Whether to forward the agent session id as vendor-neutral session-identity
+	 * headers (`session_id`, `x-session-id`) on every chat-completions request.
+	 * Off by default. Opt in for OpenAI-compatible proxies/relays that route on
+	 * session affinity or reuse a server-side prompt cache keyed by session.
+	 * First-party OpenAI does not need this (it has its own gated injection in
+	 * the openai-responses provider). Headers are only added when a non-empty
+	 * session id is available and are never allowed to overwrite a header the
+	 * caller already set via `headers`/`requestTransform`.
+	 */
+	sendSessionHeaders?: boolean;
 	/**
 	 * Whether the provider's chat-completions endpoint accepts multiple
 	 * leading `system`/`developer` messages. When false, ordered system

package/src/utils/schema/index.ts

@@ -7,6 +7,7 @@ export * from "./fields";
 export * from "./json-schema-validator";
 export * from "./meta-validator";
 export * from "./normalize";
+export * from "./root-combinator";
 export * from "./spill";
 export * from "./types";
 export * from "./wire";

package/src/utils/schema/root-combinator.ts

@@ -0,0 +1,143 @@
+/**
+ * Tool `input_schema` root flattening.
+ *
+ * Tool/function-calling `input_schema` roots MUST be a single JSON Schema object.
+ * Bedrock Converse (`toolConfig.tools[*].toolSpec.inputSchema.json.type must be
+ * one of the following: object`), OpenAI strict mode, Gemini, and Anthropic all
+ * reject roots whose top level is a bare `oneOf`/`anyOf`/`allOf` combinator (the
+ * validators require `type: "object"`).
+ *
+ * Zod `z.union(...)` / `z.discriminatedUnion(...)` tool parameters serialize to
+ * exactly such a combinator root, so this normalization is provider-agnostic and
+ * runs inside the shared wire pipeline (`toolWireSchema`).
+ */
+import { isRecord } from "@gajae-code/utils";
+import { COMBINATOR_KEYS } from "./fields";
+import { spillToDescription } from "./spill";
+
+/** `minItems` / `maxItems` apply to arrays; some validators reject them on `type: "object"`. */
+function isJsonSchemaArrayNode(schema: Record<string, unknown>): boolean {
+	const t = schema.type;
+	if (t === "array") return true;
+	if (Array.isArray(t) && t.includes("array") && !t.includes("object")) return true;
+	return false;
+}
+
+/** True when a JSON Schema node describes an object (explicit `type` or `properties`). */
+export function isJsonSchemaObjectNode(schema: Record<string, unknown>): boolean {
+	if (isJsonSchemaArrayNode(schema)) return false;
+	if (schema.type === "object") return true;
+	if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
+	if (isRecord(schema.properties)) return true;
+	return false;
+}
+
+function getRequiredNames(schema: Record<string, unknown>): Set<string> {
+	return new Set(
+		Array.isArray(schema.required)
+			? schema.required.filter((entry): entry is string => typeof entry === "string")
+			: [],
+	);
+}
+
+function getSingleLiteralValue(schema: unknown): unknown | undefined {
+	if (!isRecord(schema)) return undefined;
+	if (Object.hasOwn(schema, "const")) return schema.const;
+	if (Array.isArray(schema.enum) && schema.enum.length === 1) return schema.enum[0];
+	return undefined;
+}
+
+function describeRootBranch(index: number, branch: Record<string, unknown>, action: unknown): string {
+	const required = [...getRequiredNames(branch)];
+	const parts = [`Branch ${index + 1}`];
+	if (typeof action === "string" || typeof action === "number" || typeof action === "boolean") {
+		parts.push(`action ${JSON.stringify(action)}`);
+	}
+	if (required.length > 0) parts.push(`branch-required fields: ${required.join(", ")}`);
+	if (typeof branch.description === "string" && branch.description.length > 0) parts.push(branch.description);
+	return parts.join("; ");
+}
+
+function collectRootObjectBranches(schema: unknown): Record<string, unknown>[] | undefined {
+	if (!isRecord(schema)) return undefined;
+	if (isJsonSchemaObjectNode(schema)) return [schema];
+
+	const combinatorKeys = COMBINATOR_KEYS.filter(key => Array.isArray(schema[key]));
+	if (combinatorKeys.length === 0) return undefined;
+
+	const branches: Record<string, unknown>[] = [];
+	for (const key of combinatorKeys) {
+		const variants = schema[key];
+		if (!Array.isArray(variants) || variants.length === 0) return undefined;
+		for (const variant of variants) {
+			const nestedBranches = collectRootObjectBranches(variant);
+			if (nestedBranches === undefined) return undefined;
+			branches.push(...nestedBranches);
+		}
+	}
+	return branches;
+}
+
+/**
+ * Flatten a provider-emitted tool ROOT whose top level is a `oneOf`/`anyOf`/`allOf`
+ * combinator into one `type: "object"` schema: merge object-branch properties,
+ * derive the discriminant (`action`) enum, keep the common required set, and demote
+ * leftover combinators plus per-branch guidance into the description. Nested
+ * combinators (inside individual properties) are left untouched.
+ *
+ * Idempotent: a root that already lacks top-level combinators is returned unchanged.
+ */
+export function flattenToolRootCombinators(schema: Record<string, unknown>): Record<string, unknown> {
+	const rootCombinators = COMBINATOR_KEYS.filter(key => Array.isArray(schema[key]));
+	if (rootCombinators.length === 0) return schema;
+	const result: Record<string, unknown> = { ...schema };
+
+	const baseProperties = isRecord(result.properties) ? { ...result.properties } : {};
+	const flattenedBranches = rootCombinators
+		.map(key => ({ key, branches: collectRootObjectBranches({ [key]: result[key] }) }))
+		.find(entry => entry.branches !== undefined && entry.branches.length > 0);
+
+	result.type = "object";
+	result.properties = baseProperties;
+	result.additionalProperties = result.additionalProperties === undefined ? false : result.additionalProperties;
+
+	if (flattenedBranches?.branches !== undefined) {
+		const variants = flattenedBranches.branches;
+		const commonRequired = variants.map(variant => getRequiredNames(variant));
+		const required = [...commonRequired[0]].filter(name => commonRequired.every(set => set.has(name)));
+		const actionValues: unknown[] = [];
+		const guidance: string[] = [];
+
+		for (const [index, branch] of variants.entries()) {
+			if (isRecord(branch.properties)) {
+				Object.assign(baseProperties, branch.properties);
+				const actionValue = getSingleLiteralValue(branch.properties.action);
+				if (actionValue !== undefined && !actionValues.includes(actionValue)) actionValues.push(actionValue);
+				guidance.push(describeRootBranch(index, branch, actionValue));
+			} else {
+				guidance.push(describeRootBranch(index, branch, undefined));
+			}
+		}
+
+		if (actionValues.length > 0) {
+			const existingAction = isRecord(baseProperties.action) ? { ...baseProperties.action } : {};
+			delete existingAction.const;
+			baseProperties.action = { ...existingAction, enum: actionValues };
+		}
+		result.required = required;
+		spillToDescription(result, [
+			["rootCombinatorGuidance", guidance],
+			...rootCombinators
+				.filter(key => key !== flattenedBranches.key)
+				.map(key => [key, result[key]] as [string, unknown]),
+		]);
+	} else {
+		spillToDescription(
+			result,
+			rootCombinators.map(key => [key, result[key]]),
+		);
+	}
+
+	for (const key of COMBINATOR_KEYS) delete result[key];
+	return result;
+}