@oh-my-pi/pi-catalog 18.0.7 → 18.0.9

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [18.0.9] - 2026-08-28
+
+### Added
+
+- Added Z.AI GLM-5.3-Flash to the bundled GLM Coding Plan catalog, with a 1M-token context window, 131,072-token output limit, native image input, and low/high/max thinking levels. It is now available through model discovery and the model picker.
+
+### Fixed
+
+- Fixed Google Antigravity Gemini 3.7 Flash tiered models failing with HTTP 400 errors at minimal or disabled thinking levels; those tiers now use the compatible Gemini 3.7 Flash model routing.
+- Fixed OpenCode Go and Zen GLM-5.3 Flash models exposing an unsupported extra-high reasoning level; they now use the supported low/high/max reasoning levels.
+- Fixed Cloudflare AI Gateway credential handling so stored credentials and routing metadata are parsed and used correctly.
+
+## [18.0.8] - 2026-08-27
+
+### Fixed
+
+- Fixed the thinking control mode for OpenAI models served over Bedrock Converse (`global.openai.gpt-5.6-luna`, `-sol`, `-terra`), which are now classified as `effort` rather than `budget` so requests use OpenAI's reasoning schema.
+- Fixed LiteLLM discovery leaking a colliding bundled model's provider-specific transport onto custom endpoints: a discovered alias (e.g. `kimi-k3`) matching a bundled Fireworks model no longer inherits that model's wire-id transform, which had caused requests to POST a model id the endpoint never advertised and return HTTP 400 ([#9938](https://github.com/can1357/oh-my-pi/issues/9938)).
+
 ## [18.0.7] - 2026-08-26
 
 ### Added

package/dist/types/identity/family.d.ts

@@ -145,24 +145,28 @@ export declare const supportsCodexReasoningSummary: (modelId: string) => boolean
 export declare const isOpenAISamplingRestrictedModelId: (modelId: string) => boolean;
 /**
  * Reasoning-capable GLM coding SKUs: glm-4.5 and up on the base / `-air` /
- * `-turbo` lines. Excludes the vision (`…v`) shape, the non-reasoning
- * `-flash`/`-flashx`/`-preview` variants, and pre-4.5 ids. Matching the family
- * keeps newly-bumped integers (`glm-5.3`, `glm-6`, …) covered without a per-id
- * allowlist.
+ * `-turbo` lines, plus `-flash` from GLM-5.3-Flash on. Excludes the vision
+ * (`…v`) shape, the non-reasoning `-flashx`/`-preview` variants, and pre-4.5
+ * ids. Matching the family keeps newly-bumped integers (`glm-5.4`, `glm-6`, …)
+ * covered without a per-id allowlist.
  */
 export declare const isReasoningGlmModelId: (modelId: string) => boolean;
 /** GLM-5.2+ coding SKUs accept `reasoning_effort` in addition to binary thinking. */
 export declare const isGlm52ReasoningEffortModelId: (modelId: string) => boolean;
 /**
- * GLM-5.3+ coding SKUs. Unlike GLM-5.2 (whose reasoning_effort dialect is
- * host-specific), GLM-5.3+ exposes a uniform wire-exact `low`/`high`/`max`
- * ladder on every host, and thinking can no longer be disabled —
- * `thinking.type` must always be `enabled`. Matching the family keeps future
- * bumps (`glm-5.4`, `glm-6`, …) covered while excluding the vision (`…v`)
- * shape and the non-reasoning `-flash`/`-flashx`/`-preview` variants.
+ * GLM-5.3+ reasoning-effort SKUs. Unlike GLM-5.2 (whose dialect is
+ * host-specific), the base, `-air`, `-turbo`, and `-flash` variants expose a
+ * uniform wire-exact `low`/`high`/`max` ladder on every host, and thinking can
+ * no longer be disabled — `thinking.type` must always be `enabled`. Matching
+ * the family keeps future bumps (`glm-5.4`, `glm-6`, …) covered while excluding
+ * the vision (`…v`) shape and the non-reasoning `-flashx`/`-preview` variants.
  */
 export declare const isGlm53ReasoningEffortModelId: (modelId: string) => boolean;
-/** GLM vision SKUs — the `v` that attaches to the version (`glm-4v`, `glm-4.5v`). */
+/**
+ * GLM SKUs that accept image input: the `v` that attaches to the version
+ * (`glm-4v`, `glm-4.5v`) and the natively multimodal `-flash` line from
+ * GLM-5.3-Flash on, whose id carries no `v` marker.
+ */
 export declare const isGlmVisionModelId: (modelId: string) => boolean;
 /**
  * Coarse vendor-lineage token for "are two models the same family?" checks

package/dist/types/wire/cloudflare-ai-gateway.d.ts

@@ -0,0 +1,18 @@
+/** Provider-native AI Gateway prefix before the upstream route segment. */
+export declare const CLOUDFLARE_AI_GATEWAY_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>";
+/** Anthropic Messages passthrough endpoint. */
+export declare const CLOUDFLARE_AI_GATEWAY_ANTHROPIC_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic";
+/** OpenAI Responses passthrough endpoint. */
+export declare const CLOUDFLARE_AI_GATEWAY_OPENAI_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/openai";
+/** OpenAI-compatible Workers AI endpoint. */
+export declare const CLOUDFLARE_AI_GATEWAY_COMPAT_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat";
+/** Opaque API-key credential payload persisted by Cloudflare AI Gateway login. */
+export interface CloudflareAiGatewayCredential {
+    token: string;
+    accountId?: string;
+    gatewayId?: string;
+}
+/** Parse both structured login credentials and legacy plain gateway tokens. */
+export declare function parseCloudflareAiGatewayCredential(value: string): CloudflareAiGatewayCredential | null;
+/** Serialize the gateway token with the routing identifiers collected during login. */
+export declare function serializeCloudflareAiGatewayCredential(token: string, accountId: string, gatewayId: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "18.0.7",
+	"version": "18.0.9",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -34,11 +34,11 @@
 		"gen:proto": "bun scripts/generate-protocols.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.0.7",
-		"@oh-my-pi/pi-utils": "18.0.7"
+		"@oh-my-pi/omptype": "18.0.9",
+		"@oh-my-pi/pi-utils": "18.0.9"
 	},
 	"devDependencies": {
-		"@oh-my-pi/pi-ai": "18.0.7",
+		"@oh-my-pi/pi-ai": "18.0.9",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/identity/family.ts

@@ -9,6 +9,7 @@
 
 import {
 	bareModelId,
+	type GlmModel,
 	isAnthropicAdaptiveGenAtLeast,
 	isFableOrMythos,
 	parseAnthropicModel,
@@ -283,19 +284,35 @@ export const isOpenAISamplingRestrictedModelId = memo((modelId: string): boolean
 	return isOpenAIWireGen5Plus(modelId) || O_SERIES_REASONING_RE.test(bare);
 });
 
+/**
+ * GLM SKU shapes that carry the reasoning ladders. `base`/`air`/`turbo` have
+ * always been reasoning lines; `flash` joins at GLM-5.3-Flash, the first flash
+ * SKU whose thinking is mandatory (pre-5.3 `-flash` SKUs are non-reasoning).
+ * `flashx` and `preview` stay out.
+ */
+function isGlmReasoningVariant(glm: GlmModel): boolean {
+	switch (glm.variant) {
+		case "base":
+		case "air":
+		case "turbo":
+			return true;
+		case "flash":
+			return semverGte(glm.version, "5.3");
+		default:
+			return false;
+	}
+}
+
 /**
  * Reasoning-capable GLM coding SKUs: glm-4.5 and up on the base / `-air` /
- * `-turbo` lines. Excludes the vision (`…v`) shape, the non-reasoning
- * `-flash`/`-flashx`/`-preview` variants, and pre-4.5 ids. Matching the family
- * keeps newly-bumped integers (`glm-5.3`, `glm-6`, …) covered without a per-id
- * allowlist.
+ * `-turbo` lines, plus `-flash` from GLM-5.3-Flash on. Excludes the vision
+ * (`…v`) shape, the non-reasoning `-flashx`/`-preview` variants, and pre-4.5
+ * ids. Matching the family keeps newly-bumped integers (`glm-5.4`, `glm-6`, …)
+ * covered without a per-id allowlist.
  */
 export const isReasoningGlmModelId = memo((modelId: string): boolean => {
 	const glm = parseGlmModel(bareModelId(modelId));
-	if (!glm || glm.vision) {
-		return false;
-	}
-	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+	if (!glm || glm.vision || !isGlmReasoningVariant(glm)) {
 		return false;
 	}
 	return semverGte(glm.version, "4.5");
@@ -304,37 +321,39 @@ export const isReasoningGlmModelId = memo((modelId: string): boolean => {
 /** GLM-5.2+ coding SKUs accept `reasoning_effort` in addition to binary thinking. */
 export const isGlm52ReasoningEffortModelId = memo((modelId: string): boolean => {
 	const glm = parseGlmModel(bareModelId(modelId));
-	if (!glm || glm.vision) {
-		return false;
-	}
-	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+	if (!glm || glm.vision || !isGlmReasoningVariant(glm)) {
 		return false;
 	}
 	return semverGte(glm.version, "5.2");
 });
 
 /**
- * GLM-5.3+ coding SKUs. Unlike GLM-5.2 (whose reasoning_effort dialect is
- * host-specific), GLM-5.3+ exposes a uniform wire-exact `low`/`high`/`max`
- * ladder on every host, and thinking can no longer be disabled —
- * `thinking.type` must always be `enabled`. Matching the family keeps future
- * bumps (`glm-5.4`, `glm-6`, …) covered while excluding the vision (`…v`)
- * shape and the non-reasoning `-flash`/`-flashx`/`-preview` variants.
+ * GLM-5.3+ reasoning-effort SKUs. Unlike GLM-5.2 (whose dialect is
+ * host-specific), the base, `-air`, `-turbo`, and `-flash` variants expose a
+ * uniform wire-exact `low`/`high`/`max` ladder on every host, and thinking can
+ * no longer be disabled — `thinking.type` must always be `enabled`. Matching
+ * the family keeps future bumps (`glm-5.4`, `glm-6`, …) covered while excluding
+ * the vision (`…v`) shape and the non-reasoning `-flashx`/`-preview` variants.
  */
 export const isGlm53ReasoningEffortModelId = memo((modelId: string): boolean => {
 	const glm = parseGlmModel(bareModelId(modelId));
-	if (!glm || glm.vision) {
-		return false;
-	}
-	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+	if (!glm || glm.vision || !isGlmReasoningVariant(glm)) {
 		return false;
 	}
 	return semverGte(glm.version, "5.3");
 });
 
-/** GLM vision SKUs — the `v` that attaches to the version (`glm-4v`, `glm-4.5v`). */
+/**
+ * GLM SKUs that accept image input: the `v` that attaches to the version
+ * (`glm-4v`, `glm-4.5v`) and the natively multimodal `-flash` line from
+ * GLM-5.3-Flash on, whose id carries no `v` marker.
+ */
 export const isGlmVisionModelId = memo((modelId: string): boolean => {
-	return parseGlmModel(bareModelId(modelId))?.vision === true;
+	const glm = parseGlmModel(bareModelId(modelId));
+	if (!glm) {
+		return false;
+	}
+	return glm.vision || (glm.variant === "flash" && semverGte(glm.version, "5.3"));
 });
 
 /**

package/src/model-thinking.ts

@@ -777,6 +777,14 @@ function inferThinkingControlMode<TApi extends Api>(
 					return "anthropic-budget-effort";
 				}
 			}
+			// Bedrock serves the GPT-5.x models through OpenAI's own request
+			// schema, which rejects Anthropic's budget block outright:
+			// `unknown_parameter: 'thinking'`. It takes `reasoning.effort`
+			// instead. gpt-oss parses as `unknown` (no `gpt-<digits>`), so it
+			// keeps the budget path it ships with today.
+			if (parsedModel.family === "openai") {
+				return "effort";
+			}
 			return "budget";
 
 		default:

package/src/models.json

@@ -28688,7 +28688,7 @@
 			"contextWindow": 1050000,
 			"maxTokens": 128000,
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"efforts": [
 					"low",
 					"medium",
@@ -28727,7 +28727,7 @@
 			"contextWindow": 1050000,
 			"maxTokens": 128000,
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"efforts": [
 					"low",
 					"medium",
@@ -28766,7 +28766,7 @@
 			"contextWindow": 1050000,
 			"maxTokens": 128000,
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"efforts": [
 					"low",
 					"medium",
@@ -64887,38 +64887,6 @@
 			"requiresGlyphTokenization": false,
 			"supportsComputerUse": false
 		},
-		"gemini-3.7-flash-tiered": {
-			"id": "gemini-3.7-flash-tiered",
-			"name": "gemini-3.7-flash-tiered",
-			"api": "google-gemini-cli",
-			"provider": "google-antigravity",
-			"baseUrl": "https://daily-cloudcode-pa.googleapis.com",
-			"reasoning": true,
-			"input": [
-				"text",
-				"image"
-			],
-			"cost": {
-				"input": 0,
-				"output": 0,
-				"cacheRead": 0,
-				"cacheWrite": 0
-			},
-			"contextWindow": 1048576,
-			"maxTokens": 65536,
-			"thinking": {
-				"mode": "google-level",
-				"efforts": [
-					"minimal",
-					"low",
-					"medium",
-					"high"
-				],
-				"requiresEffort": true
-			},
-			"requiresGlyphTokenization": false,
-			"supportsComputerUse": false
-		},
 		"gpt-oss-120b": {
 			"id": "gpt-oss-120b",
 			"name": "GPT OSS 120B",
@@ -294589,6 +294557,55 @@
 			},
 			"supportsComputerUseConfig": false
 		},
+		"glm-5.3-flash": {
+			"id": "glm-5.3-flash",
+			"name": "GLM-5.3-Flash",
+			"api": "anthropic-messages",
+			"provider": "zai",
+			"baseUrl": "https://api.z.ai/api/anthropic",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 0.15,
+				"output": 0.5,
+				"cacheRead": 0.03,
+				"cacheWrite": 0
+			},
+			"contextWindow": 1000000,
+			"maxTokens": 131072,
+			"thinking": {
+				"mode": "anthropic-budget-effort",
+				"efforts": [
+					"low",
+					"high",
+					"max"
+				],
+				"defaultLevel": "max",
+				"requiresEffort": true
+			},
+			"requiresGlyphTokenization": false,
+			"tokenizer": "glm5",
+			"supportsComputerUse": false,
+			"compat": {
+				"officialEndpoint": false,
+				"signingEndpoint": false,
+				"disableStrictTools": false,
+				"disableAdaptiveThinking": false,
+				"allowAnthropicHeaderOverrides": false,
+				"supportsEagerToolInputStreaming": false,
+				"supportsLongCacheRetention": false,
+				"supportsMidConversationSystem": false,
+				"supportsForcedToolChoice": true,
+				"supportsSamplingParams": true,
+				"requiresToolResultId": true,
+				"requiresThinkingEnabled": false,
+				"replayUnsignedThinking": true,
+				"escapeBuiltinToolNames": false
+			}
+		},
 		"glm-5v-turbo": {
 			"id": "glm-5v-turbo",
 			"name": "GLM-5V-Turbo",
@@ -312261,4 +312278,4 @@
 			}
 		}
 	}
-}
+}

package/src/provider-models/cache-provider-id.ts

@@ -60,7 +60,10 @@ export function resolveModelCacheProviderId(providerId: string, options: ModelCa
 			return "cursor:default-effort-v4";
 		case "litellm": {
 			const baseUrl = options.baseUrl ?? getDefaultModelDiscoveryBaseUrl(providerId)!;
-			return `litellm:rich-v7:${Bun.hash(baseUrl).toString(36)}`;
+			// rich-v8 invalidates rows whose `compatConfig` retained a colliding
+			// bundled model's provider-specific transport (e.g. Fireworks
+			// `wireModelIdMode`) before that leak was fixed (issue #9938).
+			return `litellm:rich-v8:${Bun.hash(baseUrl).toString(36)}`;
 		}
 		case "opencode-go":
 		case "opencode-zen": {

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

@@ -2823,6 +2823,9 @@ const OPENCODE_GO_API_ID_OVERRIDES: Readonly<Record<string, Api>> = {
 	"qwen3.5-plus": "openai-completions",
 	"qwen3.6-plus": "openai-completions",
 };
+// Runtime-discovered rows cached before model-identity corrections retain
+// stale capability metadata until the authoritative catalog TTL expires.
+const OPENCODE_CACHE_MIGRATION_MODEL_IDS = ["glm-5.3-flash"] as const;
 
 // Billing-variant suffixes the OpenCode gateways append to a base model id
 // without changing its transport (`deepseek-v4-flash-free`,
@@ -2883,12 +2886,10 @@ function openCodeModelManagerOptions(
 		providerId,
 		cacheProviderId: resolveModelCacheProviderId(providerId, { apiKey, baseUrl: discoveryBaseUrl }),
 		dynamicModelsAuthoritative: true,
-		// The per-id API pins are cache identity: without this, rows cached
-		// before a pin was added keep the wrong endpoint until TTL expiry
-		// (#8957 — 17.3.7 caches held muse-spark-1.2[-contributor] on chat
-		// completions after the pin shipped). Sibling-catalog drift is bounded
-		// by the 2h cache TTL instead.
-		dropCachedModelIdsOnStaticMismatch: Object.keys(apiOverrides),
+		// Per-id route pins and capability migrations are cache identity:
+		// without this, rows cached before a correction keep the stale route or
+		// thinking surface until TTL expiry (#8957, #9960).
+		dropCachedModelIdsOnStaticMismatch: [...Object.keys(apiOverrides), ...OPENCODE_CACHE_MIGRATION_MODEL_IDS],
 		modelsDev: {
 			fetch: () => fetchRevalidatedWellKnownModelsWithTimeout(config?.fetch),
 			map: payload => {
@@ -5397,12 +5398,29 @@ function mapLiteLLMRichEntry<TApi extends Api>(
 							["tools", "tool_choice", "functions", "function_call"].includes(param),
 						)
 					: reference?.supportsTools;
+	// Enrich from the bundled reference with provider-INDEPENDENT reasoning
+	// hints only. The reference is resolved against the global bundled catalog,
+	// so a custom endpoint exposing an alias that collides with a bundled model
+	// (a LiteLLM proxy serving `kimi-k3`, which matches Fireworks' bundled
+	// `kimi-k3`) must not inherit that provider's transport compat. Spreading
+	// the resolved `reference.compat` wholesale leaked `wireModelIdMode`,
+	// `toolSchemaFlavor`, `thinkingFormat`, etc. across the provider boundary —
+	// rewriting the wire id to `accounts/fireworks/models/kimi-k3` for a
+	// non-Fireworks endpoint (issue #9938). `buildModel` re-derives every
+	// transport field from the discovered provider and model id, so only the
+	// effort vocabulary flows through here. Mirrors `discoverOpenAIModelsList`.
+	const referenceCompat = reference?.compat as OpenAICompat | undefined;
 	const compat: OpenAICompat = {
-		...(reference?.compat ?? {}),
 		supportsStore: false,
 		supportsDeveloperRole: false,
 		...(supportedOpenAIParams !== undefined
 			? { supportsReasoningEffort: supportedOpenAIParams.includes("reasoning_effort") }
+			: referenceCompat?.supportsReasoningEffort !== undefined
+				? { supportsReasoningEffort: referenceCompat.supportsReasoningEffort }
+				: {}),
+		...(referenceCompat?.reasoningEffortMap ? { reasoningEffortMap: referenceCompat.reasoningEffortMap } : {}),
+		...(referenceCompat?.omitReasoningEffort !== undefined
+			? { omitReasoningEffort: referenceCompat.omitReasoningEffort }
 			: {}),
 	};
 	return {
@@ -5628,12 +5646,14 @@ export function litellmModelManagerOptions(config?: LiteLLMModelManagerConfig):
 	const baseUrl = config?.baseUrl ?? getDefaultModelDiscoveryBaseUrl("litellm")!;
 	return {
 		providerId: "litellm",
-		// rich-v7 invalidates rows cached before discovery continued past endpoints
-		// that omitted cache pricing. Earlier versions added bundled reference fallback,
-		// moved OpenAI models to Responses, continued past incomplete vision and API
-		// metadata, stripped reseller usage suffixes, filtered placeholder rows, and
-		// mapped rich pricing. Bump the version whenever these mappers change, or warm
-		// authoritative caches keep serving pre-change rows for the full TTL.
+		// rich-v8 invalidates rows whose `compatConfig` retained a colliding
+		// bundled model's provider-specific transport (e.g. Fireworks
+		// `wireModelIdMode`) before that leak was fixed. Earlier versions added
+		// bundled reference fallback, moved OpenAI models to Responses, continued
+		// past incomplete vision/API metadata and endpoints omitting cache
+		// pricing, stripped reseller usage suffixes, filtered placeholder rows,
+		// and mapped rich pricing. Bump the version whenever these mappers change,
+		// or warm authoritative caches keep serving pre-change rows for the full TTL.
 		cacheProviderId: resolveModelCacheProviderId("litellm", { baseUrl }),
 		// litellm is a local-only proxy and is never bundled in models.json (that
 		// would leak the machine's localhost catalog). Prefer the proxy's richer

package/src/variant-collapse.ts

@@ -307,7 +307,7 @@ function geminiLevelFlashFamily(version: "3.6" | "3.7", ...additionalMembers: st
 }
 
 const GEMINI_36_FLASH_FAMILY = geminiLevelFlashFamily("3.6", "gemini-3.6-flash-tiered");
-const GEMINI_37_FLASH_FAMILY = geminiLevelFlashFamily("3.7");
+const GEMINI_37_FLASH_FAMILY = geminiLevelFlashFamily("3.7", "gemini-3.7-flash-tiered");
 
 function geminiProFamily(mode: "budget" | "google-level"): EffortVariantFamily {
 	const budget = mode === "budget";

package/src/wire/cloudflare-ai-gateway.ts

@@ -0,0 +1,44 @@
+import { isRecord } from "../utils";
+
+/** Provider-native AI Gateway prefix before the upstream route segment. */
+export const CLOUDFLARE_AI_GATEWAY_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>";
+/** Anthropic Messages passthrough endpoint. */
+export const CLOUDFLARE_AI_GATEWAY_ANTHROPIC_BASE_URL = `${CLOUDFLARE_AI_GATEWAY_BASE_URL}/anthropic`;
+/** OpenAI Responses passthrough endpoint. */
+export const CLOUDFLARE_AI_GATEWAY_OPENAI_BASE_URL = `${CLOUDFLARE_AI_GATEWAY_BASE_URL}/openai`;
+/** OpenAI-compatible Workers AI endpoint. */
+export const CLOUDFLARE_AI_GATEWAY_COMPAT_BASE_URL = `${CLOUDFLARE_AI_GATEWAY_BASE_URL}/compat`;
+
+/** Opaque API-key credential payload persisted by Cloudflare AI Gateway login. */
+export interface CloudflareAiGatewayCredential {
+	token: string;
+	accountId?: string;
+	gatewayId?: string;
+}
+
+/** Parse both structured login credentials and legacy plain gateway tokens. */
+export function parseCloudflareAiGatewayCredential(value: string): CloudflareAiGatewayCredential | null {
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	if (!trimmed.startsWith("{")) return { token: trimmed };
+	try {
+		const parsed: unknown = JSON.parse(trimmed);
+		if (!isRecord(parsed)) return null;
+		if (typeof parsed.token !== "string" || !parsed.token.trim()) return null;
+		if (parsed.accountId !== undefined && typeof parsed.accountId !== "string") return null;
+		if (parsed.gatewayId !== undefined && typeof parsed.gatewayId !== "string") return null;
+		const credential: CloudflareAiGatewayCredential = { token: parsed.token.trim() };
+		const accountId = parsed.accountId?.trim();
+		const gatewayId = parsed.gatewayId?.trim();
+		if (accountId) credential.accountId = accountId;
+		if (gatewayId) credential.gatewayId = gatewayId;
+		return credential;
+	} catch {
+		return null;
+	}
+}
+
+/** Serialize the gateway token with the routing identifiers collected during login. */
+export function serializeCloudflareAiGatewayCredential(token: string, accountId: string, gatewayId: string): string {
+	return JSON.stringify({ token: token.trim(), accountId: accountId.trim(), gatewayId: gatewayId.trim() });
+}