@oh-my-pi/pi-catalog 17.4.0 → 17.4.2

package/dist/types/discovery/cursor-proto.d.ts

@@ -25,6 +25,12 @@ export declare enum DiagnosticSeverity {
     INFORMATION = 3,
     HINT = 4
 }
+/** Cursor agent enum CursorRuleSource. */
+export declare enum CursorRuleSource {
+    UNSPECIFIED = 0,
+    TEAM = 1,
+    USER = 2
+}
 /** Cursor agent enum ForceBackgroundShellStatus. */
 export declare enum ForceBackgroundShellStatus {
     UNSPECIFIED = 0,

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

@@ -102,6 +102,13 @@ export declare const isMinimaxM3FamilyModelId: (modelId: string) => boolean;
  * and `none`.
  */
 export declare const isOpenAIGptOssModelId: (modelId: string) => boolean;
+/**
+ * Meta Muse Spark ids (`muse-spark-1.1`, `muse-spark-1.2`,
+ * `muse-spark-1.2-contributor`, `meta/muse-spark-1.2`). The Responses
+ * `reasoning.effort` wire accepts `none` (thinking-off) plus
+ * `minimal`/`low`/`medium`/`high`/`xhigh`.
+ */
+export declare const isMuseSparkModelId: (modelId: string) => boolean;
 /** OpenAI model ids (gpt-*, chatgpt-*, o1/o3/o4 SKUs, codex-*, or openai/*). */
 export declare const isOpenAIModelId: (modelId: string) => boolean;
 /**

package/dist/types/index.d.ts

@@ -16,3 +16,4 @@ export * from "./wire/codex.js";
 export * from "./wire/coreweave.js";
 export * from "./wire/gemini-headers.js";
 export * from "./wire/github-copilot.js";
+export * from "./wire/image-fetchers.js";

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

@@ -31,11 +31,11 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
     /** Cached model ids whose presence forces refresh when the static or migration-policy fingerprint changes. */
     dropCachedModelIdsOnStaticMismatch?: readonly string[];
     /**
-     * Trusted, provider-wide request headers (compile-time constants, never
-     * credentials) that the cache may restore by value for any model whose live
-     * headers matched them at write time. Lets header-bearing dynamic models
-     * without a bundled static entry survive offline reads instead of being
-     * dropped as unrestorable (e.g. GitHub Copilot's User-Agent + API version).
+     * Trusted, provider-wide request headers that can be safely re-derived at
+     * cache-read time. The cache never persists their values. Models whose live
+     * headers matched this record at write time can survive offline reads without
+     * a bundled static source, including configured discovery providers whose
+     * bearer header comes from the current local config.
      */
     restorableHeaderFallback?: Record<string, string>;
     /** Optional dynamic endpoint fetcher. */

package/dist/types/provider-models/cache-provider-id.d.ts

@@ -2,6 +2,8 @@ export interface ModelCacheProviderIdOptions {
     apiKey?: string;
     baseUrl?: string;
 }
+/** Whether a provider's model-cache namespace requires its resolved credential. */
+export declare function isCredentialScopedModelCacheProvider(providerId: string): boolean;
 export declare function getDefaultModelDiscoveryBaseUrl(providerId: string): string | undefined;
 /** Resolve an Ollama model-cache namespace scoped to the normalized discovery endpoint. */
 export declare function resolveOllamaModelCacheProviderId(providerId: string, baseUrl?: string): string;

package/dist/types/provider-models/descriptors.d.ts

@@ -205,7 +205,7 @@ export declare const CATALOG_PROVIDERS: readonly [{
     readonly id: "litellm";
     readonly defaultModel: "claude-opus-4-8";
     readonly envVars: readonly ["LITELLM_API_KEY"];
-    readonly createModelManagerOptions: (config: ModelManagerConfig) => import("../index.js").ModelManagerOptions<"openai-completions", unknown>;
+    readonly createModelManagerOptions: (config: ModelManagerConfig) => import("../index.js").ModelManagerOptions<import("../index.js").Api, unknown>;
     readonly catalogDiscovery: {
         readonly label: "LiteLLM";
         readonly allowUnauthenticated: true;

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

@@ -568,12 +568,14 @@ export interface FetchLiteLLMRichModelsOptions<TApi extends Api> {
     signal?: AbortSignal;
     timeoutMs?: number;
     referenceResolver?: (modelId: string) => ModelSpec<TApi> | undefined;
+    resolveApi?: (entry: Record<string, unknown>, modelId: string) => TApi;
 }
 export declare const OPENAI_COMPAT_DISCOVERY_DEFAULT_CONTEXT_WINDOW = 128000;
 export declare const OPENAI_COMPAT_DISCOVERY_DEFAULT_MAX_TOKENS = 32768;
 export declare function normalizeLiteLLMManagementBaseUrl(baseUrl: string): string;
+export declare function resolveLiteLLMApi(entry: Record<string, unknown> | undefined, id: string, fallbackApi?: Api): Api;
 export declare function fetchLiteLLMRichModels<TApi extends Api>(options: FetchLiteLLMRichModelsOptions<TApi>): Promise<ModelSpec<TApi>[] | null>;
-export declare function litellmModelManagerOptions(config?: LiteLLMModelManagerConfig): ModelManagerOptions<"openai-completions">;
+export declare function litellmModelManagerOptions(config?: LiteLLMModelManagerConfig): ModelManagerOptions<Api>;
 export interface VllmModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;

package/dist/types/types.d.ts

@@ -123,7 +123,7 @@ export interface Usage {
 }
 export type OpenAIReasoningFormat = "openai" | "openrouter" | "zai" | "kimi" | "qwen" | "qwen-chat-template";
 export type OpenAIReasoningDisableMode = "omit" | "lowest-effort" | "none-effort" | "openrouter-enabled-false" | "zai-thinking-disabled" | "qwen-enable-thinking-false" | "qwen-template-false";
-export type OpenAIStreamMarkupHealingPattern = "kimi" | "dsml" | "thinking";
+export type OpenAIStreamMarkupHealingPattern = "kimi" | "dsml" | "qwen" | "thinking";
 /**
  * Compatibility settings for openai-completions API.
  * Use this to override URL-based auto-detection for custom providers.
@@ -812,6 +812,8 @@ export interface Model<TApi extends Api = Api> {
     preferWebsockets?: boolean;
     /** Codex Responses Lite transport: send the lite marker and carry instructions/tools as input items (mirrors codex-rs `use_responses_lite`). */
     useResponsesLite?: boolean;
+    /** Codex Code Mode restriction: model expects tools routed through a programmatic exec surface (mirrors codex-rs `tool_mode`). */
+    toolMode?: "code_mode_only";
     /** Preferred model to switch to when context promotion is triggered (model id or provider/id). */
     contextPromotionTarget?: string;
     /** Preferred model to use only for compaction (model id or provider/id); the active session model is unchanged. */

package/dist/types/variant-collapse.d.ts

@@ -58,7 +58,7 @@ export declare const ANTIGRAVITY_VARIANT_COLLAPSE_TABLE: VariantCollapseTable;
 /** `google-gemini-cli` Gemini families on the official CLI's level transport. */
 export declare const GEMINI_CLI_VARIANT_COLLAPSE_TABLE: VariantCollapseTable;
 export declare const DEVIN_VARIANT_COLLAPSE_TABLE: VariantCollapseTable;
-/** `cursor` Grok families: per-effort siblings collapsed per service-tier lane. */
+/** `cursor` per-effort sibling families collapsed per service-tier lane: Grok 4.5/4.6 plus GPT-5.6 Luna/Sol/Terra. */
 export declare const CURSOR_VARIANT_COLLAPSE_TABLE: VariantCollapseTable;
 /** Provider id → hand collapse table. The CCA providers diverge on thinking transport. */
 export declare const VARIANT_COLLAPSE_TABLES: Readonly<Record<string, VariantCollapseTable>>;
@@ -91,10 +91,11 @@ export declare function isVariantCollapsedSpec(spec: VariantSpecLike): boolean;
  */
 export declare function collapseEffortVariants<TSpec extends VariantSpecLike>(specs: readonly TSpec[], table: VariantCollapseTable): TSpec[];
 /**
- * Collapse a full mixed-provider list: per provider, the hand table (when
- * registered) plus the automatic `X`/`X-thinking` pair rule. Used by the
- * catalog generator; the runtime equivalent lives at the model-manager merge
- * point. Output is regrouped by provider — callers re-sort.
+ * Collapse a full mixed-provider list: per provider, the hand table, Cursor's
+ * conservative live effort-sibling rule, and the automatic `X`/`X-thinking`
+ * pair rule. Used by the catalog generator; the runtime equivalent lives at
+ * the model-manager merge point. Output is regrouped by provider — callers
+ * re-sort.
  */
 export declare function collapseEffortVariantsAcrossProviders<TSpec extends VariantSpecLike>(specs: readonly TSpec[]): TSpec[];
 /**
@@ -107,29 +108,30 @@ export declare function collapseEffortVariantsAcrossProviders<TSpec extends Vari
 export declare function collapseBuiltModelVariants<TApi extends Api>(models: readonly Model<TApi>[]): Model<TApi>[];
 /**
  * Resolve a retired effort-tier variant id (collapsed member, recycled id) to
- * its replacement model id for `provider` via the hand table. Returns
- * `undefined` when the id is not a known alias; derived `X-thinking` members
- * resolve through `stripThinkingVariantToken` instead. Callers must try an
- * exact model lookup first — a live model always wins over an alias.
+ * its replacement model id for `provider` via hand-table or registered live
+ * aliases. Returns `undefined` when the id is not a known alias; derived
+ * `X-thinking` members also resolve through `stripThinkingVariantToken`.
+ * Callers must try an exact model lookup first — a live model always wins over
+ * an alias.
  */
 export declare function resolveVariantAlias(provider: Provider, modelId: string): string | undefined;
 /** Bare-id alias hit: replacement id plus the providers declaring it. */
 export interface BareVariantAliasHit {
     id: string;
-    /** Providers whose table declares the alias — candidates from these win ties. */
+    /** Providers declaring the alias — candidates from these win ties. */
     providers: readonly Provider[];
 }
 /**
- * Provider-agnostic hand-table alias lookup for bare-id selectors. Returns
- * the declaring providers so callers can prefer their models when the
- * replacement id exists on unrelated providers too (e.g. a retired Cursor
- * tier id must not resolve to `openai/gpt-5.4`).
+ * Provider-agnostic alias lookup for bare-id selectors. Returns the declaring
+ * providers so callers can prefer their models when the replacement id exists
+ * on unrelated providers too (e.g. a retired Cursor tier id must not resolve
+ * to `openai/gpt-5.4`).
  */
 export declare function resolveBareVariantAlias(modelId: string): BareVariantAliasHit | undefined;
 /**
  * Reverse alias lookup: the retired ids that resolve to `modelId` for
- * `provider` via the hand table. Used to re-key config keyed by raw member
- * ids (models.yml `modelOverrides`, suppressed selectors) onto the collapsed
- * model. Empty for providers without a table.
+ * `provider` via hand-table or registered live aliases. Used to re-key config
+ * keyed by raw member ids (models.yml `modelOverrides`, suppressed selectors)
+ * onto the collapsed model.
  */
 export declare function getVariantAliasSources(provider: Provider, modelId: string): readonly string[];

package/dist/types/wire/codex.d.ts

@@ -26,6 +26,8 @@ export declare const OPENAI_HEADERS: {
     readonly RESPONSES_LITE: "x-openai-internal-codex-responses-lite";
     /** DeviceCheck attestation envelope (codex-rs `X_OAI_ATTESTATION_HEADER`); sent on ChatGPT-OAuth requests. */
     readonly ATTESTATION: "x-oai-attestation";
+    /** Client-declared data residency for region-pinned enterprise workspaces. */
+    readonly RESIDENCY: "x-openai-internal-codex-residency";
 };
 export declare const OPENAI_HEADER_VALUES: {
     readonly BETA_RESPONSES: "responses=experimental";
@@ -43,3 +45,22 @@ export declare const JWT_CLAIM_PATH: "https://api.openai.com/auth";
  * Returns undefined if the token is not a valid Codex JWT.
  */
 export declare function getCodexAccountId(accessToken: string): string | undefined;
+/**
+ * Extract the account's data residency from a Codex JWT access token.
+ *
+ * Enterprise ChatGPT workspaces can be pinned to a region. Such a workspace
+ * rejects a Codex request whose egress does not match it — HTTP 401
+ * `Workspace is not authorized in this region.` — unless the client declares
+ * the residency itself. The token already carries it, so no configuration is
+ * needed: `chatgpt_data_residency` is the authoritative claim, with
+ * `chatgpt_compute_residency` as the fallback for tokens that only carry that.
+ *
+ * Returns undefined for a non-JWT token, or for the (common) accounts whose
+ * claims omit residency entirely — those workspaces are not region-pinned.
+ */
+export declare function getCodexResidency(accessToken: string): string | undefined;
+/**
+ * Adds the token's workspace residency to Codex request headers without
+ * replacing a caller-supplied value.
+ */
+export declare function applyCodexResidencyHeader(headers: Headers | Record<string, string>, accessToken: string): void;

package/dist/types/wire/image-fetchers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Identification of provider-side image fetchers.
+ *
+ * A request may carry an image either inline (base64) or as a URL. With a URL,
+ * the provider's backend performs its own server-side GET against that URL, so
+ * a local blob server sees an inbound request from vendor infrastructure rather
+ * than from the client. This module names those fetchers, letting a blob server
+ * attribute an inbound GET to the vendor that issued it — which is how a caller
+ * learns where a request actually landed when a router sits between them and
+ * the model.
+ *
+ * NOT an authentication mechanism. Every value here is a request header chosen
+ * by the caller and is trivially forged. Authorize blob reads with an
+ * unguessable URL (single-use capability token, short TTL) and treat a fetcher
+ * match as attribution/telemetry only.
+ *
+ * Each entry was captured from a live fetch triggered by handing that vendor's
+ * API a URL-sourced image.
+ */
+/** Vendor whose infrastructure performed an inbound fetch. */
+export type ImageFetcherVendor = "openai" | "anthropic" | "xai" | "google";
+/** Registry key for a known fetcher. */
+export type ImageFetcherId = "openai-file-downloader" | "anthropic-claude-user" | "anthropic-claude-user-preview" | "xai-image-api-fetch" | "google";
+/** Request signature of one provider-side fetcher. */
+export interface ImageFetcherIdentity {
+    vendor: ImageFetcherVendor;
+    /** Human-readable name for logs and UI. */
+    label: string;
+    /**
+     * `User-Agent` contract: an exact string for fetchers that send a fixed
+     * value, or a pattern for those embedding a client version.
+     */
+    userAgent: string | RegExp;
+    /**
+     * Vendor-proprietary headers observed alongside the agent, used to
+     * corroborate a `User-Agent` claim. Generic infrastructure headers
+     * (`traceparent`, `x-cloud-trace-context`) are deliberately excluded: they
+     * are emitted by unrelated infrastructure and corroborate nothing. Empty
+     * means the agent string is the only available signal, so
+     * {@link ImageFetcherMatch.corroborated} can never be true for that entry.
+     */
+    markerHeaders: readonly string[];
+    /** API surface the capture came from. */
+    observedVia: string;
+    /** Operational caveats a blob server should account for. */
+    note?: string;
+}
+/**
+ * Known provider-side fetchers.
+ *
+ * Agent contracts do not overlap — exact strings never collide with the
+ * versioned patterns — so lookup order carries no meaning.
+ */
+export declare const IMAGE_FETCHERS: Readonly<Record<ImageFetcherId, ImageFetcherIdentity>>;
+/** Attribution outcome for one inbound request. */
+export interface ImageFetcherMatch {
+    id: ImageFetcherId;
+    identity: ImageFetcherIdentity;
+    /**
+     * Whether every proprietary marker header for the matched identity is
+     * present. Always false for identities declaring no markers — absence of
+     * corroboration is not evidence against the match.
+     */
+    corroborated: boolean;
+}
+/** Inbound header bag, as exposed by either `fetch` or a Node-style server. */
+export type InboundHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Attribute an inbound blob request to a known provider-side fetcher, or
+ * `null` when the agent matches none.
+ *
+ * Matches on `User-Agent` alone and reports marker-header corroboration
+ * separately; callers MUST NOT treat either as proof of origin. Gate access on
+ * the unguessable URL.
+ */
+export declare function identifyImageFetcher(headers: InboundHeaders): ImageFetcherMatch | null;

package/package.json

@@ -1,10 +1,10 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "17.4.0",
+	"version": "17.4.2",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"homepage": "https://omp.sh",
-	"author": "Can Boluk",
+	"author": "Stencil Labs, Inc.",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -34,11 +34,11 @@
 		"gen:proto": "bun scripts/generate-protocols.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "17.4.0",
-		"@oh-my-pi/pi-utils": "17.4.0"
+		"@oh-my-pi/omptype": "17.4.2",
+		"@oh-my-pi/pi-utils": "17.4.2"
 	},
 	"devDependencies": {
-		"@oh-my-pi/pi-ai": "17.4.0",
+		"@oh-my-pi/pi-ai": "17.4.2",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {
@@ -48,6 +48,8 @@
 		"src",
 		"README.md",
 		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD-PARTY-NOTICES.txt",
 		"dist/types"
 	],
 	"exports": {

package/src/compat/openai.ts

@@ -759,7 +759,7 @@ export function buildOpenAIResponsesCompat(spec: OpenAIResponsesSpecLike): Resol
 		disableReasoningOnForcedToolChoice: isKimiModel,
 		disableReasoningOnToolChoice: isDeepseekFamily && reasoningCapable && !isOpenRouter,
 		supportsToolChoice: true,
-		supportsForcedToolChoice: true,
+		supportsForcedToolChoice: spec.provider !== "opencode-go" && spec.provider !== "opencode-zen",
 		supportsNamedToolChoice: STRING_ONLY_NAMED_TOOL_CHOICE_PROVIDERS[spec.provider] !== true,
 		reasoningContentField: "reasoning_content",
 		requiresReasoningContentForToolCalls:

package/src/discovery/codex.ts

@@ -68,6 +68,7 @@ const codexModelEntrySchema = type({
 	"priority?": "unknown",
 	"prefer_websockets?": "unknown",
 	"use_responses_lite?": "unknown",
+	"tool_mode?": "unknown",
 });
 
 const codexModelsResponseSchema = type({
@@ -282,6 +283,7 @@ interface ParsedCodexModelEntry {
 	input: ("text" | "image")[];
 	preferWebsockets: boolean;
 	useResponsesLite: boolean;
+	toolMode: boolean;
 	priority: number;
 }
 
@@ -310,6 +312,7 @@ function parseCodexModelEntry(entry: unknown): ParsedCodexModelEntry | null {
 		input: normalizeInputModalities(payload.input_modalities),
 		preferWebsockets: toBoolean(payload.prefer_websockets) === true,
 		useResponsesLite: toBoolean(payload.use_responses_lite) === true,
+		toolMode: payload.tool_mode === "code_mode_only",
 		priority: toFiniteNumber(payload.priority) ?? Number.MAX_SAFE_INTEGER,
 	};
 }
@@ -360,6 +363,7 @@ function buildNormalizedCodexModel(
 			maxTokens,
 			...(parsed.preferWebsockets ? { preferWebsockets: true } : {}),
 			...(parsed.useResponsesLite ? { useResponsesLite: true } : {}),
+			...(parsed.toolMode ? { toolMode: "code_mode_only" as const } : {}),
 			...(parsed.priority !== Number.MAX_SAFE_INTEGER ? { priority: parsed.priority } : {}),
 		},
 	};

package/src/discovery/cursor-proto.ts

@@ -31,6 +31,13 @@ export enum DiagnosticSeverity {
 	HINT = 4,
 }
 
+/** Cursor agent enum CursorRuleSource. */
+export enum CursorRuleSource {
+	UNSPECIFIED = 0,
+	TEAM = 1,
+	USER = 2,
+}
+
 /** Cursor agent enum ForceBackgroundShellStatus. */
 export enum ForceBackgroundShellStatus {
 	UNSPECIFIED = 0,

package/src/identity/family.ts

@@ -209,6 +209,16 @@ export const isOpenAIGptOssModelId = memo((modelId: string): boolean => {
 	return /(^|\/)gpt-oss[-:]/i.test(modelId);
 });
 
+/**
+ * Meta Muse Spark ids (`muse-spark-1.1`, `muse-spark-1.2`,
+ * `muse-spark-1.2-contributor`, `meta/muse-spark-1.2`). The Responses
+ * `reasoning.effort` wire accepts `none` (thinking-off) plus
+ * `minimal`/`low`/`medium`/`high`/`xhigh`.
+ */
+export const isMuseSparkModelId = memo((modelId: string): boolean => {
+	return /(^|\/)muse-spark(?:[-.]|$)/i.test(modelId);
+});
+
 /** OpenAI model ids (gpt-*, chatgpt-*, o1/o3/o4 SKUs, codex-*, or openai/*). */
 export const isOpenAIModelId = memo((modelId: string): boolean => {
 	return (

package/src/index.ts

@@ -16,3 +16,4 @@ export * from "./wire/codex";
 export * from "./wire/coreweave";
 export * from "./wire/gemini-headers";
 export * from "./wire/github-copilot";
+export * from "./wire/image-fetchers";

package/src/model-cache.ts

@@ -309,9 +309,9 @@ export function writeModelCache<TApi extends Api>(
 					const staticHeaderSource =
 						staticById.get(model.id) ?? (model.requestModelId ? staticById.get(model.requestModelId) : undefined);
 					// A model with no static source is still restorable when its live
-					// headers equal the provider's trusted constant (a compile-time,
-					// non-credential value the reader can reattach by value). This keeps
-					// reference-less Copilot models (e.g. claude-opus-5) alive offline.
+					// headers equal a trusted provider-wide fallback that the reader can
+					// re-derive without persisting it. This keeps reference-less models
+					// with constant or configured headers alive offline.
 					const matchesStatic = staticHeaderSource
 						? headersEqual(model.headers, staticHeaderSource.headers)
 						: headersEqual(model.headers, restorableHeaderFallback);

package/src/model-manager.ts

@@ -42,11 +42,11 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
 	/** Cached model ids whose presence forces refresh when the static or migration-policy fingerprint changes. */
 	dropCachedModelIdsOnStaticMismatch?: readonly string[];
 	/**
-	 * Trusted, provider-wide request headers (compile-time constants, never
-	 * credentials) that the cache may restore by value for any model whose live
-	 * headers matched them at write time. Lets header-bearing dynamic models
-	 * without a bundled static entry survive offline reads instead of being
-	 * dropped as unrestorable (e.g. GitHub Copilot's User-Agent + API version).
+	 * Trusted, provider-wide request headers that can be safely re-derived at
+	 * cache-read time. The cache never persists their values. Models whose live
+	 * headers matched this record at write time can survive offline reads without
+	 * a bundled static source, including configured discovery providers whose
+	 * bearer header comes from the current local config.
 	 */
 	restorableHeaderFallback?: Record<string, string>;
 	/** Optional dynamic endpoint fetcher. */