@oh-my-pi/pi-catalog 18.11.3 → 18.12.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [18.12.0] - 2026-10-17
+
+### Added
+
+- Added the `request-encodings`, `request-encoding-rejection`, and `endpoint-hosts` rule axes, `resolveRequestCompression(model, url)`, and `isCatalogEndpointUrl(model, url)`, declaring which providers' own endpoints decode compressed request bodies: official Anthropic API (gzip), Codex backend (zstd), and GitHub Copilot's API hosts (zstd, then gzip); Moonshot's China host counts as its own endpoint ([#16086](https://github.com/can1357/oh-my-pi/pull/16086) by [@H4vC](https://github.com/H4vC))
+
+### Changed
+
+- Bundled GPT-5.4 rows on OpenAI, Azure, OpenCode Zen, and Command Code report a 1M context window, the window the coding agent already applied at runtime; GitHub Copilot and Factory Droid keep their own windows ([#16094](https://github.com/can1357/oh-my-pi/pull/16094) by [@H4vC](https://github.com/H4vC))
+
+### Fixed
+
+- Fixed custom providers that declare a built-in `providerType` (Azure, GitHub Copilot, OpenCode, ClinePass, DeepSeek, NVIDIA) missing that provider's wire quirks, such as strict Responses pairing and the ClinePass reasoning field: they now follow the same catalog rules as the built-in provider ([#16093](https://github.com/can1357/oh-my-pi/pull/16093) by [@H4vC](https://github.com/H4vC))
+- Fixed OpenCode Zen bringing back its retired bundled models after a failed refresh: the retry-backoff write no longer drops the cached snapshot's retention, so the pruned catalog survives the retry window and offline launches. ([#16054](https://github.com/can1357/oh-my-pi/pull/16054) by [@adi-IL](https://github.com/adi-IL))
+- Fixed `providers.cacheWarming` never arming for Claude on Google Antigravity: Claude models there now declare Vertex Anthropic's five-minute prompt-cache lifetime; Gemini models stay unwarmed because Google's implicit cache has no fixed lifetime ([#15764](https://github.com/can1357/oh-my-pi/issues/15764), [#16025](https://github.com/can1357/oh-my-pi/pull/16025) by [@harshaygadekar](https://github.com/harshaygadekar))
+- Scoped Jev image bounds to the selected models instead of applying them to unrelated native judges ([#16002](https://github.com/can1357/oh-my-pi/pull/16002) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy))
+- Fixed Bedrock sessions rejecting replayed tool names over 64 characters after a model switch ([#15839](https://github.com/can1357/oh-my-pi/issues/15839))
+
 ## [18.11.3] - 2026-10-16
 
 ### Changed

package/dist/types/compat/behavior.d.ts

@@ -78,3 +78,8 @@ export declare function pricingPeerFor(provider: string, model: string): {
     peers: readonly string[];
     peerId: string;
 } | undefined;
+/**
+ * Built-in default model selector chains per agent role (`smol`, `slow`,
+ * `image`, …), most preferred first, in declaration order.
+ */
+export declare function roleDefaultModels(): Readonly<Record<string, readonly string[]>>;

package/dist/types/compat/catalog-endpoint.d.ts

@@ -0,0 +1,8 @@
+import type { Model } from "../types.js";
+/**
+ * Whether {@link url} is HTTPS to {@link model}'s provider's own endpoint: the
+ * host of its bundled base URL or one of its `endpoint-hosts`. A custom model
+ * or provider override that keeps a catalog provider id but points `baseUrl`
+ * at a gateway, proxy, or local server is not.
+ */
+export declare function isCatalogEndpointUrl(model: Model, url: string | undefined): boolean;

package/dist/types/compat/judgment-images.d.ts

@@ -0,0 +1,25 @@
+import type { Model } from "../types.js";
+/** Bounds a judgment model applies to image inputs. */
+export interface JudgmentImageInput {
+    /** Accepted lowercase MIME types; unset adds no model-specific format restriction. */
+    mimeTypes?: readonly string[];
+    /** Images per request. */
+    maxCount?: number;
+    /** Decoded bytes per image. */
+    maxBytes?: number;
+    /** Decoded bytes across all images. */
+    maxTotalBytes?: number;
+    /** Pixels per image, when the image header reports dimensions. */
+    maxPixels?: number;
+    /** Minimum pixels per image, when the image header reports dimensions. */
+    minPixels?: number;
+    /** Inclusive bounds on each side, when the image header reports dimensions. */
+    minSide?: number;
+    maxSide?: number;
+}
+/**
+ * Resolve image bounds assigned to this model by the catalog cascade. KDL
+ * object payloads have scalar children, so `mime-types` is authored as a
+ * comma-separated string and normalized here to the public array type.
+ */
+export declare function resolveJudgmentImageInput(model: Model): JudgmentImageInput | undefined;

package/dist/types/compat/request-compression.d.ts

@@ -0,0 +1,21 @@
+import type { Model } from "../types.js";
+/** `Content-Encoding` values a host may accept on request bodies. */
+export type RequestBodyEncoding = "zstd" | "gzip";
+/** Request-body compression contract for one request. */
+export interface RequestCompressionPolicy {
+    /** Accepted encodings, most preferred first. */
+    readonly encodings: readonly RequestBodyEncoding[];
+    /**
+     * Error-body pattern of a 400/415 that rejects the encoding; `undefined`
+     * treats every 400/415 as a possible rejection.
+     */
+    readonly rejection: RegExp | undefined;
+}
+/**
+ * Compression contract for a request from {@link model} to {@link url}, or
+ * `undefined` when the body must go uncompressed. The `request-encodings` axis
+ * applies only while the URL reaches the provider's own endpoint
+ * ({@link isCatalogEndpointUrl}): a proxy, relay, or rerouted base URL never
+ * receives bytes it cannot read.
+ */
+export declare function resolveRequestCompression(model: Model, url: string): RequestCompressionPolicy | undefined;

package/dist/types/compat/types.d.ts

@@ -328,6 +328,8 @@ export interface CompiledBehavior {
     retryResetTimezones: CompiledRetryResetTimezone[];
     retiredProviders: string[];
     referenceIsolatedProviders: string[];
+    /** Built-in model selector chains per agent role, keyed by role in declaration order. */
+    roleDefaults: Record<string, string[]>;
 }
 /**
  * A string setting from `auth/*.kdl` that may be overridden by environment

package/dist/types/model-cache.d.ts

@@ -20,6 +20,13 @@ export interface CacheEntry<TApi extends Api = Api> {
     models: Model<TApi>[];
     fresh: boolean;
     authoritative: boolean;
+    /**
+     * `authoritative` of the payload row itself, ignoring the
+     * `model_cache_refresh` side row. A failed refresh flips only the side row
+     * (freshness plus retry backoff), so this keeps answering "were `models`
+     * written by an authoritative discovery result?" after such a write.
+     */
+    payloadAuthoritative: boolean;
     updatedAt: number;
     /** Model ids whose live headers were intentionally omitted from disk. */
     headerOmittedModelIds: readonly string[];

package/dist/types/provider-models/openai-compat.d.ts

@@ -245,52 +245,6 @@ export interface ZhipuCodingPlanModelManagerConfig {
     fetch?: FetchImpl;
 }
 export declare function zhipuCodingPlanModelManagerOptions(config?: ZhipuCodingPlanModelManagerConfig): ModelManagerOptions<"openai-completions">;
-/**
- * Fireworks-published cap for the Kimi K2 family. Fireworks' `/v1/models`
- * envelope generically reports `max_completion_tokens: 65536` for every Kimi
- * deployment, but Kimi K2 (instruct / thinking / turbo) on Fireworks is
- * documented to ship long reasoning traces that should be bounded — capping
- * at 32,768 prevents handing callers a budget the router cannot honor.
- * See https://github.com/can1357/oh-my-pi/issues/1849.
- */
-export declare const FIREWORKS_KIMI_MAX_TOKENS = 32768;
-/**
- * Fireworks' output ceiling for Kimi K2.7-Code specifically. Its `/v1/models`
- * generic `max_completion_tokens` is 65,536 and Fireworks serves it in full —
- * verified with a single completion emitting 58,971 output tokens and
- * `max_tokens: 200000` accepted without error. Unlike the older K2.5/K2.6
- * family (see {@link FIREWORKS_KIMI_MAX_TOKENS}), K2.7-Code is not clamped to
- * 32,768; that ceiling only truncated it.
- */
-export declare const FIREWORKS_KIMI_K27_CODE_MAX_TOKENS = 65536;
-/**
- * Returns true for the Kimi K2.5 / K2.6 family served by Fireworks-backed
- * providers (`fireworks` direct, `firepass` router) that share the 32,768
- * `maxTokens` ceiling. Matches both the public catalog id (`kimi-k2.5`,
- * `kimi-k2.6`, `kimi-k2.6-turbo`) and the canonical Fireworks wire id
- * (`accounts/fireworks/{models,routers}/kimi-k2…`).
- *
- * K2.7-Code (incl. `-fast` / `-highspeed`) is deliberately excluded: unlike the
- * earlier K2 family it serves its full context on Fireworks — verified with a
- * single completion emitting 58,971 output tokens and `max_tokens: 200000`
- * accepted without error — so the 32,768 cap would only truncate it. It inherits
- * Fireworks' reported `max_completion_tokens` (65,536) instead.
- */
-export declare function isFireworksKimiK2ModelId(modelId: string): boolean;
-/**
- * Clamp the Kimi K2 family's `maxTokens` to {@link FIREWORKS_KIMI_MAX_TOKENS}
- * on Fireworks-backed providers, leaving every other model untouched.
- */
-export declare function clampFireworksKimiMaxTokens(modelId: string, candidate: number): number;
-export declare function clampFireworksKimiMaxTokens(modelId: string, candidate: number | null): number | null;
-/**
- * Kimi K2.7 Code's documented recommended output budget. Some provider
- * discovery rows report the context-sized `max_completion_tokens` instead.
- */
-export declare const KIMI_K27_CODE_RECOMMENDED_MAX_TOKENS = 32768;
-export declare function isKimiK27CodeModelId(modelId: string): boolean;
-export declare function clampKimiK27CodeMaxTokens(modelId: string, candidate: number): number;
-export declare function clampKimiK27CodeMaxTokens(modelId: string, candidate: number | null): number | null;
 /**
  * Build the Fireworks Fast seed by projecting each base bundled spec into a
  * `<id>-fast` variant. Pushed into the generated catalog (Fast routers never

package/dist/types/types.d.ts

@@ -451,6 +451,8 @@ export interface OpenAICompat {
     reasoningDeltasMayBeCumulative?: boolean;
     /** Strip leaked DeepSeek chat-template special tokens from visible content deltas. Default: auto-detected. */
     stripDeepseekSpecialTokens?: boolean;
+    /** Drop assistant thinking blocks from replayed chat-completions history. Default: false. */
+    stripThinkingHistory?: boolean;
     /** Heal leaked chat-template/tool-call/thinking markup from visible content deltas. Default: auto-detected. */
     streamMarkupHealingPattern?: OpenAIStreamMarkupHealingPattern;
     /** Whether this wire may revise already-streamed text (`stream-revision` axis). Unassigned: append-only. */
@@ -874,12 +876,15 @@ export interface ResolvedOpenAISharedCompat {
  * `buildModel`; request handlers read fields and never detect, resolve, or
  * allocate.
  */
-export type ResolvedOpenAICompat = ResolvedOpenAISharedCompat & Required<Omit<OpenAICompat, "supportsDeveloperRole" | "supportsReasoningEffort" | "trustExplicitThinkingOnly" | "reasoningEffortMap" | "supportsReasoningParams" | "supportsReasoningSummary" | "statefulResponses" | "supportsSamplingParams" | "supportsPenaltyAndStopParams" | "thinkingFormat" | "kimiApiFormat" | "reasoningDisableMode" | "omitReasoningEffort" | "includeEncryptedReasoning" | "filterReasoningHistory" | "disableReasoningOnForcedToolChoice" | "disableReasoningOnToolChoice" | "disableReasoningWithTools" | "supportsToolChoice" | "supportsForcedToolChoice" | "supportsNamedToolChoice" | "reasoningContentField" | "mistralReasoningContentParts" | "requiresReasoningContentForToolCalls" | "requiresReasoningContentForAllAssistantTurns" | "allowsSyntheticReasoningContentForToolCalls" | "syntheticReasoningContentFallback" | "replayReasoningContent" | "qwenPreserveThinking" | "qwenTemplateReasoningEffort" | "requiresThinkingAsText" | "requiresMistralToolIds" | "requiresToolResultName" | "requiresAssistantAfterToolResult" | "requiresAssistantContentForToolCalls" | "stripDeepseekSpecialTokens" | "streamMarkupHealingPattern" | "reasoningDeltasMayBeCumulative" | "emptyLengthFinishIsContextError" | "usesOpenAIToolCallIdLimit" | "promptCacheSessionHeader" | "sessionHeader" | "supportsPromptCacheBreakpoints" | "promptCacheBreakpointTtl" | "openRouterRouting" | "isOpenRouterHost" | "supportsStrictMode" | "supportsLongPromptCacheRetention" | "alwaysSendMaxTokens" | "clampOutputToModelMax" | "wireModelIdMode" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolSchemaFlavor" | "streamFirstEventTimeoutMs" | "streamIdleTimeoutMs" | "streamRevision" | "cacheControlFormat" | "thinkingKeep" | "strictResponsesPairing" | "supportsImageDetailOriginal" | "supportsConfigurationUpdate" | "supportsSteering" | "stripImageInput" | "thinkingLoopGuard" | "whenThinking">> & {
+export type ResolvedOpenAICompat = ResolvedOpenAISharedCompat & Required<Omit<OpenAICompat, "supportsDeveloperRole" | "supportsReasoningEffort" | "trustExplicitThinkingOnly" | "reasoningEffortMap" | "supportsReasoningParams" | "supportsReasoningSummary" | "statefulResponses" | "supportsSamplingParams" | "supportsPenaltyAndStopParams" | "thinkingFormat" | "kimiApiFormat" | "reasoningDisableMode" | "omitReasoningEffort" | "includeEncryptedReasoning" | "filterReasoningHistory" | "disableReasoningOnForcedToolChoice" | "disableReasoningOnToolChoice" | "disableReasoningWithTools" | "supportsToolChoice" | "supportsForcedToolChoice" | "supportsNamedToolChoice" | "reasoningContentField" | "mistralReasoningContentParts" | "requiresReasoningContentForToolCalls" | "requiresReasoningContentForAllAssistantTurns" | "allowsSyntheticReasoningContentForToolCalls" | "syntheticReasoningContentFallback" | "replayReasoningContent" | "qwenPreserveThinking" | "qwenTemplateReasoningEffort" | "requiresThinkingAsText" | "requiresMistralToolIds" | "requiresToolResultName" | "requiresAssistantAfterToolResult" | "requiresAssistantContentForToolCalls" | "stripDeepseekSpecialTokens" | "stripThinkingHistory" | "streamMarkupHealingPattern" | "reasoningDeltasMayBeCumulative" | "emptyLengthFinishIsContextError" | "usesOpenAIToolCallIdLimit" | "promptCacheSessionHeader" | "sessionHeader" | "supportsPromptCacheBreakpoints" | "promptCacheBreakpointTtl" | "openRouterRouting" | "isOpenRouterHost" | "supportsStrictMode" | "supportsLongPromptCacheRetention" | "alwaysSendMaxTokens" | "clampOutputToModelMax" | "wireModelIdMode" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolSchemaFlavor" | "streamFirstEventTimeoutMs" | "streamIdleTimeoutMs" | "streamRevision" | "cacheControlFormat" | "thinkingKeep" | "strictResponsesPairing" | "supportsImageDetailOriginal" | "supportsConfigurationUpdate" | "supportsSteering" | "stripImageInput" | "thinkingLoopGuard" | "whenThinking">> & {
     vercelGatewayRouting?: OpenAICompat["vercelGatewayRouting"];
     extraBody?: OpenAICompat["extraBody"];
     cacheControlFormat?: OpenAICompat["cacheControlFormat"];
     thinkingKeep?: OpenAICompat["thinkingKeep"];
     streamIdleTimeoutMs?: number;
+    stripThinkingHistory?: boolean;
+    /** The configured `baseUrl` is the official OpenAI API (provider `openai`); unset otherwise. */
+    officialEndpoint?: boolean;
     toolStrictMode: ResolvedToolStrictMode;
     /** The model sits behind Vercel AI Gateway. */
     isVercelGatewayHost: boolean;
@@ -1374,6 +1379,8 @@ export interface Model<TApi extends Api = Api> {
     contextWindow: number | null;
     /** Preserve the host's supplied window instead of applying inferred expansion or reference-price caps. */
     contextWindowAuthoritative?: boolean;
+    /** The long-context price tier does not cap the runtime context window when extended context is off. */
+    longContextWindowUncapped?: boolean;
     /** Optional larger prompt window available when extended context is enabled. */
     maxContextWindow?: number;
     maxTokens: number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "18.11.3",
+	"version": "18.12.0",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"keywords": [
 		"ai",
@@ -93,12 +93,12 @@
 		"gen:proto": "bun scripts/generate-protocols.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.11.3",
-		"@oh-my-pi/pi-utils": "18.11.3"
+		"@oh-my-pi/omptype": "18.12.0",
+		"@oh-my-pi/pi-utils": "18.12.0"
 	},
 	"devDependencies": {
 		"@bgotink/kdl": "0.4.0",
-		"@oh-my-pi/pi-ai": "18.11.3",
+		"@oh-my-pi/pi-ai": "18.12.0",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/build.ts

@@ -54,6 +54,11 @@ function applyCatalogAssignments<TApi extends Api>(model: Model<TApi>, catalog:
 	} else {
 		delete model.contextWindowAuthoritative;
 	}
+	if (catalog.longContextWindowUncapped === true) {
+		model.longContextWindowUncapped = true;
+	} else {
+		delete model.longContextWindowUncapped;
+	}
 	const webSearch = catalog.webSearch;
 	if (
 		webSearch === "gemini" ||
@@ -330,6 +335,14 @@ export function applyCatalogCorrections(
 		const maxTokens = numberField(limitsPatch, "maxTokens");
 		if (maxTokens !== undefined) model.maxTokens = maxTokens;
 	}
+	const maxTokensFallback = catalog.maxTokensFallback;
+	if (typeof maxTokensFallback === "number" && model.maxTokens === null) {
+		model.maxTokens = maxTokensFallback;
+	}
+	const maxTokensCeiling = catalog.maxTokensCeiling;
+	if (typeof maxTokensCeiling === "number" && model.maxTokens !== null && model.maxTokens > maxTokensCeiling) {
+		model.maxTokens = maxTokensCeiling;
+	}
 	const contextWindowFloor = catalog.contextWindowFloor;
 	if (typeof contextWindowFloor === "number") {
 		model.contextWindow = Math.max(model.contextWindow ?? 0, contextWindowFloor);

package/src/compat/axes.ts

@@ -259,7 +259,7 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	"requires-thinking-enabled": wire("requiresThinkingEnabled", ["anthropic"]),
 	"requires-tool-result-id": wire("requiresToolResultId", ["anthropic"]),
 	"signing-endpoint": wire("signingEndpoint", ["anthropic"]),
-	"strip-thinking-history": wire("stripThinkingHistory", ["anthropic", "ollama"]),
+	"strip-thinking-history": wire("stripThinkingHistory", ["openai", "anthropic", "ollama"]),
 	"supports-context-management": wire("supportsContextManagement", ["anthropic"]),
 	"supports-output-effort": wire("supportsOutputEffort", ["anthropic"]),
 	"supports-eager-tool-input-streaming": wire("supportsEagerToolInputStreaming", ["anthropic"]),
@@ -355,6 +355,14 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 		shape: "scalar",
 		values: [true, false],
 	},
+	/** Replayed tool calls must satisfy the target wire's declaration charset and length. */
+	"tool-call-name-charset": {
+		key: "toolCallNameCharset",
+		set: "catalog",
+		shape: "scalar",
+		values: ["ascii", "google"],
+	},
+	"tool-call-name-max-length": { key: "toolCallNameMaxLength", set: "catalog", shape: "scalar" },
 	"preserves-max-output-tokens": {
 		key: "preservesMaxOutputTokens",
 		set: "catalog",
@@ -401,6 +409,19 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 		shape: "scalar",
 		values: [true, false],
 	},
+	/**
+	 * The model's long-context price tier does not bound its runtime context
+	 * window: with extended context off, the window is not capped at the
+	 * tier's input threshold (subscription hosts carrying API-equivalent tier
+	 * prices, or a model served at its full window). Explicit user context
+	 * overrides still apply.
+	 */
+	"long-context-window-uncapped": {
+		key: "longContextWindowUncapped",
+		set: "catalog",
+		shape: "scalar",
+		values: [true, false],
+	},
 	"cost-patch": { key: "costPatch", set: "catalog", shape: "object" },
 	"cost-fallback": { key: "costFallback", set: "catalog", shape: "object" },
 	/**
@@ -472,12 +493,41 @@ export const AXES: Readonly<Record<string, AxisDef>> = {
 	/** Longest image edge the host passes to the model: it downscales larger images to fit first. */
 	"image-max-edge": { key: "imageMaxEdge", set: "catalog", shape: "scalar" },
 	"inline-image-byte-budget": { key: "inlineImageByteBudget", set: "catalog", shape: "scalar" },
+	/**
+	 * Supported formats and size bounds for judgment-request images; `mime-types`
+	 * is comma-separated because object payloads have no array shape.
+	 */
+	"judgment-image-input": { key: "judgmentImageInput", set: "catalog", shape: "object" },
+	/**
+	 * `Content-Encoding`s the host decodes on request bodies, most preferred
+	 * first. Applied only while the request reaches the provider's own endpoint
+	 * (see `endpoint-hosts`), so a proxy or rerouted endpoint never receives
+	 * bytes it cannot read. Unassigned: bodies are sent uncompressed.
+	 */
+	"request-encodings": { key: "requestEncodings", set: "catalog", shape: "array", values: ["zstd", "gzip"] },
+	/**
+	 * HTTPS hostnames the provider itself serves besides its bundled base URL's
+	 * host — per-account endpoints such as Copilot's plan hosts. Together with
+	 * that host they define the provider's own endpoint, which tells first-party
+	 * traffic from a custom gateway that reuses the provider id.
+	 */
+	"endpoint-hosts": { key: "endpointHosts", set: "catalog", shape: "array" },
+	/**
+	 * Pattern of the 400/415 error body the host returns when it cannot decode
+	 * a compressed request body. Unassigned: every 400/415 is a possible
+	 * rejection and is re-checked with an uncompressed resend.
+	 */
+	"request-encoding-rejection": { key: "requestEncodingRejection", set: "catalog", shape: "scalar" },
 	/**
 	 * Most questions one System One judgment request may carry; the judge
 	 * splits larger requests. Unassigned: the endpoint takes any batch size.
 	 */
 	"judgment-questions-max": { key: "judgmentQuestionsMax", set: "catalog", shape: "scalar" },
 	"limits-patch": { key: "limitsPatch", set: "catalog", shape: "object" },
+	/** Seeds `maxTokens` only when the row reports none; applied after `limits-patch`. */
+	"max-tokens-fallback": { key: "maxTokensFallback", set: "catalog", shape: "scalar" },
+	/** Most output tokens the host serves: a larger reported `maxTokens` is lowered to it; an unknown one stays unknown. */
+	"max-tokens-ceiling": { key: "maxTokensCeiling", set: "catalog", shape: "scalar" },
 	"long-context-cost": { key: "longContext", set: "catalog", shape: "object" },
 	"prompt-cache": { key: "promptCache", set: "catalog", shape: "object" },
 	"task-sibling-prompt-cache": {

package/src/compat/behavior.ts

@@ -3,7 +3,7 @@
  * (`rules/runtime/behavior.kdl`): provider/model heuristics that run before
  * or outside exact bundled-model lookup — responses routing, API routing,
  * quota tiers, plan requirements, model limits, roster and discovery-mode
- * exclusions, hosted defaults, and pricing peers.
+ * exclusions, hosted defaults, pricing peers, and per-role default models.
  */
 import { globMatch } from "./cascade";
 import rules from "./rules.json";
@@ -225,3 +225,11 @@ export function pricingPeerFor(
 	const alias = rule.aliases.find(candidate => candidate.model === model);
 	return { peers: rule.peers, peerId: alias?.peerId ?? model };
 }
+
+/**
+ * Built-in default model selector chains per agent role (`smol`, `slow`,
+ * `image`, …), most preferred first, in declaration order.
+ */
+export function roleDefaultModels(): Readonly<Record<string, readonly string[]>> {
+	return behavior.roleDefaults;
+}

package/src/compat/catalog-endpoint.ts

@@ -0,0 +1,43 @@
+import { getBundledModels, isGeneratedProvider } from "../models";
+import type { Model } from "../types";
+import { resolveCatalogPolicy } from "./catalog-policy";
+
+const bundledHosts = new Map<string, string | null>();
+
+/** Hostname of the provider's bundled base URL; every provider bundles one origin. */
+function bundledHost(provider: string): string | null {
+	let host = bundledHosts.get(provider);
+	if (host !== undefined) return host;
+	host = null;
+	if (isGeneratedProvider(provider)) {
+		for (const row of getBundledModels(provider)) {
+			try {
+				host = new URL(row.baseUrl).hostname;
+				break;
+			} catch {}
+		}
+	}
+	bundledHosts.set(provider, host);
+	return host;
+}
+
+/**
+ * Whether {@link url} is HTTPS to {@link model}'s provider's own endpoint: the
+ * host of its bundled base URL or one of its `endpoint-hosts`. A custom model
+ * or provider override that keeps a catalog provider id but points `baseUrl`
+ * at a gateway, proxy, or local server is not.
+ */
+export function isCatalogEndpointUrl(model: Model, url: string | undefined): boolean {
+	if (!url) return false;
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return false;
+	}
+	if (parsed.protocol !== "https:") return false;
+	if (parsed.hostname === bundledHost(model.provider)) return true;
+	// The rule compiler validates `endpoint-hosts` as an array of strings.
+	const hosts = resolveCatalogPolicy(model).endpointHosts as readonly string[] | undefined;
+	return hosts?.includes(parsed.hostname) === true;
+}

package/src/compat/judgment-images.ts

@@ -0,0 +1,83 @@
+import { isRecord } from "../utils";
+import type { Model } from "../types";
+import { resolveCatalogPolicy } from "./catalog-policy";
+
+/** Bounds a judgment model applies to image inputs. */
+export interface JudgmentImageInput {
+	/** Accepted lowercase MIME types; unset adds no model-specific format restriction. */
+	mimeTypes?: readonly string[];
+	/** Images per request. */
+	maxCount?: number;
+	/** Decoded bytes per image. */
+	maxBytes?: number;
+	/** Decoded bytes across all images. */
+	maxTotalBytes?: number;
+	/** Pixels per image, when the image header reports dimensions. */
+	maxPixels?: number;
+	/** Minimum pixels per image, when the image header reports dimensions. */
+	minPixels?: number;
+	/** Inclusive bounds on each side, when the image header reports dimensions. */
+	minSide?: number;
+	maxSide?: number;
+}
+
+type NumericField = "maxCount" | "maxBytes" | "maxTotalBytes" | "maxPixels" | "minPixels" | "minSide" | "maxSide";
+
+const NUMERIC_FIELDS: readonly NumericField[] = [
+	"maxCount",
+	"maxBytes",
+	"maxTotalBytes",
+	"maxPixels",
+	"minPixels",
+	"minSide",
+	"maxSide",
+];
+const POLICY_FIELDS: Record<string, true> = {
+	mimeTypes: true,
+	maxCount: true,
+	maxBytes: true,
+	maxTotalBytes: true,
+	maxPixels: true,
+	minPixels: true,
+	minSide: true,
+	maxSide: true,
+};
+const MIME_TYPE = /^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/;
+
+function positiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+/**
+ * Resolve image bounds assigned to this model by the catalog cascade. KDL
+ * object payloads have scalar children, so `mime-types` is authored as a
+ * comma-separated string and normalized here to the public array type.
+ */
+export function resolveJudgmentImageInput(model: Model): JudgmentImageInput | undefined {
+	const value = resolveCatalogPolicy(model).judgmentImageInput;
+	if (!isRecord(value) || Object.keys(value).some(key => !Object.hasOwn(POLICY_FIELDS, key))) return undefined;
+
+	let mimeTypes: readonly string[] | undefined;
+	if (value.mimeTypes !== undefined) {
+		if (typeof value.mimeTypes !== "string") return undefined;
+		const parsed = value.mimeTypes.split(",");
+		if (parsed.some(mimeType => !MIME_TYPE.test(mimeType))) return undefined;
+		mimeTypes = Object.freeze(parsed);
+	}
+
+	const numeric: Partial<Record<NumericField, number>> = {};
+	for (const field of NUMERIC_FIELDS) {
+		const bound = value[field];
+		if (bound === undefined) continue;
+		if (!positiveInteger(bound)) return undefined;
+		numeric[field] = bound;
+	}
+	if (
+		(numeric.minPixels !== undefined && numeric.maxPixels !== undefined && numeric.minPixels > numeric.maxPixels) ||
+		(numeric.minSide !== undefined && numeric.maxSide !== undefined && numeric.minSide > numeric.maxSide)
+	) {
+		return undefined;
+	}
+
+	return { ...(mimeTypes !== undefined && { mimeTypes }), ...numeric };
+}

package/src/compat/request-compression.ts

@@ -0,0 +1,41 @@
+import type { Model } from "../types";
+import { isCatalogEndpointUrl } from "./catalog-endpoint";
+import { resolveCatalogPolicy } from "./catalog-policy";
+
+/** `Content-Encoding` values a host may accept on request bodies. */
+export type RequestBodyEncoding = "zstd" | "gzip";
+
+/** Request-body compression contract for one request. */
+export interface RequestCompressionPolicy {
+	/** Accepted encodings, most preferred first. */
+	readonly encodings: readonly RequestBodyEncoding[];
+	/**
+	 * Error-body pattern of a 400/415 that rejects the encoding; `undefined`
+	 * treats every 400/415 as a possible rejection.
+	 */
+	readonly rejection: RegExp | undefined;
+}
+
+const rejectionPatterns = new Map<string, RegExp>();
+
+/**
+ * Compression contract for a request from {@link model} to {@link url}, or
+ * `undefined` when the body must go uncompressed. The `request-encodings` axis
+ * applies only while the URL reaches the provider's own endpoint
+ * ({@link isCatalogEndpointUrl}): a proxy, relay, or rerouted base URL never
+ * receives bytes it cannot read.
+ */
+export function resolveRequestCompression(model: Model, url: string): RequestCompressionPolicy | undefined {
+	const policy = resolveCatalogPolicy(model);
+	// The rule compiler validates encodings against the axis vocabulary.
+	const encodings = policy.requestEncodings as readonly RequestBodyEncoding[] | undefined;
+	if (!encodings?.length || !isCatalogEndpointUrl(model, url)) return undefined;
+	const source = policy.requestEncodingRejection;
+	if (typeof source !== "string") return { encodings, rejection: undefined };
+	let rejection = rejectionPatterns.get(source);
+	if (!rejection) {
+		rejection = new RegExp(source);
+		rejectionPatterns.set(source, rejection);
+	}
+	return { encodings, rejection };
+}