@oh-my-pi/pi-catalog 18.2.6 → 18.2.7

package/src/compat/taxonomy.ts

@@ -14,13 +14,13 @@ import { formatRevision, parseRevisionPrefix } from "./revision";
 import rules from "./rules.json";
 import type { CompiledClass, CompiledIdentityOverride, CompiledMatcher, ModelIdentity } from "./types";
 
-/** Two classes (or two families) tie for one model id. */
+/** Two classes, families, or reviewed override patterns tie for one model id. */
 export class AmbiguousIdentityError extends Error {
 	constructor(
 		readonly model: string,
 		readonly first: string,
 		readonly second: string,
-		kind: "class" | "family",
+		kind: "class" | "family" | "override",
 	) {
 		super(`ambiguous ${kind} for \`${model}\`: \`${first}\` and \`${second}\` tie`);
 		this.name = "AmbiguousIdentityError";
@@ -201,27 +201,50 @@ function ranksInClass(classId: string, model: string, lenient: boolean): Omit<Cl
 	return out;
 }
 
-// Lowercase override index built once per process: avoids re-lowercasing every
-// override model/provider string on every classifyModel call. First override
-// in tree order wins per (model, provider) slot, matching the linear scan it
-// replaced.
+// Exact overrides retain a direct lowercase index. Pattern overrides are few
+// and remain in one static list, ranked only after exact lookup misses.
 interface OverrideBucket {
 	byProvider: Map<string, CompiledIdentityOverride>;
 	agnostic: CompiledIdentityOverride | undefined;
 }
 
-let overrideIndex: Map<string, OverrideBucket> | undefined;
+interface IndexedPatternOverride {
+	override: CompiledIdentityOverride;
+	glob: string;
+	provider?: string;
+	specificity: number;
+}
 
-function getOverrideIndex(): Map<string, OverrideBucket> {
-	if (overrideIndex !== undefined) return overrideIndex;
-	const index = new Map<string, OverrideBucket>();
-	for (const cls of rules.taxonomy.classes) {
+interface OverrideIndexes {
+	exact: Map<string, OverrideBucket>;
+	patterns: IndexedPatternOverride[];
+}
+
+let overrideIndexes: OverrideIndexes | undefined;
+
+function getOverrideIndexes(): OverrideIndexes {
+	if (overrideIndexes !== undefined) return overrideIndexes;
+	const exact = new Map<string, OverrideBucket>();
+	const patterns: IndexedPatternOverride[] = [];
+	const classes: readonly CompiledClass[] = rules.taxonomy.classes;
+	for (const cls of classes) {
 		for (const override of cls.overrides) {
+			if (override.model === undefined) {
+				if (override.glob !== undefined) {
+					patterns.push({
+						override,
+						glob: override.glob,
+						provider: override.provider?.toLowerCase(),
+						specificity: nonWildcardBytes(override.glob),
+					});
+				}
+				continue;
+			}
 			const key = override.model.toLowerCase();
-			let bucket = index.get(key);
+			let bucket = exact.get(key);
 			if (bucket === undefined) {
 				bucket = { byProvider: new Map(), agnostic: undefined };
-				index.set(key, bucket);
+				exact.set(key, bucket);
 			}
 			if (override.provider !== undefined) {
 				const providerKey = override.provider.toLowerCase();
@@ -231,30 +254,68 @@ function getOverrideIndex(): Map<string, OverrideBucket> {
 			}
 		}
 	}
-	overrideIndex = index;
-	return index;
+	overrideIndexes = { exact, patterns };
+	return overrideIndexes;
+}
+
+function overrideIsActive(override: CompiledIdentityOverride, observedAtMs: number | undefined): boolean {
+	return override.expiresAtMs === undefined || observedAtMs === undefined || observedAtMs < override.expiresAtMs;
+}
+
+interface PatternOverrideRanking {
+	winner?: { specificity: number; override: CompiledIdentityOverride };
+	tied?: readonly [CompiledIdentityOverride, CompiledIdentityOverride];
+}
+
+function rankPatternOverrides(
+	patterns: readonly IndexedPatternOverride[],
+	provider: string | undefined,
+	bareModel: string,
+	observedAtMs: number | undefined,
+): PatternOverrideRanking {
+	let winner: { specificity: number; override: CompiledIdentityOverride } | undefined;
+	let tied: readonly [CompiledIdentityOverride, CompiledIdentityOverride] | undefined;
+	for (const pattern of patterns) {
+		const { override, specificity } = pattern;
+		if (pattern.provider !== provider || !overrideIsActive(override, observedAtMs)) continue;
+		if (!globMatch(pattern.glob, bareModel)) continue;
+		if (winner?.specificity === specificity) {
+			tied = [winner.override, override];
+		} else if (winner === undefined || winner.specificity < specificity) {
+			winner = { specificity, override };
+			tied = undefined;
+		}
+	}
+	return { winner, tied };
 }
 
 function findIdentityOverride(
 	provider: string,
 	bareModel: string,
 	observedAtMs: number | undefined,
+	lenient: boolean,
 ): CompiledIdentityOverride | undefined {
-	const bucket = getOverrideIndex().get(bareModel.toLowerCase());
-	if (bucket === undefined) return undefined;
-	const scoped = bucket.byProvider.get(provider.toLowerCase());
-	if (scoped !== undefined) {
-		if (scoped.expiresAtMs === undefined || observedAtMs === undefined || observedAtMs < scoped.expiresAtMs) {
-			return scoped;
-		}
+	const lowerProvider = provider.toLowerCase();
+	const lowerBareModel = bareModel.toLowerCase();
+	const indexes = getOverrideIndexes();
+	const bucket = indexes.exact.get(lowerBareModel);
+	if (bucket !== undefined) {
+		const scoped = bucket.byProvider.get(lowerProvider);
+		if (scoped !== undefined && overrideIsActive(scoped, observedAtMs)) return scoped;
+		const agnostic = bucket.agnostic;
+		if (agnostic !== undefined && overrideIsActive(agnostic, observedAtMs)) return agnostic;
 	}
-	const agnostic = bucket.agnostic;
-	if (agnostic !== undefined) {
-		if (agnostic.expiresAtMs === undefined || observedAtMs === undefined || observedAtMs < agnostic.expiresAtMs) {
-			return agnostic;
-		}
+
+	const scoped = rankPatternOverrides(indexes.patterns, lowerProvider, lowerBareModel, observedAtMs);
+	const ranked =
+		scoped.winner === undefined && scoped.tied === undefined
+			? rankPatternOverrides(indexes.patterns, undefined, lowerBareModel, observedAtMs)
+			: scoped;
+	if (ranked.tied !== undefined) {
+		if (lenient) return undefined;
+		throw new AmbiguousIdentityError(lowerBareModel, ranked.tied[0].id, ranked.tied[1].id, "override");
 	}
-	return undefined;
+	return ranked.winner?.override;
 }
 
 /** Result of collapsing a wire id through the suffix vocabulary. */
@@ -369,8 +430,8 @@ export function stripThinkingVariantSuffix(model: string): string | undefined {
  * other model classified under the same key. Calls with an explicit
  * observedAtMs skip the memo so override expiry stays exact.
  *
- * @throws AmbiguousIdentityError on equal-rank cross-class or cross-family
- * matches unless `opts.lenient`.
+ * @throws AmbiguousIdentityError on equal-rank cross-class, cross-family, or
+ * reviewed-pattern matches unless `opts.lenient`.
  */
 const classifyMemo = new Map<string, ModelIdentity>();
 const CLASSIFY_MEMO_MAX = 4096;
@@ -396,7 +457,7 @@ function classifyModelUncached(provider: string, modelId: string, opts?: Classif
 	const lenient = opts?.lenient === true;
 	const trimmed = modelId.trim();
 	const bare = bareOf(trimmed);
-	const override = findIdentityOverride(provider, bare, opts?.observedAtMs);
+	const override = findIdentityOverride(provider, bare, opts?.observedAtMs, lenient);
 	if (override) {
 		const logical = override.logical ?? trimmed;
 		const cls = override.class ?? classifyRanks(logical, lenient).class;

package/src/compat/types.ts

@@ -5,7 +5,7 @@
  * `behavior.ts`, `resolve.ts`) exposes to consumers.
  */
 import type { Effort } from "../effort";
-import type { KnownApi, ThinkingControlMode, TokenCost } from "../types";
+import type { Api, ThinkingControlMode, TokenCost } from "../types";
 import type { RevisionOp } from "./revision";
 
 /** Class-membership matcher kinds, most to least specific. */
@@ -32,11 +32,9 @@ export interface CompiledRevisionPrefix {
 	anywhere?: boolean;
 }
 
-/** One compiled reviewed identity correction. */
-export interface CompiledIdentityOverride {
+interface CompiledIdentityOverrideFields {
 	id: string;
 	provider?: string;
-	model: string;
 	logical?: string;
 	class?: string;
 	family?: string;
@@ -49,6 +47,21 @@ export interface CompiledIdentityOverride {
 	expiresAtMs?: number;
 }
 
+/** One compiled reviewed identity correction with exactly one bare-model selector. */
+export type CompiledIdentityOverride = CompiledIdentityOverrideFields &
+	(
+		| {
+				/** Exact bare-model selector. */
+				model: string;
+				glob?: never;
+		  }
+		| {
+				model?: never;
+				/** Anchored, case-insensitive bare-model glob. */
+				glob: string;
+		  }
+	);
+
 /** One compiled model class: matchers, families, revision rules, overrides. */
 export interface CompiledClass {
 	id: string;
@@ -588,7 +601,7 @@ export interface CompiledProviderDiscovery {
 export interface CompiledSeedModel {
 	id: string;
 	name: string;
-	api: KnownApi;
+	api: Api;
 	provider: string;
 	baseUrl: string;
 	reasoning: boolean;
@@ -615,8 +628,8 @@ export interface CompiledSeed {
 }
 
 /**
- * One chat-model provider's catalog entry: the non-code half of what the
- * runtime and generator know about a provider. A `providers/<id>.kdl` file
+ * One model provider's catalog entry: the non-code half of what the runtime
+ * and generator know about a provider. A `providers/<id>.kdl` file
  * declares one by carrying `default-model`; files without it are wire-compat
  * only (custom provider ids such as `llama.cpp`).
  */
@@ -634,6 +647,8 @@ export interface CompiledProvider {
 	skipCrossProviderReferenceFills?: boolean;
 	/** Present only for providers enrolled in `generate-models.ts` discovery. */
 	discovery?: CompiledProviderDiscovery;
+	/** Non-chat model kinds mapped to their runtime transport APIs. */
+	kindApis?: Partial<Record<"image" | "tts" | "stt", Api>>;
 	/** Authored bundled rows, when the provider cannot be discovered at generation time. */
 	seed?: CompiledSeed;
 }

package/src/discovery/index.ts

@@ -5,3 +5,4 @@ export * from "./gemini-cli";
 export * from "./gitlab-duo-workflow";
 export * from "./openai-compatible";
 export * from "./protobuf";
+export * from "./typesafe";

package/src/discovery/openai-compatible.ts

@@ -106,6 +106,8 @@ export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
 	apiKey?: string;
 	/** Additional request headers. */
 	headers?: Record<string, string>;
+	/** Query parameters appended to the `/models` probe (e.g. OpenRouter's `output_modalities` roster filter). */
+	query?: Record<string, string>;
 	/** Optional AbortSignal for request cancellation; caller owns its lifecycle. */
 	signal?: AbortSignal;
 	/**
@@ -155,10 +157,11 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 	}
 
 	const fetchImpl = discoveryFetch(options.fetch);
+	const query = options.query ? `?${new URLSearchParams(options.query)}` : "";
 	const fetchPayload = async (signal?: AbortSignal): Promise<unknown | null> => {
 		let response: Response;
 		try {
-			response = await fetchImpl(`${baseUrl}${MODELS_PATH}`, {
+			response = await fetchImpl(`${baseUrl}${MODELS_PATH}${query}`, {
 				method: "GET",
 				headers: requestHeaders,
 				signal,

package/src/discovery/typesafe.ts

@@ -0,0 +1,118 @@
+import type { FetchImpl, ModelSpec } from "../types";
+import { discoveryFetch, isRecord } from "../utils";
+
+/** Public TypeSafe API root shared by discovery and judgment requests. */
+export const TYPESAFE_DEFAULT_BASE_URL = "https://api.typesafe.ai";
+
+/** Wire card returned by TypeSafe's authenticated `GET /v1/models`. */
+export interface TypeSafeModelCard {
+	name: string;
+	description: string;
+	release_date: string;
+}
+
+/** Credentials and transport overrides for TypeSafe account model discovery. */
+export interface FetchTypeSafeModelsOptions {
+	apiKey: string;
+	baseUrl?: string;
+	fetch?: FetchImpl;
+	signal?: AbortSignal;
+}
+
+function normalizeBaseUrl(value: string): string | null {
+	try {
+		const url = new URL(value);
+		return url.toString().replace(/\/+$/, "");
+	} catch {
+		return null;
+	}
+}
+
+function parseModelCard(value: unknown): TypeSafeModelCard | null {
+	if (
+		!isRecord(value) ||
+		typeof value.name !== "string" ||
+		value.name.trim().length === 0 ||
+		typeof value.description !== "string" ||
+		typeof value.release_date !== "string"
+	) {
+		return null;
+	}
+	return {
+		name: value.name.trim(),
+		description: value.description.trim(),
+		release_date: value.release_date,
+	};
+}
+
+/** Validate and de-duplicate the official `{ models: [...] }` response. */
+export function parseTypeSafeModelCards(payload: unknown): TypeSafeModelCard[] | null {
+	if (!isRecord(payload) || !Array.isArray(payload.models)) return null;
+	const cards: TypeSafeModelCard[] = [];
+	const seen = new Set<string>();
+	for (const raw of payload.models) {
+		const card = parseModelCard(raw);
+		if (card === null) return null;
+		if (seen.has(card.name)) continue;
+		seen.add(card.name);
+		cards.push(card);
+	}
+	return cards;
+}
+
+/**
+ * Fetch TypeSafe's account-visible judge models.
+ *
+ * Returns `null` for transport, HTTP, or envelope failures. A valid empty
+ * roster returns `[]`, allowing the model manager to distinguish it from an
+ * unavailable discovery endpoint.
+ */
+export async function fetchTypeSafeModels(
+	options: FetchTypeSafeModelsOptions,
+): Promise<ModelSpec<"typesafe">[] | null> {
+	const baseUrl = normalizeBaseUrl(options.baseUrl ?? TYPESAFE_DEFAULT_BASE_URL);
+	if (baseUrl === null) return null;
+
+	let response: Response;
+	try {
+		response = await discoveryFetch(options.fetch)(`${baseUrl}/v1/models`, {
+			method: "GET",
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${options.apiKey}`,
+			},
+			signal: options.signal,
+		});
+	} catch {
+		return null;
+	}
+	if (!response.ok) return null;
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch {
+		return null;
+	}
+	const cards = parseTypeSafeModelCards(payload);
+	if (cards === null) return null;
+
+	const models: ModelSpec<"typesafe">[] = [];
+	for (const card of cards) {
+		models.push({
+			id: card.name,
+			name: card.description || card.name,
+			api: "typesafe",
+			provider: "typesafe",
+			baseUrl,
+			kind: "judge",
+			reasoning: false,
+			input: ["text"],
+			supportsTools: false,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: null,
+			maxTokens: null,
+		});
+	}
+	return models;
+}

package/src/model-manager.ts

@@ -5,7 +5,15 @@ import { applyCatalogMetrics, CatalogMetricsIndex } from "./identity/metrics";
 import { readModelCache, writeModelCache } from "./model-cache";
 import { type GeneratedProvider, getBundledModels } from "./models";
 import { isTimeBasedCost } from "./pricing";
-import type { Api, Model, ModelCost, ModelSpec, Provider, TokenCost } from "./types";
+import {
+	type Api,
+	type Model,
+	type ModelCost,
+	modelKind,
+	type ModelSpec,
+	type Provider,
+	type TokenCost,
+} from "./types";
 import { isRecord } from "./utils";
 
 const DEFAULT_CACHE_TTL_MS = 2 * 60 * 60 * 1000;
@@ -292,7 +300,7 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 		? await Promise.all([fetchModelsDev(options), dynamicFetcher ? fetchDynamicModels(dynamicFetcher) : null])
 		: [null, null];
 	const modelsDevFetchSucceeded = fetchedModelsDevModels !== null;
-	const normalizedModelsDevModels = fetchedModelsDevModels ?? [];
+	const normalizedModelsDevModels = fetchedModelsDevModels?.models ?? [];
 	const modelsDevModels = additiveStaticModelIds
 		? normalizedModelsDevModels.filter(model => !additiveStaticModelIds.has(model.id))
 		: normalizedModelsDevModels;
@@ -319,7 +327,7 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 	const cacheModels = additiveStaticModelIds
 		? preparedCacheModels.filter(model => !additiveStaticModelIds.has(model.id))
 		: preparedCacheModels;
-	const dynamicModels = fetchedDynamicModels ?? [];
+	const dynamicModels = fetchedDynamicModels?.models ?? [];
 	// A successful empty endpoint result stays authoritative for THIS cycle (so an
 	// intentional catalog emptying still prunes removed models downstream), but
 	// is NOT pinned into the cache as authoritative — that would suppress the
@@ -331,12 +339,20 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 			(dynamicModelsAuthoritative || !hasModelsDevFetcher || modelsDevFetchSucceeded)
 		: modelsDevFetchSucceeded;
 	const mergedWithCache = mergeDynamicModels(staticModels, cacheModels);
-	const mergedWithModelsDev = mergeDynamicModels(mergedWithCache, modelsDevModels);
+	const mergedWithModelsDev = mergeDynamicModels(
+		mergedWithCache,
+		modelsDevModels,
+		fetchedModelsDevModels?.explicitKindModels,
+	);
 	const catalogMetricsSource = modelsDevFetchSucceeded ? normalizedModelsDevModels : preparedCacheModels;
 	const mergedWithCatalogMetrics = additiveStaticModelIds
 		? mergeCatalogMetrics(mergedWithModelsDev, catalogMetricsSource)
 		: mergedWithModelsDev;
-	const mergedModels = mergeDynamicModels(mergedWithCatalogMetrics, dynamicModels);
+	const mergedModels = mergeDynamicModels(
+		mergedWithCatalogMetrics,
+		dynamicModels,
+		fetchedDynamicModels?.explicitKindModels,
+	);
 	const models = collapseBuiltVariants(
 		authoritativeDynamicFetchSucceeded ? retainModelIds(mergedModels, dynamicModels) : mergedModels,
 	);
@@ -423,9 +439,15 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 	};
 }
 
+/** Materialized discovery rows plus kind provenance captured before policy can supply a KDL kind. */
+interface DiscoveredModelSet<TApi extends Api> {
+	models: Model<TApi>[];
+	explicitKindModels: ReadonlySet<Model<TApi>>;
+}
+
 async function fetchModelsDev<TApi extends Api, TModelsDevPayload>(
 	options: ModelManagerOptions<TApi, TModelsDevPayload>,
-): Promise<Model<TApi>[] | null> {
+): Promise<DiscoveredModelSet<TApi> | null> {
 	if (!options.modelsDev) {
 		return null;
 	}
@@ -440,7 +462,7 @@ async function fetchModelsDev<TApi extends Api, TModelsDevPayload>(
 
 async function fetchDynamicModels<TApi extends Api>(
 	fetcher: () => Promise<readonly ModelSpec<TApi>[] | null>,
-): Promise<Model<TApi>[] | null> {
+): Promise<DiscoveredModelSet<TApi> | null> {
 	try {
 		const models = await fetcher();
 		if (models === null) {
@@ -512,6 +534,7 @@ function mergeCatalogMetrics<TApi extends Api>(
 function mergeDynamicModels<TApi extends Api>(
 	baseModels: readonly Model<TApi>[],
 	dynamicModels: readonly Model<TApi>[],
+	explicitKindModels?: ReadonlySet<Model<TApi>>,
 ): Model<TApi>[] {
 	// Empty-side fast paths: `mergeDynamicModels(base, [])` is the common shape
 	// after we've already merged the first pair, and `(...)` with no base
@@ -528,6 +551,9 @@ function mergeDynamicModels<TApi extends Api>(
 			merged.set(dynamicModel.id, dynamicModel);
 			continue;
 		}
+		// A policy-derived kind on a chat row is not permission to replace an
+		// authored runner. Only a kind present before materialization can do so.
+		if (modelKind(existingModel) !== "chat" && !explicitKindModels?.has(dynamicModel)) continue;
 		merged.set(dynamicModel.id, mergeDynamicModel(existingModel, dynamicModel));
 	}
 	return Array.from(merged.values());
@@ -537,12 +563,12 @@ function retainModelIds<TApi extends Api>(
 	models: readonly Model<TApi>[],
 	retainedModels: readonly Model<TApi>[],
 ): Model<TApi>[] {
-	if (retainedModels.length === 0 || models.length === 0) return [];
+	if (models.length === 0) return [];
 	const retainedIds = new Set(retainedModels.map(model => model.id));
-	return models.filter(model => retainedIds.has(model.id));
+	return models.filter(model => modelKind(model) !== "chat" || retainedIds.has(model.id));
 }
 
-const MODEL_CACHE_FINGERPRINT_VERSION = `merge-v4:${VERSION}`;
+const MODEL_CACHE_FINGERPRINT_VERSION = `merge-v5:${VERSION}`;
 
 /**
  * Return the versioned content identity for a static provider slice. Callers
@@ -663,17 +689,20 @@ function preferDiscoveryLimit(discoveryLimit: number | null, fallbackLimit: numb
 	return discoveryLimit;
 }
 
-function buildDiscoveredModelSpecs<TApi extends Api>(value: unknown): Model<TApi>[] {
+function buildDiscoveredModelSpecs<TApi extends Api>(value: unknown): DiscoveredModelSet<TApi> {
+	const models: Model<TApi>[] = [];
+	const explicitKindModels = new Set<Model<TApi>>();
 	if (!Array.isArray(value)) {
-		return [];
+		return { models, explicitKindModels };
 	}
-	const models: Model<TApi>[] = [];
 	for (const item of value) {
 		if (isModelLike(item)) {
-			models.push(buildModel(item as ModelSpec<TApi>));
+			const model = buildModel(item as ModelSpec<TApi>);
+			models.push(model);
+			if (item.kind !== undefined) explicitKindModels.add(model);
 		}
 	}
-	return models;
+	return { models, explicitKindModels };
 }
 
 function isModelLike(value: unknown): value is ModelSpec<Api> {