Model Catalog Resolution

Relevant source files

The following files were used as context for generating this wiki page:

• src/catalog/parser.ts
• src/catalog/runtime-sync.ts
• src/model/catalog-store.ts
• src/model.ts
• src/upstream/catalog-protocol.ts
• scripts/catalog/sync-catalog.ts
• src/upstream/protocol/constants.ts

Model Catalog Resolution is the system responsible for maintaining, parsing, and normalizing the list of available models and their associated upstream identifiers within freebuff-proxy. It ensures that downstream client requests using human-readable names or legacy IDs correctly map to the internal handles required by the upstream Freebuff/Codebuff orchestrator.

The system operates through a three-layer hierarchy of metadata:

1. Frontend Custom Models: Manual overrides or additions stored in data/custom-models.json.
2. Built-in Catalog: Extracted from Codebuff source constants and stored in src/catalog/freebuff-catalog.json.
3. Naming Rule Derivation: A fallback mechanism for unknown models that derives agent IDs using the base2-free-<slug> pattern.

Sources: src/model.ts:8-15, src/upstream/catalog-protocol.ts:10-18

Architecture and Data Flow

The catalog resolution system synchronizes data from upstream source code and live API responses to build a mapping index. It utilizes a dedicated parser to extract model definitions from TypeScript constant files and a protocol handler to manage live catalog handles.

Catalog Synchronization Flow

The following diagram illustrates how the system fetches and processes model data from upstream sources:

The system uses src/catalog/parser.ts to process raw TypeScript source text into a structured JSON catalog. src/catalog/runtime-sync.ts manages periodic background updates (every 6 hours by default), while scripts/catalog/sync-catalog.ts provides a manual entry point for developers.

Sources: src/catalog/runtime-sync.ts:9-17, scripts/catalog/sync-catalog.ts:16-24, src/catalog/parser.ts:12-20

Model Identifier Normalization

The proxy must reconcile three distinct forms of model identifiers to ensure requests are correctly routed and existing sessions are reused.

Identifier Mapping Hierarchy

Identifier Type	Example	Usage
Catalog Key	m-096e75164d	Internal server-side identifier used for scheduling.
Legacy ID	deepseek/deepseek-v4-flash	Used in upstream session listings (desktopPurchases).
Display Name	DeepSeek V4.1 Flash	Human-readable name used in the web UI and /v1/models.

Sources: test/suites/entries/verify/model/mapping-truth.ts:12-20

Resolution Logic

CatalogHolder.keyForName() serves as the single source of truth for normalizing these inputs. It follows a specific precedence:

1. Display Name Match: Checks against the keyByName map.
2. Legacy ID Digest: Computes an FNV-1a hash of the legacy ID and checks the keyByDigest map.
3. Self-Reference: Validates if the input is already a valid catalog key handle.

Technical Implementation Details

FNV-1a Hashing (Legacy Digest)

The system uses a specific double FNV-1a algorithm to map legacy model IDs to the digests found in the upstream catalog. This implementation is critical for matching existing paid sessions to model requests.

// Sources: src/upstream/catalog-protocol.ts:36-50
export function freebuffLegacyModelDigest(modelId: any) {
  const input = `freebuff-legacy-model:${modelId}`
  let h1 = 0x811c9dc5
  let h2 = 0x01000193 ^ 0x5bd1e995
  for (let i = 0; i < input.length; i++) {
    const c = input.charCodeAt(i)
    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0
    h2 = Math.imul(h2 ^ c, 0x5bd1e995) >>> 0
  }
  return (
    h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')
  )
}

Source Parsing Logic

src/catalog/parser.ts uses regex-based extraction to collect constants from three specific upstream files:

• freebuff-model-ids.ts: Extracts model ID string literals.
• freebuff-models.ts: Extracts displayName and model pool metadata.
• free-agents.ts: Maps models to agentId (Base2) and fallbackAgentId (Base3).

Sources: src/catalog/parser.ts:28-36, src/catalog/parser.ts:74-88

Catalog Protocol Constants

Upstream communication relies on specific headers and path conventions defined in the catalog protocol.

Constant	Value	Description
CATALOG_PATH	/api/v1/freebuff/models	The upstream endpoint for fetching handles.
HEADER_CATALOG_PROTOCOL	x-freebuff-catalog-protocol	Version header (current: 1).
MODEL_HANDLE_PREFIX	fbm1.	Prefix for signed model handles.
CATALOG_FETCH_USER_AGENT	Bun/1.4.2	UA used to mimic the official orchestrator.

Sources: src/upstream/protocol/constants.ts:13-25

Conclusion

Model Catalog Resolution provides the infrastructure necessary for freebuff-proxy to maintain compatibility with shifting upstream model definitions. By combining static source parsing with dynamic runtime synchronization and a robust normalization layer, the system ensures that model requests are always mapped to the correct internal identifiers, protecting user sessions and ensuring reliable upstream communication.

Sources: src/model.ts:8-25, src/upstream/catalog-protocol.ts:145-160