@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
693 lines (655 loc) • 29.4 kB
text/typescript
/**
* Cost estimation core (devlog/_plan/260720_toks_speed_price_columns/010).
*
* All prices are display-time ESTIMATES (~$), never billing reproductions:
* - cache detail comes from provider usage as-reported (no session heuristics);
* - matching is exact native provider/model ID via the jawcode alias table
* (no fuzzy, no case-fold, no resolvedModel/requestedModel fallback);
* - user-configured provider overlay wins, then jawcode nonzero price, then the expected-price overlay
* (verified / verified-derived only), otherwise null => UI shows em dash;
* - combo sums per-attempt costs and fails closed when any attempt is unpriced.
*/
import {
findVendorCostByModelId,
getModelMetadata,
resolveMetadataProvider,
} from "../generated/model-metadata";
import type { AttemptTierOutcome, OcxUsage } from "../types";
import { canonicalFastTierMarker } from "../providers/fastwire";
import { baseProviderLabel } from "../providers/label";
import type { PersistedUsageAttempt, UsageStatus } from "./log";
import { canonicalAntigravityUsageModel } from "../providers/antigravity-models";
import { activeAccountPricingProviders, activeConfiguredProviders, activeUserCostOverlays, userCostOverlayVersion } from "./user-cost-overlays";
import {
EXPECTED_PRICE_OVERLAYS,
findExpectedPriceOverlay,
findVerifiedPriceOverride,
findPriorityPricingRule,
cursorFastPriceMultiplier,
cursorFastPriceSource,
cursorFastPriceSupported,
findContextTier,
isLongContext,
type Cost4,
type ExpectedPriceOverlay,
type ExpectedPriceStatus,
} from "./expected-prices";
/** Published long-context pricing band (#908). */
export type ContextTierName = "long";
export interface PriceResolutionOptions {
/** False for unresolved slash selectors; exact provider/user rates still apply. */
allowModelLevelFallback?: boolean;
}
type AttemptCostInput = Pick<PersistedUsageAttempt, "ordinal" | "provider" | "model" | "usage" | "usageStatus" | "tierOutcome"> & PriceResolutionOptions;
/**
* Service-tier provenance. `effectiveServiceTier()` collapses these with `??`,
* but provider-specific long-context rules need to know WHICH source supplied Fast.
* Current API rows stack Fast and long rates; legacy exclusive rows and unknown
* vendor combinations still require response-confirmed provenance.
*/
export interface ServiceTierContext {
responseServiceTier?: string;
requestedServiceTier?: string;
configuredServiceTier?: string;
tierOutcome?: AttemptTierOutcome;
}
export interface CostTokens {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
}
export interface CostBreakdown {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
total: number;
}
export interface MatchedPrice {
provider: string;
modelId: string;
jawcodeProvider?: string;
cost4: Cost4;
source: "jawcode" | "expected" | "user";
sourceRef?: string;
verifiedAt?: string;
status: "verified" | "verified-derived";
}
export interface AttemptCostEstimate {
ordinal: number;
provider: string;
model: string;
tokens: CostTokens;
price: MatchedPrice;
cost: CostBreakdown;
estimated: boolean;
/** Applied provider priority-tier multiplier (undefined or 1 = standard). */
priorityMultiplier?: number;
/** Set when the published long-context rate was applied (#908). */
contextTier?: ContextTierName;
/** The numeric estimate is a known floor because the exact Priority price is unavailable. */
priorityLowerBound?: boolean;
}
export interface CostEstimate {
tokens: CostTokens;
cost: CostBreakdown;
estimated: boolean;
attempts?: AttemptCostEstimate[];
price?: MatchedPrice;
/** Applied provider priority-tier multiplier (undefined or 1 = standard). */
priorityMultiplier?: number;
/** Set when any priced attempt used the published long-context rate (#908). */
contextTier?: ContextTierName;
/** The aggregate is a known floor because every priced attempt is a lower bound. */
priorityLowerBound?: boolean;
}
function finiteNonNegative(value: number): boolean {
return Number.isFinite(value) && value >= 0;
}
function validCost4(cost: Cost4 | undefined): cost is Cost4 {
return !!cost
&& finiteNonNegative(cost.input)
&& finiteNonNegative(cost.output)
&& finiteNonNegative(cost.cacheRead)
&& finiteNonNegative(cost.cacheWrite);
}
function hasNonZeroCost(cost: Cost4): boolean {
return cost.input !== 0 || cost.output !== 0
|| cost.cacheRead !== 0 || cost.cacheWrite !== 0;
}
/**
* Normalize inclusive OcxUsage (types.ts: inputTokens INCLUDES cache read/write)
* into jawcode CostTokens (input = uncached prompt only) without double-charging.
*
* Canonical-first with a single legacy retry: the canonical contract says
* `cachedInputTokens` is read-only tokens, but legacy claude-route rows stored
* read+write combined there (devlog 070). The two shapes are indistinguishable
* by fields alone, so we apply the canonical reading first and only when it
* produces an impossible R+W>I do we retry the legacy recovery
* (cached - creation). If both readings are contradictory, fail closed (null).
*/
export function normalizeCostTokens(usage: OcxUsage): CostTokens | null {
const input = usage.inputTokens;
const output = usage.outputTokens;
const cacheWrite = usage.cacheCreationInputTokens ?? 0;
const primaryRead = usage.cacheReadInputTokens ?? usage.cachedInputTokens ?? 0;
const candidates: number[] = [primaryRead];
if (typeof usage.cacheReadInputTokens !== "number"
&& typeof usage.cachedInputTokens === "number"
&& typeof usage.cacheCreationInputTokens === "number") {
candidates.push(Math.max(0, usage.cachedInputTokens - usage.cacheCreationInputTokens));
}
for (const cacheRead of candidates) {
if (![input, output, cacheRead, cacheWrite].every(finiteNonNegative)) return null;
if (cacheRead + cacheWrite > input) continue;
return {
input: Math.max(0, input - cacheRead - cacheWrite),
output,
cacheRead,
cacheWrite,
};
}
return null;
}
/** jawcode unit convention: USD per 1M tokens (jawcode stats/db.ts calculateCatalogCost). */
export function calculateCost(tokens: CostTokens, cost4: Cost4): CostBreakdown {
const input = cost4.input * tokens.input / 1_000_000;
const output = cost4.output * tokens.output / 1_000_000;
const cacheRead = cost4.cacheRead * tokens.cacheRead / 1_000_000;
const cacheWrite = cost4.cacheWrite * tokens.cacheWrite / 1_000_000;
return { input, output, cacheRead, cacheWrite, total: input + output + cacheRead + cacheWrite };
}
/**
* Fixed priority: user-configured provider overlay -> jawcode exact (provider
* bundle) nonzero -> overlay verified -> overlay verified-derived -> jawcode
* model-level vendor price (cross-provider fallback: a model follows its official
* vendor price — WP5 policy, e.g. kiro/claude-opus-4-6 uses the anthropic price)
* -> null. An explicit all-zero user override means free; all-zero catalog
* rows remain overlay candidates rather than evidence of free pricing.
*/
export function resolveMatchedPrice(
provider: string,
modelId: string,
overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
options: PriceResolutionOptions = {},
): MatchedPrice | null {
// Literal configured providers win over account identities. Only then use
// config-owned Codex identities, followed by the existing historical suffix
// grammar. Never infer an account by stripping an arbitrary suffix.
const namespace = activeConfiguredProviders().has(provider)
? provider
: activeAccountPricingProviders().get(provider) ?? baseProviderLabel(provider);
if (namespace !== provider) {
// An exact override (including caller-supplied rows) owns its namespace.
// Unchanged names use the memoized inner lookup's existing user-first order.
const exactUserOverlay = userOverlayMatch(provider, modelId, userOverlays);
if (exactUserOverlay) return exactUserOverlay;
provider = namespace;
}
// Memoize by (provider, model): usage summaries iterate hundreds of thousands of
// rows that share a handful of provider/model keys, so resolving each time would
// dominate /api/usage latency (WP6 audit). The compiled overlays are static;
// user overlays get a NEW array identity + version bump on every config refresh,
// so memoized rows never go stale.
if (overlays === EXPECTED_PRICE_OVERLAYS && userOverlays === activeUserCostOverlays()) {
const cacheKey = `${userCostOverlayVersion()} ${options.allowModelLevelFallback !== false} ${provider} ${modelId}`;
if (!priceMemo.has(cacheKey)) {
if (priceMemo.size >= 512) priceMemo.clear();
priceMemo.set(cacheKey, resolveMatchedPriceInner(provider, modelId, overlays, userOverlays, options));
}
return priceMemo.get(cacheKey)!;
}
return resolveMatchedPriceInner(provider, modelId, overlays, userOverlays, options);
}
const priceMemo = new Map<string, MatchedPrice | null>();
/**
* Resolution wrapper: exact provider/model lookup first, then the Antigravity
* base-model fallback for collapsed wire ids. Never falls through to the
* cross-provider vendor price at this level.
*/
function resolveMatchedPriceInner(
provider: string,
modelId: string,
overlays: readonly ExpectedPriceOverlay[],
userOverlays: readonly ExpectedPriceOverlay[],
options: PriceResolutionOptions,
): MatchedPrice | null {
const direct = resolveMatchedPriceExact(provider, modelId, overlays, userOverlays, options);
if (direct) return direct;
// Antigravity historical/wire ids often lack an exact overlay; fall back to the
// picker/call base model so collapsed usage rows still get a price.
if (provider === "google-antigravity" || provider.startsWith("google-antigravity")) {
const base = canonicalAntigravityUsageModel(modelId);
if (base !== modelId) return resolveMatchedPriceExact(provider, base, overlays, userOverlays, options);
}
return null;
}
/**
* Exact provider/model price lookup: user-configured `modelCosts` first, then
* an exact official correction, the jawcode provider bundle, the expected-price overlay, then the
* model-level vendor fallback. All-zero catalog rows fall through; user zeros win.
*/
function resolveMatchedPriceExact(
provider: string,
modelId: string,
overlays: readonly ExpectedPriceOverlay[],
userOverlays: readonly ExpectedPriceOverlay[],
options: PriceResolutionOptions,
): MatchedPrice | null {
// User-configured provider overlay wins over every compiled catalog: the
// operator's explicit price is authoritative for the ~$ estimate.
const userOverlay = userOverlayMatch(provider, modelId, userOverlays);
if (userOverlay) return userOverlay;
if (!cursorFastPriceSupported(provider, modelId)) return null;
const verifiedOverride = overlays === EXPECTED_PRICE_OVERLAYS
? findVerifiedPriceOverride(provider, modelId)
: undefined;
if (verifiedOverride && verifiedOverride.status !== "unverified" && validCost4(verifiedOverride.cost4) && hasNonZeroCost(verifiedOverride.cost4)) {
return {
provider,
modelId,
cost4: multiplyCursorFastCost(verifiedOverride.cost4, provider, modelId),
source: "expected",
sourceRef: verifiedOverride.source,
verifiedAt: verifiedOverride.verifiedAt,
status: verifiedOverride.status,
...cursorFastPriceProvenance(provider, modelId),
};
}
const metadataProvider = resolveMetadataProvider(provider);
const bundled = metadataProvider
? getModelMetadata(metadataProvider, modelId)
: undefined;
if (bundled?.cost && validCost4(bundled.cost) && hasNonZeroCost(bundled.cost)) {
return {
provider,
modelId,
jawcodeProvider: metadataProvider,
cost4: multiplyCursorFastCost(bundled.cost, provider, modelId),
source: "jawcode",
status: "verified",
...cursorFastPriceProvenance(provider, modelId),
};
}
const overlay = findExpectedPriceOverlay(provider, modelId, overlays);
if (!overlay || !validCost4(overlay.cost4) || !hasNonZeroCost(overlay.cost4)) {
if (options.allowModelLevelFallback === false) return null;
const fallback = resolveModelLevelPrice(provider, modelId);
return fallback
? { ...fallback, cost4: multiplyCursorFastCost(fallback.cost4, provider, modelId), ...cursorFastPriceProvenance(provider, modelId) }
: null;
}
if (overlay.status === "unverified") return null;
return {
provider,
modelId,
...(metadataProvider ? { jawcodeProvider: metadataProvider } : {}),
cost4: multiplyCursorFastCost(overlay.cost4, provider, modelId),
source: "expected",
sourceRef: overlay.source,
verifiedAt: overlay.verifiedAt,
status: overlay.status,
...cursorFastPriceProvenance(provider, modelId),
};
}
function multiplyCursorFastCost(cost4: Cost4, provider: string, modelId: string): Cost4 {
const multiplier = cursorFastPriceMultiplier(provider, modelId);
if (multiplier === 1) return cost4;
return {
input: cost4.input * multiplier,
output: cost4.output * multiplier,
cacheRead: cost4.cacheRead * multiplier,
cacheWrite: cost4.cacheWrite * multiplier,
};
}
function cursorFastPriceProvenance(provider: string, modelId: string): Pick<MatchedPrice, "sourceRef" | "status"> | Record<never, never> {
const sourceRef = cursorFastPriceSource(provider, modelId);
return sourceRef ? { sourceRef, status: "verified" } : {};
}
/** User-configured overlay match; explicit zero rates are authoritative too. */
function userOverlayMatch(
provider: string,
modelId: string,
userOverlays: readonly ExpectedPriceOverlay[],
): MatchedPrice | null {
const overlay = findExpectedPriceOverlay(provider, modelId, userOverlays);
if (!overlay || !validCost4(overlay.cost4)) return null;
return {
provider,
modelId,
cost4: overlay.cost4,
source: "user",
sourceRef: overlay.source,
verifiedAt: overlay.verifiedAt,
status: "verified",
};
}
function resolveModelLevelPrice(provider: string, modelId: string): MatchedPrice | null {
// Exact first; then dot->dash variant for providers that spell vendor ids with
// dots where the catalog uses dashes (kiro "claude-opus-4.6" vs anthropic
// "claude-opus-4-6"). No fuzzy matching beyond this one normalization.
const found = findVendorCostByModelId(modelId)
?? (modelId.includes(".") ? findVendorCostByModelId(modelId.replaceAll(".", "-")) : undefined)
?? vendorPrefixedCost(modelId);
if (!found) return null;
return {
provider,
modelId,
jawcodeProvider: found.provider,
cost4: found.cost,
source: "jawcode",
status: "verified-derived",
};
}
/**
* Aggregators spell a model as `<vendor>/<model>` — CommandCode serves
* `deepseek/deepseek-v4-flash`, and OpenRouter-shaped presets do the same. The cost
* catalog stores the bare id, so the exact lookup above misses a price that is present and
* every request through such a provider reports no cost at all (#3136).
*
* Retrying on the tail is only safe while the prefix AGREES with the vendor the matched row
* belongs to. `findVendorCostByModelId` returns whichever vendor `COST_VENDOR_PRIORITY`
* reaches first, so an unchecked strip would happily price `openai/claude-opus-4-6` from
* Anthropic's row — a number that looks authoritative and is wrong. Requiring agreement
* keeps the failure closed for a genuinely mismatched id.
*
* Comparison is normalized because the same vendor is spelled differently across catalogs:
* `x-ai/grok-4.6` resolves to vendor `xai`. Dashes and case are the only variance seen;
* anything beyond that stays a miss.
*/
function vendorPrefixedCost(modelId: string): ReturnType<typeof findVendorCostByModelId> {
const slash = modelId.indexOf("/");
if (slash <= 0 || slash === modelId.length - 1) return undefined;
const claimedVendor = modelId.slice(0, slash);
const tail = modelId.slice(slash + 1);
// A tail that is itself slashed is not a vendor prefix we understand; leave it alone.
if (tail.includes("/")) return undefined;
const found = findVendorCostByModelId(tail)
?? (tail.includes(".") ? findVendorCostByModelId(tail.replaceAll(".", "-")) : undefined);
if (!found) return undefined;
const normalize = (value: string): string => value.toLowerCase().replaceAll("-", "");
return normalize(found.provider) === normalize(claimedVendor) ? found : undefined;
}
function isEstimated(usage: OcxUsage, usageStatus: UsageStatus, priceStatus: ExpectedPriceStatus | "verified"): boolean {
return usage.estimated === true || usageStatus === "estimated" || priceStatus === "verified-derived";
}
/**
* Resolve the effective service tier from persisted log fields.
* Priority: responseServiceTier (server-confirmed) > requestedServiceTier
* (client-sent, pre-rewrite) > configuredServiceTier (config.fastMode injection).
*/
export function effectiveServiceTier(entry: {
responseServiceTier?: string;
requestedServiceTier?: string;
configuredServiceTier?: string;
}): string | undefined {
return entry.responseServiceTier ?? entry.requestedServiceTier ?? entry.configuredServiceTier;
}
/**
* Accepts either the collapsed tier scalar or the full provenance record.
* A bare string carries no provenance, so it cannot confirm Fast: callers that
* need long-context exclusivity to be correct must pass the record.
*/
export type ServiceTierInput = string | ServiceTierContext;
/**
* Narrow a persisted log entry to just its tier provenance. Prefer this over
* `effectiveServiceTier()` at estimator call sites: the collapsed scalar cannot
* distinguish a response-confirmed Fast request from a merely requested one,
* and long-context exclusivity depends on that distinction.
*/
export function serviceTierContext(entry: ServiceTierContext): ServiceTierContext {
if (entry.tierOutcome) {
return { ...serviceTierContextFromOutcome(entry.tierOutcome), tierOutcome: entry.tierOutcome };
}
return {
responseServiceTier: entry.responseServiceTier,
requestedServiceTier: entry.requestedServiceTier,
configuredServiceTier: entry.configuredServiceTier,
};
}
/** Convert one adapter-observed attempt outcome into the existing pricing provenance shape. */
export function serviceTierContextFromOutcome(outcome: AttemptTierOutcome): ServiceTierContext {
const responseAuthoritative = outcome.responseTierAuthoritative !== false;
if (responseAuthoritative && outcome.canonical === "priority" && outcome.confirmation === "confirmed") {
return { responseServiceTier: "priority" };
}
// Non-authoritative echoes remain in the log, but cannot become pricing confirmation either.
if (responseAuthoritative && outcome.responseServiceTier !== undefined) {
return { responseServiceTier: outcome.responseServiceTier };
}
if (outcome.canonical === "priority"
&& (outcome.confirmation === "assumed" || (!responseAuthoritative && outcome.confirmation === "confirmed"))) {
return { requestedServiceTier: "priority" };
}
// An unclassified route makes no canonical Fast claim, but its adapter can still prove that
// it serialized a caller tier. Preserve that wire evidence instead of discarding the legacy
// top-level pricing signal merely because B0 added an outcome row.
if (
outcome.fastOutcome === "unknown"
&& outcome.wireKind === "service-tier"
&& typeof outcome.wireValue === "string"
) {
return { requestedServiceTier: outcome.wireValue };
}
return {};
}
function tierScalar(tier?: ServiceTierInput): string | undefined {
return typeof tier === "string" ? tier : tier && effectiveServiceTier(tier);
}
/** True only when the UPSTREAM RESPONSE confirmed the Fast tier (see ServiceTierContext). */
function isConfirmedFast(tier?: ServiceTierInput): boolean {
return typeof tier === "object" && canonicalFastTierMarker(tier.responseServiceTier) === "priority";
}
/**
* Apply the published long-context rate when raw prompt size crosses the vendor
* threshold. Returns [effectiveCost4, tierName].
*
* `rawInputTokens` MUST be `usage.inputTokens` (total prompt size), never the
* normalized billable input — normalization subtracts cache read/write, so a
* cache-heavy long prompt would fall below the boundary and under-bill.
*
* A provider's declaration decides how a response-confirmed priority tier relates to this band.
* API rows can stack the bands. xAI publishes neither a combined rate nor an exclusion,
* so its long-context rate remains the known lower bound instead of inventing a stacked multiplier.
*/
function applyContextTier(
cost4: Cost4,
provider: string,
modelId: string,
rawInputTokens: number | undefined,
tier?: ServiceTierInput,
): [Cost4, ContextTierName | undefined, boolean] {
if (rawInputTokens === undefined) return [cost4, undefined, false];
const rule = findContextTier(provider, modelId);
if (!rule || !isLongContext(rule, rawInputTokens)) return [cost4, undefined, false];
const confirmedFast = isConfirmedFast(tier);
if (confirmedFast && rule.confirmedPriorityRelation === "exclusive") {
return [cost4, undefined, false];
}
return [{
input: cost4.input * rule.multiplier.input,
output: cost4.output * rule.multiplier.output,
cacheRead: cost4.cacheRead * rule.multiplier.cacheRead,
cacheWrite: cost4.cacheWrite * rule.multiplier.cacheWrite,
}, "long", confirmedFast && rule.confirmedPriorityRelation === "lower-bound"];
}
/**
* Apply a declared provider/model priority-tier multiplier to a Cost4 when applicable.
* Returns [effectiveCost4, multiplier]. Multiplier is 1 (no-op) when:
* - serviceTier is not "priority"
* - no exact provider/model rule exists
*/
function applyPriorityMultiplier(
cost4: Cost4,
provider: string,
modelId: string,
serviceTier?: ServiceTierInput,
contextTier?: ContextTierName,
): [Cost4, number] {
if (canonicalFastTierMarker(tierScalar(serviceTier)) !== "priority") return [cost4, 1];
if (contextTier && findContextTier(provider, modelId)?.confirmedPriorityRelation !== "stack") return [cost4, 1];
const rule = findPriorityPricingRule(provider, modelId);
if (rule?.requiresResponseConfirmation && !isConfirmedFast(serviceTier)) return [cost4, 1];
const multiplier = rule?.multiplier ?? 1;
if (multiplier === 1) return [cost4, 1];
return [{
input: cost4.input * multiplier,
output: cost4.output * multiplier,
cacheRead: cost4.cacheRead * multiplier,
cacheWrite: cost4.cacheWrite * multiplier,
}, multiplier];
}
/**
* OpenRouter confirms the actual endpoint tier and documents priority as higher cost, but this
* branch does not bundle its provider-specific priority endpoint prices. A confirmed canonical
* priority result can therefore use the standard price only as a provable lower bound. Do not
* extend this to flex (cheaper) or to other providers without the same pricing contract.
*
* An ASSUMED priority attempt needs the same marker for a different reason. There the provider
* never echoed a tier at all, so the standard price is not merely a lower bound on a known
* premium — it is a floor under an outcome we did not observe. Returning it unmarked reports a
* definite standard cost for a request that may well have been billed as priority, which is the
* one thing a cost estimate must never do.
*/
function isOpenRouterPriorityLowerBound(
provider: string,
outcome: AttemptTierOutcome | undefined,
): boolean {
return provider === "openrouter"
&& outcome?.canonical === "priority"
&& outcome.fastOutcome === "applied"
&& (outcome.confirmation === "confirmed" || outcome.confirmation === "assumed");
}
/**
* Per-attempt cost estimate: tokens normalized, price resolved (user overlay →
* catalogs), priority/long-context tiers applied. Null when usage or price is
* missing so combos can fail closed.
*/
export function estimateAttemptCost(
attempt: AttemptCostInput,
overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
serviceTier?: ServiceTierInput,
userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
): AttemptCostEstimate | null {
if (!attempt.usage) return null;
const tokens = normalizeCostTokens(attempt.usage);
if (!tokens) return null;
const price = resolveMatchedPrice(attempt.provider, attempt.model, overlays, userOverlays, attempt);
if (!price) return null;
const attemptServiceTier = attempt.tierOutcome
? serviceTierContextFromOutcome(attempt.tierOutcome)
: serviceTier;
const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
price.cost4, price.provider, attempt.model, attempt.usage.inputTokens, attemptServiceTier,
);
const [effectiveCost4, multiplier] = applyPriorityMultiplier(
tieredCost4, price.provider, attempt.model, attemptServiceTier, contextTier,
);
const priorityLowerBound = contextPriorityLowerBound
|| isOpenRouterPriorityLowerBound(price.provider, attempt.tierOutcome);
return {
ordinal: attempt.ordinal,
provider: attempt.provider,
model: attempt.model,
tokens,
price,
cost: calculateCost(tokens, effectiveCost4),
estimated: isEstimated(attempt.usage, attempt.usageStatus, price.status),
...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
...(contextTier ? { contextTier } : {}),
...(priorityLowerBound ? { priorityLowerBound: true } : {}),
};
}
/**
* Combo: price every attempt with its own rate and sum. Fail closed — if ANY
* attempt is unpriced or unnormalizable, return null rather than a partial sum.
*/
export function estimateComboCost(
attempts: readonly AttemptCostInput[],
overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
serviceTier?: ServiceTierInput,
userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
): CostEstimate | null {
if (attempts.length === 0) return null;
const estimates: AttemptCostEstimate[] = [];
for (const attempt of attempts) {
const estimate = estimateAttemptCost(attempt, overlays, serviceTier, userOverlays);
if (!estimate) return null;
estimates.push(estimate);
}
const tokens: CostTokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
const cost: CostBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
for (const est of estimates) {
tokens.input += est.tokens.input;
tokens.output += est.tokens.output;
tokens.cacheRead += est.tokens.cacheRead;
tokens.cacheWrite += est.tokens.cacheWrite;
cost.input += est.cost.input;
cost.output += est.cost.output;
cost.cacheRead += est.cost.cacheRead;
cost.cacheWrite += est.cost.cacheWrite;
cost.total += est.cost.total;
}
return {
tokens,
cost,
estimated: estimates.some(est => est.estimated),
attempts: estimates,
...(estimates.some(est => est.priorityMultiplier && est.priorityMultiplier !== 1)
? { priorityMultiplier: estimates.find(est => est.priorityMultiplier)?.priorityMultiplier }
: {}),
...(estimates.some(est => est.contextTier) ? { contextTier: "long" as const } : {}),
...(estimates.every(est => est.priorityLowerBound === true)
? { priorityLowerBound: true as const }
: {}),
};
}
/** Single-target request cost estimate (non-combo). */
export function estimateRequestCost(
input: {
provider: string;
model: string;
usage?: OcxUsage;
usageStatus: UsageStatus;
serviceTier?: ServiceTierInput;
allowModelLevelFallback?: boolean;
},
overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
): CostEstimate | null {
if (!input.usage) return null;
const tokens = normalizeCostTokens(input.usage);
if (!tokens) return null;
const price = resolveMatchedPrice(input.provider, input.model, overlays, userOverlays, input);
if (!price) return null;
const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
price.cost4, price.provider, input.model, input.usage.inputTokens, input.serviceTier,
);
const [effectiveCost4, multiplier] = applyPriorityMultiplier(
tieredCost4, price.provider, input.model, input.serviceTier, contextTier,
);
const priorityLowerBound = contextPriorityLowerBound || isOpenRouterPriorityLowerBound(
price.provider,
typeof input.serviceTier === "object" ? input.serviceTier.tierOutcome : undefined,
);
return {
tokens,
price,
cost: calculateCost(tokens, effectiveCost4),
estimated: isEstimated(input.usage, input.usageStatus, price.status),
...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
...(contextTier ? { contextTier } : {}),
...(priorityLowerBound ? { priorityLowerBound: true } : {}),
};
}
/**
* End-to-end output rate: outputTokens / wall-clock seconds (jawcode/OpenRouter
* convention — TTFT is NOT subtracted; it is a separate metric, WP4).
*/
export function tokensPerSecond(outputTokens: number, durationMs: number): number | null {
if (!finiteNonNegative(outputTokens) || !finiteNonNegative(durationMs)) return null;
if (outputTokens <= 0 || durationMs <= 0) return null;
return outputTokens / (durationMs / 1_000);
}