@linxiraos/pi-catalog 1.4.6 → 1.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/CHANGELOG.md +6 -2
  2. package/README.md +3 -3
  3. package/dist/types/build.d.ts +12 -4
  4. package/dist/types/compat/auth-ids.d.ts +2 -2
  5. package/dist/types/compat/catalog-policy.d.ts +6 -4
  6. package/dist/types/compat/factory-droid.d.ts +7 -1
  7. package/dist/types/compat/provider-ids.d.ts +1 -1
  8. package/dist/types/compat/resolve.d.ts +1 -1
  9. package/dist/types/compat/revision.d.ts +2 -0
  10. package/dist/types/compat/server-side-fallback.d.ts +6 -4
  11. package/dist/types/compat/types.d.ts +6 -2
  12. package/dist/types/discovery/codex.d.ts +4 -5
  13. package/dist/types/discovery/cursor-proto.d.ts +8 -0
  14. package/dist/types/discovery/openai-compatible.d.ts +6 -0
  15. package/dist/types/model-cache.d.ts +8 -0
  16. package/dist/types/model-catalog-format.d.ts +37 -0
  17. package/dist/types/model-manager.d.ts +11 -1
  18. package/dist/types/model-thinking.d.ts +4 -0
  19. package/dist/types/models.d.ts +22 -3
  20. package/dist/types/pricing.d.ts +66 -6
  21. package/dist/types/provider-models/openai-compat.d.ts +18 -13
  22. package/dist/types/types.d.ts +14 -19
  23. package/dist/types/utils.d.ts +8 -0
  24. package/dist/types/wire/codex.d.ts +1 -1
  25. package/package.json +6 -10
  26. package/src/build.d.ts +12 -4
  27. package/src/build.ts +50 -3
  28. package/src/compat/auth-ids.ts +5 -0
  29. package/src/compat/axes.ts +27 -9
  30. package/src/compat/catalog-policy.d.ts +9 -0
  31. package/src/compat/catalog-policy.ts +14 -10
  32. package/src/compat/collapse.ts +1 -1
  33. package/src/compat/factory-droid.d.ts +7 -1
  34. package/src/compat/factory-droid.ts +9 -1
  35. package/src/compat/provider-ids.d.ts +1 -1
  36. package/src/compat/provider-ids.ts +2 -0
  37. package/src/compat/resolve.d.ts +1 -1
  38. package/src/compat/resolve.ts +4 -5
  39. package/src/compat/revision.d.ts +2 -0
  40. package/src/compat/revision.ts +10 -0
  41. package/src/compat/rules/README.md +14 -12
  42. package/src/compat/rules/auth/_order.kdl +1 -1
  43. package/src/compat/rules/auth/mistral.kdl +4 -0
  44. package/src/compat/rules/auth/modular.kdl +9 -0
  45. package/src/compat/rules/auth/scaleway.kdl +17 -0
  46. package/src/compat/rules/auth/typesafe.kdl +2 -1
  47. package/src/compat/rules/classes/anthropic.kdl +5 -0
  48. package/src/compat/rules/classes/deepseek.kdl +3 -2
  49. package/src/compat/rules/classes/gemini.kdl +1 -1
  50. package/src/compat/rules/classes/openai.kdl +2 -2
  51. package/src/compat/rules/classes/xai.kdl +1 -1
  52. package/src/compat/rules/providers/anthropic.kdl +8 -4
  53. package/src/compat/rules/providers/cursor.kdl +10 -0
  54. package/src/compat/rules/providers/deepseek.kdl +2 -2
  55. package/src/compat/rules/providers/factory-droid.kdl +243 -13
  56. package/src/compat/rules/providers/google-vertex.kdl +3 -0
  57. package/src/compat/rules/providers/kimi-code.kdl +6 -0
  58. package/src/compat/rules/providers/mistral.kdl +8 -0
  59. package/src/compat/rules/providers/modular.kdl +35 -0
  60. package/src/compat/rules/providers/openai-codex.kdl +1 -1
  61. package/src/compat/rules/providers/sambanova.kdl +2 -0
  62. package/src/compat/rules/providers/scaleway.kdl +179 -0
  63. package/src/compat/rules/runtime/behavior.kdl +22 -6
  64. package/src/compat/rules.json +1 -1
  65. package/src/compat/server-side-fallback.d.ts +9 -0
  66. package/src/compat/server-side-fallback.ts +7 -5
  67. package/src/compat/types.d.ts +6 -2
  68. package/src/compat/types.ts +6 -2
  69. package/src/discovery/codex.d.ts +4 -5
  70. package/src/discovery/codex.ts +7 -15
  71. package/src/discovery/cursor-proto.d.ts +8 -0
  72. package/src/discovery/cursor-proto.ts +12 -1
  73. package/src/discovery/factory-droid.ts +35 -11
  74. package/src/discovery/openai-compatible.d.ts +6 -0
  75. package/src/discovery/openai-compatible.ts +1 -1
  76. package/src/model-cache.d.ts +8 -0
  77. package/src/model-cache.ts +83 -61
  78. package/src/model-catalog-format.d.ts +37 -0
  79. package/src/model-catalog-format.ts +296 -0
  80. package/src/model-manager.d.ts +11 -1
  81. package/src/model-manager.ts +85 -143
  82. package/src/model-thinking.d.ts +4 -0
  83. package/src/model-thinking.ts +10 -0
  84. package/src/model-tokenizer.ts +13 -12
  85. package/src/models.d.ts +22 -3
  86. package/src/models.json +1 -1
  87. package/src/models.ts +48 -11
  88. package/src/pricing.d.ts +66 -6
  89. package/src/pricing.ts +59 -94
  90. package/src/provider-models/cache-provider-id.ts +23 -6
  91. package/src/provider-models/catalog-snapshot.json.zst +0 -0
  92. package/src/provider-models/catalog-snapshot.json.zst.d.ts +3 -0
  93. package/src/provider-models/descriptors.ts +2 -0
  94. package/src/provider-models/openai-compat.d.ts +18 -13
  95. package/src/provider-models/openai-compat.ts +203 -94
  96. package/src/provider-models/special.ts +5 -6
  97. package/src/types.d.ts +14 -19
  98. package/src/types.ts +11 -18
  99. package/src/utils.d.ts +8 -0
  100. package/src/utils.ts +18 -0
  101. package/src/wire/codex.d.ts +1 -1
  102. package/src/wire/codex.ts +1 -1
  103. package/src/wire/factory-droid.ts +4 -3
  104. package/src/models.json.d.ts +0 -9
