sidekick-shared 0.28.3 → 0.29.1

package/dist/modelContext.js

@@ -42,6 +42,7 @@ exports._getModelContextIds = _getModelContextIds;
 exports.resolveModelContextWindow = resolveModelContextWindow;
 exports.getModelContextWindowSize = getModelContextWindowSize;
 const modelAliases_1 = require("./modelAliases");
+const ownKey_1 = require("./ownKey");
 /** Known model context window sizes (in tokens); current models verified 2026-09-05. */
 const MODEL_CONTEXT_SIZES = {
     // Published API limits verified 2026-10-30; GLM's API documents 1M even
@@ -158,7 +159,7 @@ function normalizeOverrides(overrides) {
     for (const [key, value] of Object.entries(overrides)) {
         if (!Number.isFinite(value) || value <= 0)
             continue;
-        out[key.trim().toLowerCase()] = value;
+        (0, ownKey_1.setOwnValue)(out, key.trim().toLowerCase(), value);
     }
     return out;
 }
@@ -222,7 +223,7 @@ function _getModelContextIds() {
 // ── Lookup ──
 /** Exact match against one table. */
 function exactWindow(table, modelId) {
-    const hit = table[modelId];
+    const hit = (0, ownKey_1.ownValue)(table, modelId);
     return hit === undefined ? null : hit;
 }
 function exactWindowMatch(table, modelId) {
@@ -270,7 +271,7 @@ function resolveModelContextWindow(modelId) {
     // Imported resolutions rank below local observed data: a window this realm
     // saw first-hand is fresher than a snapshot transferred from another realm.
     if (!observedExact) {
-        const imported = importedTable[stripped] ?? importedTable[canonicalModelId];
+        const imported = (0, ownKey_1.ownValue)(importedTable, stripped) ?? (0, ownKey_1.ownValue)(importedTable, canonicalModelId);
         if (imported) {
             return { ...imported, modelId: rawModelId, canonicalModelId };
         }

package/dist/modelInfo.d.ts

@@ -14,11 +14,18 @@
  *   baseline without requiring a redeploy when vendor prices change.
  * - Longest-prefix matching handles variants like `claude-opus-4.5-20250514`
  *   against a key like `claude-opus-4.5`. Same pattern used in modelContext.ts.
+ * - A consumer layer (`registerModelPricing`) sits beside the catalog and
+ *   imported layers and survives their resets.
+ * - Every table-derived value is computed lazily, so a tree-shaken bundle that
+ *   only uses the parsing/display helpers does not retain the pricing table.
  *
  * @module modelInfo
  */
 import type { ModelProviderId } from './providerIds';
+import type { PricingProvenance } from './usageNormalization';
 export { MODEL_PROVIDER_IDS } from './providerIds';
+export { formatCost } from './formatting';
+export type { FormatCostOptions } from './formatting';
 /** Pricing information for a model. All costs are per million tokens in USD. */
 export interface ModelPricing {
     inputCostPerMillion: number;
@@ -26,7 +33,18 @@ export interface ModelPricing {
     cacheWriteCostPerMillion: number;
     cacheReadCostPerMillion: number;
 }
-export type ModelPricingSource = 'imported' | 'catalog' | 'static' | 'none';
+/**
+ * Which layer answered a pricing lookup.
+ *
+ * - `registered` — an entry supplied through `registerModelPricing` (consumer
+ *   configuration such as negotiated prices). Always an exact match.
+ * - `imported` — an exact resolution imported from another realm via
+ *   `importResolvedModelCatalog`.
+ * - `catalog` — the runtime LiteLLM catalog (`hydratePricingCatalog`).
+ * - `static` — the offline baseline shipped with this package.
+ * - `none` — unpriced.
+ */
+export type ModelPricingSource = 'registered' | 'imported' | 'catalog' | 'static' | 'none';
 export type ModelPricingMatch = 'exact' | 'prefix' | 'none';
 export interface ModelPricingProvenance {
     source: ModelPricingSource;
@@ -37,10 +55,75 @@ export interface ModelPricingProvenance {
 }
 export interface ResolvedModelPricing {
     modelId: string;
+    /**
+     * The looked-up id trimmed, lowercased, without `[1m]`, and resolved through
+     * registered aliases. Deployment prefixes and date suffixes are kept, so
+     * this is not the same value as `canonicalModelId(modelId)`.
+     */
     canonicalModelId: string;
     pricing: ModelPricing | null;
     provenance: ModelPricingProvenance;
 }
+export interface ResolveModelPricingOptions {
+    /**
+     * Consult entries from `registerModelPricing`. Defaults to true; pass false
+     * to see what the package's own layers would answer.
+     */
+    includeRegistered?: boolean;
+}
+export interface RegisterModelPricingOptions {
+    /**
+     * `false` (default): the entry wins over every other layer — explicit
+     * configuration such as negotiated prices.
+     *
+     * `true`: the entry is a gap filler. It is used only when no other layer has
+     * an exact price for the looked-up id (its raw form or registered alias
+     * target), so it replaces a prefix-inherited or missing price but never an
+     * exact static, catalog, or imported one.
+     */
+    onlyIfMissing?: boolean;
+}
+/** Where the active pricing tables came from. */
+export type PricingCatalogSource = 'static' | 'litellm' | 'stale-cache' | 'imported';
+/** Describes the pricing basis currently applied to cost estimates. */
+export interface PricingCatalogInfo {
+    /**
+     * `litellm` — catalog loaded from a fresh fetch or a cache within its TTL;
+     * `stale-cache` — catalog loaded from a cache older than its TTL (the
+     * refresh failed or was skipped offline); `imported` — no catalog, but
+     * resolutions imported from another realm are active; `static` — only the
+     * built-in baseline. Registered entries never change the source.
+     */
+    source: PricingCatalogSource;
+    /** When the active catalog was fetched, if known. Only set for catalog sources. */
+    fetchedAt?: string;
+    /**
+     * Stable, non-cryptographic fingerprint (`fnv1a64:<16 hex>`) of the active
+     * static, catalog, imported, and registered pricing tables. Equal digests
+     * mean equal prices; it changes whenever any price in any layer changes.
+     * Registered aliases are not part of it.
+     */
+    digest: string;
+    /** Entries in the runtime catalog layer. */
+    catalogEntries: number;
+    /** Entries in the `registerModelPricing` layer. */
+    registeredEntries: number;
+}
+/**
+ * Internal: how the catalog overrides were obtained, recorded by
+ * `pricingCatalog.ts` alongside `_setPricingOverrides`.
+ */
+export interface PricingOverridesBasis {
+    source: 'litellm' | 'stale-cache';
+    fetchedAt?: string;
+}
+/** One contribution to a cost rollup, for `mergeCostComponents`. */
+export interface CostComponent {
+    /** Provenance of this component's cost; undefined means nothing seen yet. */
+    source?: CostSource;
+    /** Tokens this component contributed. */
+    tokens: number;
+}
 /**
  * Token usage for the legacy cost calculation contract.
  * @deprecated Use NormalizedUsage and calculateNormalizedUsageCost. This shape
@@ -65,6 +148,12 @@ export interface ParsedModelId {
     provider: ModelProvider;
     family: string;
     version: string;
+    /**
+     * GPT tier name (`astra`, `sol`, `terra`, `luna`) when the id carries one,
+     * e.g. `gpt-6.1-sol` → `sol`. `version` still includes it (`6.1-sol`).
+     * Absent for every other id.
+     */
+    variant?: string;
 }
 /** Comprehensive model metadata. */
 export interface ModelInfo {
@@ -104,8 +193,12 @@ export interface ModelDisplayInfo {
  * after a successful LiteLLM hydration. Not part of the stable public API,
  * but exported so the Node-only catalog module can wire itself in without
  * creating a circular import.
+ *
+ * `basis` records how the map was obtained for `getPricingCatalogInfo()`;
+ * omitted, a non-empty map reports as `litellm` with no `fetchedAt`. Every
+ * call replaces the previous basis.
  */
-export declare function _setPricingOverrides(overrides: Record<string, ModelPricing>): void;
+export declare function _setPricingOverrides(overrides: Record<string, ModelPricing>, basis?: PricingOverridesBasis): void;
 /** Internal: snapshot current overrides (test + diagnostics). */
 export declare function _getPricingOverrides(): Record<string, ModelPricing>;
 /** Internal: clear overrides (used by tests and when disabling hydration). */
@@ -118,8 +211,67 @@ export declare function _clearPricingOverrides(): void;
 export declare function _setImportedResolvedPricing(values: Record<string, ResolvedModelPricing>): void;
 /** Internal test hook. */
 export declare function _clearImportedResolvedPricing(): void;
+/**
+ * Register consumer pricing for model ids, e.g. negotiated or private-deployment
+ * rates. This layer is separate from the runtime catalog and imported layers:
+ * `_setPricingOverrides`, `hydratePricingCatalog`, and
+ * `importResolvedModelCatalog` never reset it; only
+ * `clearRegisteredModelPricing` does.
+ *
+ * Keys are trimmed, lowercased, and stripped of `[1m]`, like the other tables.
+ * Matching is exact, never by prefix, against the looked-up id, its registered
+ * alias target, and its `canonicalModelId()` form — so a `claude-opus-5-5`
+ * entry also answers `claude-opus-5-5-20261001` and
+ * `us.anthropic.claude-opus-5-5-20261001-v1:0`.
+ *
+ * Successive calls merge; re-registering a key replaces its price and mode.
+ * Entries whose four rates are not all finite, nonnegative numbers are
+ * skipped. Results carry `provenance.source: 'registered'`.
+ *
+ * Registered entries are realm-local configuration and are kept out of
+ * cross-realm snapshots: they are not listed by the catalog id enumeration,
+ * and `resolveModelPricing(id, { includeRegistered: false })` is the
+ * resolution a snapshot should carry. An exported price would otherwise be
+ * pinned as an exact import in the other realm and outlive
+ * `clearRegisteredModelPricing` there. Register in each realm instead.
+ */
+export declare function registerModelPricing(entries: Record<string, ModelPricing>, options?: RegisterModelPricingOptions): void;
+/** Remove every entry added by `registerModelPricing`. */
+export declare function clearRegisteredModelPricing(): void;
+/**
+ * Describe the pricing basis behind current cost estimates: which layer the
+ * prices come from, when the catalog was fetched, and a digest that changes
+ * whenever any active price changes. Pure and cheap after the first call (the
+ * digest is memoized until a table changes).
+ */
+export declare function getPricingCatalogInfo(): PricingCatalogInfo;
 /** Internal: list every ID known to the pricing resolver. */
 export declare function _getModelPricingIds(): string[];
+/**
+ * Reduce a model id to the bare model name it denotes, for grouping and
+ * matching across hosts and snapshots.
+ *
+ * Trims and lowercases, then removes: `[1m]`; every leading `segment/`
+ * provider or region prefix (`azure/us/gpt-6.1-terra` → `gpt-6.1-terra`);
+ * Bedrock forms (`us.anthropic.claude-opus-5-5-20261001-v1:0` →
+ * `claude-opus-5-5`, also `eu.`/`apac.`/`global.` and bare `anthropic.`);
+ * Vertex `@YYYYMMDD`; trailing `-YYYYMMDD` and `-YYYY-MM-DD` dates; `-latest`.
+ * Meaningful suffixes (`-mini`, `-codex`, `-sol`, `-terra`, `-high`, …) stay.
+ *
+ * Pure and syntactic: registered aliases are not applied (see
+ * `resolveModelAlias`). Pricing lookups do not use this to reach other
+ * models' prices — dated snapshots and deployments can bill differently — only
+ * to match `registerModelPricing` entries.
+ */
+export declare function canonicalModelId(id: string): string;
+/**
+ * True for model names an agent CLI resolves to a different concrete model
+ * over time (`default`, `auto`, `latest`, `sonnet`, `opus`, `haiku`, `fable`,
+ * and Claude Code's `opusplan`), so a recorded value names a moving target
+ * rather than a model. Case-insensitive, trimmed, and `[1m]`-tolerant
+ * (`sonnet[1m]`). Dated or versioned ids are never moving aliases.
+ */
+export declare function isMovingModelAlias(id: string): boolean;
 /**
  * Parses a model ID into {provider, family, version}.
  *
@@ -130,14 +282,23 @@ export declare function _getModelPricingIds(): string[];
  * Returns null for anything else — callers should treat that as "unknown model".
  */
 export declare function parseModelId(modelId: string): ParsedModelId | null;
-/** Resolve pricing and disclose whether the result was inherited by prefix. */
-export declare function resolveModelPricing(modelId: string): ResolvedModelPricing;
+/**
+ * Resolve pricing and disclose which layer answered and whether the result was
+ * inherited by prefix.
+ *
+ * Order: registered entries (default mode); exact imported, catalog, and
+ * static matches; registered `onlyIfMissing` entries; catalog then static
+ * prefix matches; unpriced.
+ */
+export declare function resolveModelPricing(modelId: string, options?: ResolveModelPricingOptions): ResolvedModelPricing;
 /**
  * Gets pricing for a model ID.
  *
- * Lookup order:
- *   1. Runtime override map (from LiteLLM catalog hydration).
- *   2. Static PRICING_TABLE.
+ * Lookup order (see `resolveModelPricing` for provenance):
+ *   1. Registered entries (`registerModelPricing`), exact matches only.
+ *   2. Imported resolutions, then the runtime override map (from LiteLLM
+ *      catalog hydration), then the static PRICING_TABLE — exact before prefix,
+ *      with gap-filling registered entries between the two.
  *   3. `null` — unknown model. Callers MUST handle this.
  *
  * The ID is first looked up verbatim (minus the "[1m]" suffix) — override
@@ -188,6 +349,19 @@ export declare function calculateCostWithProvenance(input: CostProvenanceInput):
  * containing any unpriced or estimated component does not look fully reported.
  */
 export declare function mergeCostSources(a: CostSource, b: CostSource): CostSource;
+/**
+ * Map the provenance `calculateNormalizedUsageCost` reports to the display
+ * cost source: provider-reported costs are `reported`, costs computed from
+ * explicit or catalog pricing are `estimated`, and unpriced stays `unpriced`.
+ */
+export declare function costSourceFromPricingProvenance(provenance: PricingProvenance): CostSource;
+/**
+ * Merge the cost sources of a rollup's components, least certain winning (as
+ * `mergeCostSources`). Components without a `source` have not been seen yet
+ * and are ignored, and an `unpriced` component that contributed no tokens
+ * does not taint the total. Returns `undefined` when nothing counted.
+ */
+export declare function mergeCostComponents(components: Iterable<CostComponent>): CostSource | undefined;
 /**
  * Short display label for model IDs. Keeps historical Claude family labels
  * compact while normalizing common OpenAI labels.
@@ -197,15 +371,10 @@ export declare function shortModelName(modelId: string): string;
  * Returns stable display metadata and a rank suitable for provider model menus.
  */
 export declare function getModelDisplayInfo(modelId: string): ModelDisplayInfo;
-/** Compare two model IDs using shared provider/family ranking rules. */
+/**
+ * Compare two model IDs using shared provider/family ranking rules. Within a
+ * family and numeric version, GPT tiers rank astra > sol > terra > luna.
+ */
 export declare function compareModelIds(a: string, b: string): number;
 /** Return a sorted copy of model IDs using shared provider/family ranking rules. */
 export declare function sortModelIds<T extends string>(modelIds: readonly T[]): T[];
-/**
- * Formats a USD cost as a currency string.
- *
- * - `null` / `undefined` → `"—"` (honest "pricing unavailable").
- * - `< $0.01` → 4 decimals, so sub-cent costs are still visible.
- * - otherwise → 2 decimals.
- */
-export declare function formatCost(cost: number | null | undefined): string;