Limited support for custom models in pricing and budget management

The problem

I would like to use custom models in Facility while retaining accurate cost tracking and budget management. Currently, there is a gap between configuring custom models for use and managing their costs.

1. Configuring custom model prices requires source code changes

Input, output, cache-read, and cache-write prices are currently defined in MODEL_PRICES_USD_PER_1M. There is no supported UI or deployment configuration entry point for adding or overriding these prices.

Accounting for paid custom models therefore requires modifying the source code and maintaining those changes across upgrades.

2. Model access and zero-cost policy are not expressed independently

These three concepts should be distinguished:

• Unknown price: Facility has no configured price for the model. This does not mean the provider does not charge for it.
• Explicit zero-cost treatment: An administrator explicitly chooses to account for the model's calls at zero cost.
• Permission to call: A key is authorized to use the model, independently of whether that model incurs charges.

Currently, the zero-cost check derives the cost policy from allowedModels and whether the models are present in the pricing table, rather than from a separate, explicit cost declaration.

An existing test explicitly verifies that:

• An unpriced model is rejected under ordinary circumstances.
• A key described by the test as “explicit zero-cost” can still make a request with a hard budget of zero.
• That request is recorded with costCents = 0 and priced = false.

This shows that preserving a zero-cost execution path is intentional. However, the test does not establish that every permitted, unpriced model should be treated as free. In the test, “explicit zero-cost” is expressed through allowedModels, without a separate cost declaration.

Paid custom models need a clear way to express their prices and budget behavior, beyond simply allowing calls or accounting for them at zero cost.

What you propose

1. Support configurable custom model pricing

Allow administrators to add or override model prices through a supported configuration entry point, without modifying source code.

Support input and output prices, plus cache-read and cache-write prices where applicable, with clearly documented pricing units.

The initial implementation does not need to fetch prices automatically from provider websites. Manual configuration would be sufficient.

2. Separate cost status from model access permissions

Explicitly distinguish between:

• Configured pricing.
• Explicit zero-cost treatment.
• Unknown pricing.

allowedModels should control model access only; it should not also serve as a zero-cost declaration.

Preserve existing zero-cost use cases, but represent them through an independent, explicit setting.

3. Define how unknown pricing is handled

Reject requests for models with unknown prices by default, or provide an explicit administrator-controlled option to allow them.

If such requests are allowed:

• Clearly display “cost unknown” in the UI and relevant records.
• Explain that monetary budgets cannot reliably constrain this portion of spending.
• Do not present unknown costs as confirmed zero costs.

4. Integrate custom pricing with existing cost tracking and budgets

Custom models with configured prices should participate in the same cost calculation, spending records, and budget enforcement flows as built-in models.

Add unit tests and integration tests using deterministic local provider stubs to cover configured pricing, explicit zero-cost treatment, and unknown pricing.

Compatibility considerations

This changes the existing behavior in which an allowlist can implicitly express zero-cost treatment.

Provide migration guidance or an administrator confirmation mechanism so existing deployments can explicitly preserve their intended zero-cost settings, without silently changing their behavior.

Acceptance goal

An administrator can configure custom model prices without modifying source code and can clearly determine whether those calls are subject to monetary budget enforcement.

What you considered instead

• Modifying the source pricing table: This can solve the problem for an individual deployment, but requires maintaining local changes and increases upgrade overhead.
• Continuing to account for unpriced models at zero cost: This is appropriate for explicitly chosen zero-cost use cases, but does not meet the cost-tracking and budget-management needs of paid custom models.
• Restricting usage to models in the built-in pricing table: This avoids unknown pricing, but limits custom model support.
• Relying only on the provider's billing dashboard: This can help verify actual spending, but does not replace Facility's per-project or per-task cost tracking and budget controls.

Start with packages/core/src/pricing.ts, the zero-cost check around services/gateway/src/app.ts:479, and the related cases in services/gateway/test/gateway.test.ts:635. Trace how model access, pricing, cost records, and budgets currently interact, then define a supported configuration path and independent unknown, zero-cost, and priced states. Done includes deterministic unit and integration coverage for these states and migration handling for existing zero-cost configurations.