@@ -0,0 +1,9 @@
1
+ import type { CatalogPolicyInputs } from "../types";
2
+ import type { ResolveRoute } from "./resolve";
3
+ /**
4
+ * Ordered model ids for Anthropic's server-side refusal `fallbacks` chain,
5
+ * authored on the `server-side-fallback-models` catalog axis, on `route`'s
6
+ * upstream when it names one. Empty when no rule assigns a chain (the model,
7
+ * host or upstream does not support the feature).
8
+ */
9
+ export declare function serverSideFallbackModels(model: CatalogPolicyInputs, route?: ResolveRoute): readonly string[];
@@ -1,13 +1,15 @@
1
- import type { Model } from "../types";
1
+ import type { CatalogPolicyInputs } from "../types";
2
2
  import { resolveCatalogPolicy } from "./catalog-policy";
3
+ import type { ResolveRoute } from "./resolve";
3
4
 
4
5
  /**
5
6
  * Ordered model ids for Anthropic's server-side refusal `fallbacks` chain,
6
- * authored on the `server-side-fallback-models` catalog axis. Empty when no
7
- * rule assigns a chain (the model or host does not support the feature).
7
+ * authored on the `server-side-fallback-models` catalog axis, on `route`'s
8
+ * upstream when it names one. Empty when no rule assigns a chain (the model,
9
+ * host or upstream does not support the feature).
8
10
  */
9
- export function serverSideFallbackModels(model: Model): readonly string[] {
10
- const value = resolveCatalogPolicy(model).serverSideFallbackModels;
11
+ export function serverSideFallbackModels(model: CatalogPolicyInputs, route?: ResolveRoute): readonly string[] {
12
+ const value = resolveCatalogPolicy(model, route).serverSideFallbackModels;
11
13
  if (!Array.isArray(value)) return [];
12
14
  return value.filter((entry): entry is string => typeof entry === "string");
13
15
  }
@@ -369,8 +369,10 @@ export type CompiledAuthValidation = {
369
369
  kind: "models-endpoint";
370
370
  label?: string;
371
371
  url: string;
372
- /** Env var holding an alternate base URL; `/models` is appended to it. */
372
+ /** Env var holding an alternate base URL; `baseUrlPath` is appended to it. */
373
373
  baseUrlEnv?: string;
374
+ /** Path appended to the `baseUrlEnv` value (default `/models`), for bases that exclude the API version. */
375
+ baseUrlPath?: string;
374
376
  /** Hook returning extra request headers (may throw a configuration error). */
375
377
  headersHook?: string;
376
378
  optional?: boolean;
@@ -712,6 +714,8 @@ export interface ResolvedAxes {
712
714
  export interface RequestPolicy {
713
715
  completionsReasoningMode?: "none" | "effort" | "opt-in" | "forced-on";
714
716
  completionsReasoningHistory?: "omit" | "preserved" | "interleaved";
717
+ /** Send `allow_missing_thinking` with the effort so tool-call turns may arrive without reasoning. */
718
+ completionsAllowMissingThinking?: boolean;
715
719
  anthropicThinking?: "adaptive" | "adaptive-summarized" | "budget-interleaved" | "budget-effort";
716
720
  /** Advertise `fine-grained-tool-streaming-2025-05-14` on requests that carry tools. */
717
721
  anthropicToolStreamingBeta?: boolean;
@@ -719,7 +723,7 @@ export interface RequestPolicy {
719
723
  openaiPlatformHeader?: string;
720
724
  responsesCacheRetention?: boolean;
721
725
  responsesVerbosity?: "low";
722
- responsesServiceTier?: "priority";
726
+ responsesServiceTier?: "priority" | "ultrafast";
723
727
  responsesParallelToolCalls?: boolean;
724
728
  responsesSafetyIdentifier?: boolean;
725
729
  /** Default `tool_choice` to `auto` when the request carries tools and the caller picks none. */
@@ -398,8 +398,10 @@ export type CompiledAuthValidation =
398
398
  kind: "models-endpoint";
399
399
  label?: string;
400
400
  url: string;
401
- /** Env var holding an alternate base URL; `/models` is appended to it. */
401
+ /** Env var holding an alternate base URL; `baseUrlPath` is appended to it. */
402
402
  baseUrlEnv?: string;
403
+ /** Path appended to the `baseUrlEnv` value (default `/models`), for bases that exclude the API version. */
404
+ baseUrlPath?: string;
403
405
  /** Hook returning extra request headers (may throw a configuration error). */
404
406
  headersHook?: string;
405
407
  optional?: boolean;
@@ -751,6 +753,8 @@ export interface ResolvedAxes {
751
753
  export interface RequestPolicy {
752
754
  completionsReasoningMode?: "none" | "effort" | "opt-in" | "forced-on";
753
755
  completionsReasoningHistory?: "omit" | "preserved" | "interleaved";
756
+ /** Send `allow_missing_thinking` with the effort so tool-call turns may arrive without reasoning. */
757
+ completionsAllowMissingThinking?: boolean;
754
758
  anthropicThinking?: "adaptive" | "adaptive-summarized" | "budget-interleaved" | "budget-effort";
755
759
  /** Advertise `fine-grained-tool-streaming-2025-05-14` on requests that carry tools. */
756
760
  anthropicToolStreamingBeta?: boolean;
@@ -758,7 +762,7 @@ export interface RequestPolicy {
758
762
  openaiPlatformHeader?: string;
759
763
  responsesCacheRetention?: boolean;
760
764
  responsesVerbosity?: "low";
761
- responsesServiceTier?: "priority";
765
+ responsesServiceTier?: "priority" | "ultrafast";
762
766
  responsesParallelToolCalls?: boolean;
763
767
  responsesSafetyIdentifier?: boolean;
764
768
  /** Default `tool_choice` to `auto` when the request carries tools and the caller picks none. */
@@ -27,12 +27,11 @@ export interface CodexModelDiscoveryResult {
27
27
  models: ModelSpec<"openai-codex-responses">[];
28
28
  etag?: string;
29
29
  /**
30
- * Set when the backend rejected the credential itself (401/403, e.g.
31
- * `token_revoked`); `models` is empty. A definitive per-account denial,
32
- * unlike the `null` result for transport/parse failures, so multi-account
33
- * discovery can skip the account instead of aborting.
30
+ * A definitive per-account denial (401/403 auth, 402 payment). `models` is
31
+ * empty; unlike transport/parse failures, sibling accounts can still supply
32
+ * an authoritative catalog.
34
33
  */
35
- rejectedStatus?: 401 | 403;
34
+ rejectedStatus?: 401 | 402 | 403;
36
35
  }
37
36
  /**
38
37
  * Fetches model metadata from Codex backend and normalizes it for pi model management.
@@ -3,7 +3,7 @@ import { compareRevision, parseRevision } from "../compat/revision";
3
3
  import { classifyModel } from "../compat/taxonomy";
4
4
  import { getBundledModels } from "../models";
5
5
  import type { FetchImpl, ModelSpec } from "../types";
6
- import { discoveryFetch } from "../utils";
6
+ import { discoveryFetch, parseServiceTierIds } from "../utils";
7
7
  import { CODEX_BASE_URL, CODEX_CLIENT_VERSION, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "../wire/codex";
8
8
 
9
9
  const DEFAULT_MODEL_LIST_PATHS = ["/codex/models", "/models"] as const;
@@ -113,12 +113,11 @@ export interface CodexModelDiscoveryResult {
113
113
  models: ModelSpec<"openai-codex-responses">[];
114
114
  etag?: string;
115
115
  /**
116
- * Set when the backend rejected the credential itself (401/403, e.g.
117
- * `token_revoked`); `models` is empty. A definitive per-account denial,
118
- * unlike the `null` result for transport/parse failures, so multi-account
119
- * discovery can skip the account instead of aborting.
116
+ * A definitive per-account denial (401/403 auth, 402 payment). `models` is
117
+ * empty; unlike transport/parse failures, sibling accounts can still supply
118
+ * an authoritative catalog.
120
119
  */
121
- rejectedStatus?: 401 | 403;
120
+ rejectedStatus?: 401 | 402 | 403;
122
121
  }
123
122
 
124
123
  /**
@@ -148,7 +147,7 @@ export async function fetchCodexModels(options: CodexModelDiscoveryOptions): Pro
148
147
  continue;
149
148
  }
150
149
 
151
- if (response.status === 401 || response.status === 403) {
150
+ if (response.status === 401 || response.status === 402 || response.status === 403) {
152
151
  return { models: [], rejectedStatus: response.status };
153
152
  }
154
153
  if (!response.ok) {
@@ -335,14 +334,7 @@ function parseCodexModelEntry(entry: unknown): ParsedCodexModelEntry | null {
335
334
 
336
335
  // codex-rs `ModelServiceTier { id, name, description }`; only the id reaches the wire.
337
336
  // An explicit empty array is kept: it means the model offers no optional tier.
338
- let serviceTiers: string[] | undefined;
339
- if (Array.isArray(payload.service_tiers)) {
340
- serviceTiers = [];
341
- for (const tier of payload.service_tiers) {
342
- const id = tier !== null && typeof tier === "object" && "id" in tier ? toNonEmptyString(tier.id) : null;
343
- if (id && !serviceTiers.includes(id)) serviceTiers.push(id);
344
- }
345
- }
337
+ const serviceTiers = parseServiceTierIds(payload.service_tiers);
346
338
 
347
339
  return {
348
340
  slug,
@@ -2514,6 +2514,9 @@ export interface InteractionUpdate extends ProtoMessage {
2514
2514
  } | {
2515
2515
  case: "stepCompleted";
2516
2516
  value: StepCompletedUpdate;
2517
+ } | {
2518
+ case: "toolRequestsListed";
2519
+ value: ToolRequestsListedUpdate;
2517
2520
  };
2518
2521
  }
2519
2522
  export declare const InteractionUpdateSchema: MessageCodec<InteractionUpdate>;
@@ -5318,6 +5321,11 @@ export interface ToolCallStartedUpdate extends ProtoMessage {
5318
5321
  modelCallId: string;
5319
5322
  }
5320
5323
  export declare const ToolCallStartedUpdateSchema: MessageCodec<ToolCallStartedUpdate>;
5324
+ /** Cursor agent message agent.v1.ToolRequestsListedUpdate. */
5325
+ export interface ToolRequestsListedUpdate extends ProtoMessage {
5326
+ callCount: number;
5327
+ }
5328
+ export declare const ToolRequestsListedUpdateSchema: MessageCodec<ToolRequestsListedUpdate>;
5321
5329
  /** Cursor agent message agent.v1.TruncatedToolCall. */
5322
5330
  export interface TruncatedToolCall extends ProtoMessage {
5323
5331
  originalStepBlobId: Uint8Array;
@@ -3662,7 +3662,8 @@ export interface InteractionUpdate extends ProtoMessage {
3662
3662
  | { case: "heartbeat"; value: HeartbeatUpdate }
3663
3663
  | { case: "turnEnded"; value: TurnEndedUpdate }
3664
3664
  | { case: "stepStarted"; value: StepStartedUpdate }
3665
- | { case: "stepCompleted"; value: StepCompletedUpdate };
3665
+ | { case: "stepCompleted"; value: StepCompletedUpdate }
3666
+ | { case: "toolRequestsListed"; value: ToolRequestsListedUpdate };
3666
3667
  }
3667
3668
 
3668
3669
  export const InteractionUpdateSchema: MessageCodec<InteractionUpdate> = pb<InteractionUpdate>("agent.v1.InteractionUpdate", [
@@ -3687,6 +3688,7 @@ export const InteractionUpdateSchema: MessageCodec<InteractionUpdate> = pb<Inter
3687
3688
  { no: 14, name: "turnEnded", kind: "message", T: () => TurnEndedUpdateSchema },
3688
3689
  { no: 16, name: "stepStarted", kind: "message", T: () => StepStartedUpdateSchema },
3689
3690
  { no: 17, name: "stepCompleted", kind: "message", T: () => StepCompletedUpdateSchema },
3691
+ { no: 27, name: "toolRequestsListed", kind: "message", T: () => ToolRequestsListedUpdateSchema },
3690
3692
  ],
3691
3693
  },
3692
3694
  ]);
@@ -8251,6 +8253,15 @@ export const ToolCallStartedUpdateSchema: MessageCodec<ToolCallStartedUpdate> =
8251
8253
  { no: 3, name: "modelCallId", kind: "string" },
8252
8254
  ]);
8253
8255
 
8256
+ /** Cursor agent message agent.v1.ToolRequestsListedUpdate. */
8257
+ export interface ToolRequestsListedUpdate extends ProtoMessage {
8258
+ callCount: number;
8259
+ }
8260
+
8261
+ export const ToolRequestsListedUpdateSchema: MessageCodec<ToolRequestsListedUpdate> = pb<ToolRequestsListedUpdate>("agent.v1.ToolRequestsListedUpdate", [
8262
+ { no: 1, name: "callCount", kind: "uint32" },
8263
+ ]);
8264
+
8254
8265
  /** Cursor agent message agent.v1.TruncatedToolCall. */
8255
8266
  export interface TruncatedToolCall extends ProtoMessage {
8256
8267
  originalStepBlobId: Uint8Array;
@@ -6,6 +6,7 @@ import {
6
6
  resolveFactoryDroidRotation,
7
7
  } from "../compat/factory-droid";
8
8
  import { hasModelScopedEffortLadder, resolveModelPolicy } from "../compat/resolve";
9
+ import { serverSideFallbackModels } from "../compat/server-side-fallback";
9
10
  import type { RequestPolicy } from "../compat/types";
10
11
  import { getBundledModel, isGeneratedProvider } from "../models";
11
12
  import type { FetchImpl, ModelSpec, ThinkingConfig, ThinkingControlMode } from "../types";
@@ -166,16 +167,35 @@ export interface FactoryDroidModelDiscoveryOptions extends AccountScope {
166
167
  */
167
168
  export function factoryDroidSeedModels(scope: AccountScope): ModelSpec<"factory-droid-agent">[] {
168
169
  const inferenceRegion = resolveFactoryDroidInferenceRegion(scope);
169
- return factoryDroidRegistry()
170
- .filter(model => isModelAvailable(model, {}, null, inferenceRegion, null))
171
- .map(model =>
172
- buildFactoryDroidModel(model, {
173
- region: scope.region,
174
- inferenceRegion,
175
- orgId: scope.orgId,
176
- apiProviders: resolveFactoryDroidRotation(model.policy, inferenceRegion),
177
- }),
178
- );
170
+ return withAvailableRefusalFallbacks(
171
+ factoryDroidRegistry()
172
+ .filter(model => isModelAvailable(model, {}, null, inferenceRegion, null))
173
+ .map(model =>
174
+ buildFactoryDroidModel(model, {
175
+ region: scope.region,
176
+ inferenceRegion,
177
+ orgId: scope.orgId,
178
+ apiProviders: resolveFactoryDroidRotation(model.policy, inferenceRegion),
179
+ }),
180
+ ),
181
+ );
182
+ }
183
+
184
+ /**
185
+ * Native offers a server-side refusal fallback only when the account can run
186
+ * that model, so each model keeps the fallbacks its upstreams name that are
187
+ * themselves in the account's roster.
188
+ */
189
+ function withAvailableRefusalFallbacks(models: ModelSpec<"factory-droid-agent">[]): ModelSpec<"factory-droid-agent">[] {
190
+ const available = new Set(models.map(model => model.id));
191
+ for (const model of models) {
192
+ const named = new Set<string>();
193
+ for (const upstream of model.factoryDroidApiProviders ?? []) {
194
+ for (const id of serverSideFallbackModels(model, { upstream })) named.add(id);
195
+ }
196
+ if (named.size > 0) model.factoryDroidRefusalFallbacks = [...named].filter(id => available.has(id));
197
+ }
198
+ return models;
179
199
  }
180
200
 
181
201
  /**
@@ -219,7 +239,7 @@ export async function fetchFactoryDroidModels(
219
239
  } catch {
220
240
  return null;
221
241
  }
222
- return factoryDroidRegistry().flatMap(model => {
242
+ const models = factoryDroidRegistry().flatMap(model => {
223
243
  if (!isModelAvailable(model, flags, policy, servingRegion, images)) return [];
224
244
  const { id } = model.spec;
225
245
  const family = model.policy.routingFamily;
@@ -236,6 +256,7 @@ export async function fetchFactoryDroidModels(
236
256
  if (routed !== undefined) spec.factoryDroidRoutingSource = "configured_order";
237
257
  return [spec];
238
258
  });
259
+ return withAvailableRefusalFallbacks(models);
239
260
  }
240
261
 
241
262
  /**
@@ -282,6 +303,9 @@ export function buildFactoryDroidModel(
282
303
  ...factoryDroidRegionalLimits(policy, resolveFactoryDroidInferenceRegion(options)),
283
304
  ...(options.orgId ? { factoryDroidOrgId: options.orgId } : {}),
284
305
  ...(policy.creditRates ? { factoryDroidCredits: policy.creditRates.input } : {}),
306
+ ...(policy.creditRates?.effectiveRates
307
+ ? { factoryDroidCreditCards: policy.creditRates.effectiveRates.map(card => ({ ...card })) }
308
+ : {}),
285
309
  ...(options.apiProviders?.length ? { factoryDroidApiProviders: [...options.apiProviders] } : {}),
286
310
  };
287
311
  const resolved = resolveModelPolicy(model);
@@ -10,6 +10,12 @@ import type { Api, FetchImpl, ModelSpec, Provider } from "../types";
10
10
  * (issue #8315). 10s matches the coding-agent's remote-discovery budget.
11
11
  */
12
12
  export declare const DEFAULT_OPENAI_COMPATIBLE_DISCOVERY_TIMEOUT_MS = 10000;
13
+ /**
14
+ * Uses a cancellable timer rather than the native abort-timeout helper so
15
+ * successful fast discovery requests do not leave armed timeout signals for
16
+ * concurrent GC to trip over later.
17
+ */
18
+ export declare function withOpenAICompatibleDiscoveryTimeout<T>(timeoutMs: number, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
13
19
  /**
14
20
  * Minimal OpenAI-style model entry shape consumed by discovery.
15
21
  *
@@ -21,7 +21,7 @@ export const DEFAULT_OPENAI_COMPATIBLE_DISCOVERY_TIMEOUT_MS = 10_000;
21
21
  * successful fast discovery requests do not leave armed timeout signals for
22
22
  * concurrent GC to trip over later.
23
23
  */
24
- async function withOpenAICompatibleDiscoveryTimeout<T>(
24
+ export async function withOpenAICompatibleDiscoveryTimeout<T>(
25
25
  timeoutMs: number,
26
26
  run: (signal: AbortSignal) => Promise<T>,
27
27
  ): Promise<T> {
@@ -48,6 +48,14 @@ export interface CacheEntry<TApi extends Api = Api> {
48
48
  * cache was opened under — Windows cannot remove a database that is still open.
49
49
  */
50
50
  export declare function closeModelCache(): void;
51
+ /**
52
+ * Keeps one connection to a non-default cache path open until the returned
53
+ * handle is disposed. The default `models.db` already shares a long-lived
54
+ * connection; other paths otherwise open, initialize and close the database on
55
+ * every read and write, which a refresh pass repeats once per provider.
56
+ * Retains nest: the connection closes when the last one is disposed.
57
+ */
58
+ export declare function retainModelCacheConnection(dbPath: string | undefined): Disposable;
51
59
  export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
52
60
  /**
53
61
  * Persist a provider snapshot.
@@ -4,15 +4,17 @@
4
4
  */
5
5
  import type { Database } from "bun:sqlite";
6
6
  import * as path from "node:path";
7
+ import { type } from "@linxiraos/pi-omptype";
7
8
  import { getModelDbPath, isSqliteCorruptionError, logger, openSqliteDatabaseSync, VERSION } from "@linxiraos/pi-utils";
8
9
  import RULES from "./compat/rules.json" with { type: "json" };
9
10
  import type { Api, Model } from "./types";
10
11
 
11
12
  // Rows persist fully materialized Models so compatible warm-cache reads do not
12
13
  // rerun the compat cascade. Request headers are intentionally omitted:
13
- // arbitrary provider-defined header names can carry credentials. v14
14
- // invalidates Antigravity rows predating per-SKU `antigravityWireProfiles`
15
- // (model_enum label, output cap, SKU thinking). v13 replaces
14
+ // arbitrary provider-defined header names can carry credentials. v15
15
+ // invalidates unbundled OpenAI-compatible rows that ignored provider-reported
16
+ // token limits. v14 invalidates Antigravity rows predating per-SKU
17
+ // `antigravityWireProfiles` (model_enum label, output cap, SKU thinking). v13 replaces
16
18
  // sparse ModelSpec rows with materialized rows and records the exact app/rules/
17
19
  // builder policy that produced them. v12 invalidated Kimi Code rows carrying the blanket
18
20
  // maxTokens: 32000 that predate per-family output caps (k3/k3-256k -> 131072,
@@ -27,7 +29,7 @@ import type { Api, Model } from "./types";
27
29
  // retired unknown-limit sentinels (222222/8888); v5 invalidated rows predating
28
30
  // effort-tier variant collapsing (raw `-low`/`-high`/`-thinking` member ids);
29
31
  // v4 dropped the pre-efforts ThinkingConfig shape.
30
- const CACHE_SCHEMA_VERSION = 14;
32
+ const CACHE_SCHEMA_VERSION = 15;
31
33
  /** Oldest schema whose rows are guaranteed never to carry request headers. */
32
34
  const FIRST_HEADERLESS_SCHEMA_VERSION = 11;
33
35
  const HEADER_RESTORE_VERSION = 1;
@@ -173,6 +175,14 @@ export interface CacheEntry<TApi extends Api = Api> {
173
175
  let sharedDb: Database | null = null;
174
176
  let sharedDbPath: string | null = null;
175
177
 
178
+ /** Connection to a non-default cache path, held open while any retain is outstanding. */
179
+ interface PinnedDb {
180
+ db: Database | null;
181
+ refs: number;
182
+ }
183
+
184
+ const pinnedDbs = new Map<string, PinnedDb>();
185
+
176
186
  interface ReadRowCacheEntry {
177
187
  /** `PRAGMA data_version` of the shared connection when validated; null for per-call connections. */
178
188
  dataVersion: number | null;
@@ -286,16 +296,54 @@ export function closeModelCache(): void {
286
296
  closeSharedDb();
287
297
  }
288
298
 
299
+ /**
300
+ * Keeps one connection to a non-default cache path open until the returned
301
+ * handle is disposed. The default `models.db` already shares a long-lived
302
+ * connection; other paths otherwise open, initialize and close the database on
303
+ * every read and write, which a refresh pass repeats once per provider.
304
+ * Retains nest: the connection closes when the last one is disposed.
305
+ */
306
+ export function retainModelCacheConnection(dbPath: string | undefined): Disposable {
307
+ const { resolvedPath, shared } = resolveCacheDb(dbPath);
308
+ if (shared) return { [Symbol.dispose]() {} };
309
+ let pin = pinnedDbs.get(resolvedPath);
310
+ if (!pin) {
311
+ pin = { db: null, refs: 0 };
312
+ pinnedDbs.set(resolvedPath, pin);
313
+ }
314
+ pin.refs++;
315
+ const held = pin;
316
+ let released = false;
317
+ return {
318
+ [Symbol.dispose]() {
319
+ if (released) return;
320
+ released = true;
321
+ held.refs--;
322
+ if (held.refs > 0) return;
323
+ pinnedDbs.delete(resolvedPath);
324
+ held.db?.close();
325
+ held.db = null;
326
+ },
327
+ };
328
+ }
329
+
289
330
  function runModelCacheDb<T>(resolvedPath: string, shared: boolean, useDb: (db: Database) => T): T {
290
331
  if (shared && sharedDb && sharedDbPath !== resolvedPath) closeSharedDb();
291
- if (shared && sharedDb) {
332
+ const pin = shared ? undefined : pinnedDbs.get(resolvedPath);
333
+ const heldDb = shared ? sharedDb : pin?.db;
334
+ if (heldDb) {
292
335
  try {
293
- return useDb(sharedDb);
336
+ return useDb(heldDb);
294
337
  } catch (error) {
295
338
  if (!isSqliteCorruptionError(error)) throw error;
296
339
  // The opener owns recovery for new handles. Drop this stale handle
297
340
  // first so its WAL cannot remain attached to the replacement.
298
- closeSharedDb();
341
+ if (pin) {
342
+ heldDb.close();
343
+ pin.db = null;
344
+ } else {
345
+ closeSharedDb();
346
+ }
299
347
  invalidateReadPath(resolvedPath);
300
348
  return runModelCacheDb(resolvedPath, shared, useDb);
301
349
  }
@@ -309,6 +357,8 @@ function runModelCacheDb<T>(resolvedPath: string, shared: boolean, useDb: (db: D
309
357
  if (shared) {
310
358
  sharedDb = db;
311
359
  sharedDbPath = resolvedPath;
360
+ } else if (pin) {
361
+ pin.db = db;
312
362
  } else {
313
363
  db.close();
314
364
  }
@@ -396,61 +446,33 @@ function migrateCacheSchema(db: Database): void {
396
446
  }
397
447
  }
398
448
 
449
+ /**
450
+ * A cacheable materialized model. Also checked on the write side against
451
+ * in-memory models, so optional keys may be present as `undefined`.
452
+ */
453
+ const MaterializedModel = type({
454
+ id: "string > 0",
455
+ name: "string > 0",
456
+ api: "string > 0",
457
+ provider: "string > 0",
458
+ // Empty is legitimate: Azure-style providers resolve the endpoint from
459
+ // configuration at request time, and their bundled rows carry "".
460
+ baseUrl: "string",
461
+ reasoning: "boolean",
462
+ input: "('text' | 'image')[] > 0",
463
+ "headers?": "undefined",
464
+ supportsComputerUseConfig: "boolean | null",
465
+ contextWindow: "number > 0 | null",
466
+ maxTokens: "number > 0 | null",
467
+ identity: { class: "string" },
468
+ "compat?": type("object")
469
+ .narrow(compat => !Array.isArray(compat))
470
+ .or("undefined"),
471
+ cost: { input: "number", output: "number", cacheRead: "number", cacheWrite: "number" },
472
+ });
473
+
399
474
  function isMaterializedModel(value: unknown): value is PersistedModel<Api> {
400
- if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
401
- const model = value as Partial<PersistedModel<Api>>;
402
- if (
403
- typeof model.id !== "string" ||
404
- model.id.length === 0 ||
405
- typeof model.name !== "string" ||
406
- model.name.length === 0 ||
407
- typeof model.api !== "string" ||
408
- model.api.length === 0 ||
409
- typeof model.provider !== "string" ||
410
- model.provider.length === 0 ||
411
- // Empty is legitimate: Azure-style providers resolve the endpoint from
412
- // configuration at request time, and their bundled rows carry "".
413
- typeof model.baseUrl !== "string" ||
414
- typeof model.reasoning !== "boolean" ||
415
- !Array.isArray(model.input) ||
416
- model.input.length === 0 ||
417
- model.input.some(input => input !== "text" && input !== "image") ||
418
- model.headers !== undefined ||
419
- !Object.hasOwn(model, "supportsComputerUseConfig") ||
420
- (model.supportsComputerUseConfig !== null && typeof model.supportsComputerUseConfig !== "boolean")
421
- ) {
422
- return false;
423
- }
424
- const contextWindow = model.contextWindow;
425
- const maxTokens = model.maxTokens;
426
- if (
427
- (contextWindow !== null &&
428
- (typeof contextWindow !== "number" || !Number.isFinite(contextWindow) || contextWindow <= 0)) ||
429
- (maxTokens !== null && (typeof maxTokens !== "number" || !Number.isFinite(maxTokens) || maxTokens <= 0))
430
- ) {
431
- return false;
432
- }
433
- if (
434
- model.identity === null ||
435
- typeof model.identity !== "object" ||
436
- typeof model.identity.class !== "string" ||
437
- (model.compat !== undefined &&
438
- (model.compat === null || typeof model.compat !== "object" || Array.isArray(model.compat)))
439
- ) {
440
- return false;
441
- }
442
- if (model.cost === null || typeof model.cost !== "object") return false;
443
- const cost = model.cost as Partial<Model<Api>["cost"]>;
444
- return (
445
- typeof cost.input === "number" &&
446
- Number.isFinite(cost.input) &&
447
- typeof cost.output === "number" &&
448
- Number.isFinite(cost.output) &&
449
- typeof cost.cacheRead === "number" &&
450
- Number.isFinite(cost.cacheRead) &&
451
- typeof cost.cacheWrite === "number" &&
452
- Number.isFinite(cost.cacheWrite)
453
- );
475
+ return MaterializedModel.allows(value);
454
476
  }
455
477
 
456
478
  function parseMaterializedModels<TApi extends Api>(serialized: string): Model<TApi>[] | null {
@@ -0,0 +1,37 @@
1
+ import type { Api, Model } from "./types";
2
+ type EncodedValue = string | number | boolean | null | [number];
3
+ type ObjectNode = [0, EncodedValue[], number, number[]];
4
+ type ArrayNode = [1, EncodedValue[]];
5
+ type Node = ObjectNode | ArrayNode;
6
+ type CompatDelta = [number[], EncodedValue];
7
+ type ModelRow = [string, EncodedValue, CompatDelta?];
8
+ type ProviderRow = [string, EncodedValue, ModelRow[]];
9
+ interface CatalogData {
10
+ version: 1;
11
+ keys: string[];
12
+ booleanShapes: number[][];
13
+ nodes: Node[];
14
+ compat: [string, EncodedValue][];
15
+ providers: ProviderRow[];
16
+ }
17
+ /**
18
+ * Parsed compact catalog. Decoded nested objects and arrays can be shared by
19
+ * multiple models; callers must treat those values as immutable.
20
+ */
21
+ export interface ModelCatalog {
22
+ readonly data: CatalogData;
23
+ readonly values: unknown[];
24
+ readonly decoded: boolean[];
25
+ readonly providers: Map<string, Record<string, Model<Api>>>;
26
+ readonly compatBases: Map<string, EncodedValue>;
27
+ readonly compatValues: Map<string, Map<number, Map<string, Record<string, unknown>>>>;
28
+ }
29
+ /** Encode a model catalog into a deterministic, compact JSON representation. */
30
+ export declare function encodeModelCatalog(models: Record<string, Record<string, Model<Api>>>): string;
31
+ /** Open a parsed catalog without materializing its provider models. */
32
+ export declare function openModelCatalog(value: unknown): ModelCatalog;
33
+ /** List catalog provider keys in deterministic order. */
34
+ export declare function getCatalogProviders(catalog: ModelCatalog): string[];
35
+ /** Materialize and cache one provider, or return undefined if it is absent. */
36
+ export declare function getCatalogProvider(catalog: ModelCatalog, provider: string): Record<string, Model<Api>> | undefined;
37
+ export {};