@velum-labs/routekit-registry 1.3.2 → 1.4.0

package/README.md

@@ -3,3 +3,7 @@
 Product-neutral generated provider, subscription, catalog, capability, pricing,
 and local model metadata from `spec/registry`. RouteKit packages consume this
 neutral registry surface only.
+
+`CostService` is the shared pricing, pre-run estimation, and observed-actuals
+capability. Unknown pricing, billing modes, reasoning-token multipliers, and
+missing usage remain explicit instead of becoming zero.

package/dist/generated/data.d.ts

@@ -183,6 +183,15 @@ export declare const REGISTRY: {
             oauth: {
                 tokenEndpoint: string;
                 clientId: string;
+                authorizeUrl: string;
+                redirectUri: string;
+                manualRedirectUri: string;
+                scopes: string;
+                codeChallengeMethod: string;
+                tokenRequestFormat: string;
+                authorizeExtraParams: {
+                    code: string;
+                };
                 usageEndpoint: string;
                 profileEndpoint: string;
             };
@@ -234,8 +243,23 @@ export declare const REGISTRY: {
                 omitSampling: boolean;
             };
             oauth: {
+                issuer: string;
                 tokenEndpoint: string;
                 clientId: string;
+                authorizeUrl: string;
+                redirectUri: string;
+                scopes: string;
+                codeChallengeMethod: string;
+                tokenRequestFormat: string;
+                authorizeExtraParams: {
+                    id_token_add_organizations: string;
+                    codex_cli_simplified_flow: string;
+                    originator: string;
+                };
+                deviceVerificationUrl: string;
+                deviceUserCodeEndpoint: string;
+                deviceTokenPollEndpoint: string;
+                deviceRedirectUri: string;
                 usageEndpoint: string;
                 usagePathFallback: string;
                 resetCreditsEndpoint: string;

package/dist/generated/data.js

@@ -201,8 +201,17 @@ export const REGISTRY = {
                 }
             },
             "oauth": {
-                "tokenEndpoint": "https://console.anthropic.com/v1/oauth/token",
+                "tokenEndpoint": "https://platform.claude.com/v1/oauth/token",
                 "clientId": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+                "authorizeUrl": "https://claude.com/cai/oauth/authorize",
+                "redirectUri": "http://localhost:54545/callback",
+                "manualRedirectUri": "https://platform.claude.com/oauth/code/callback",
+                "scopes": "org:create_api_key user:profile user:inference",
+                "codeChallengeMethod": "S256",
+                "tokenRequestFormat": "json",
+                "authorizeExtraParams": {
+                    "code": "true"
+                },
                 "usageEndpoint": "https://api.anthropic.com/api/oauth/usage",
                 "profileEndpoint": "https://api.anthropic.com/api/oauth/profile"
             },
@@ -260,8 +269,23 @@ export const REGISTRY = {
                 "omitSampling": true
             },
             "oauth": {
+                "issuer": "https://auth.openai.com",
                 "tokenEndpoint": "https://auth.openai.com/oauth/token",
                 "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
+                "authorizeUrl": "https://auth.openai.com/oauth/authorize",
+                "redirectUri": "http://localhost:1455/auth/callback",
+                "scopes": "openid profile email offline_access api.connectors.read api.connectors.invoke",
+                "codeChallengeMethod": "S256",
+                "tokenRequestFormat": "form",
+                "authorizeExtraParams": {
+                    "id_token_add_organizations": "true",
+                    "codex_cli_simplified_flow": "true",
+                    "originator": "routekit"
+                },
+                "deviceVerificationUrl": "https://auth.openai.com/codex/device",
+                "deviceUserCodeEndpoint": "https://auth.openai.com/api/accounts/deviceauth/usercode",
+                "deviceTokenPollEndpoint": "https://auth.openai.com/api/accounts/deviceauth/token",
+                "deviceRedirectUri": "https://auth.openai.com/deviceauth/callback",
                 "usageEndpoint": "https://chatgpt.com/backend-api/wham/usage",
                 "usagePathFallback": "/api/codex/usage",
                 "resetCreditsEndpoint": "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits"

package/dist/index.d.ts

@@ -5,10 +5,12 @@
  * model data are generated from spec/registry. Product-specific identities and
  * panel presets are deliberately excluded.
  */
-import { REGISTRY } from "./generated/data.js";
 import type { ProviderDiscoveryResponseShape } from "@velum-labs/routekit-contracts/provider-discovery";
-export { REGISTRY };
+import { REGISTRY } from "./generated/data.js";
+import { DEFAULT_MODEL_PRICING, PRICING_ALIASES } from "./pricing.js";
+export type { RegistryModelPricing } from "./pricing.js";
 export type { ProviderDiscoveryResponseShape };
+export { DEFAULT_MODEL_PRICING, PRICING_ALIASES, REGISTRY };
 export type ProviderAuthStyle = "bearer" | "x-api-key" | "x-goog-api-key" | "aws-sdk";
 export type ProviderKeyProbe = {
     path: string;
@@ -46,9 +48,26 @@ export declare function defaultKeyEnv(provider: string): string | undefined;
 export declare function providerKeyProbe(provider: string): ProviderKeyProbe | undefined;
 export declare function providerDiscovery(provider: string): ProviderDiscovery | undefined;
 export type SubscriptionMode = "claude-code" | "codex";
+export type SubscriptionTokenRequestFormat = "form" | "json";
 export type SubscriptionOAuthInfo = {
     tokenEndpoint: string;
     clientId: string;
+    authorizeUrl: string;
+    redirectUri: string;
+    /**
+     * Headless/manual redirect used when the host cannot bind a loopback listener
+     * (Claude `--no-browser`). Browser logins keep `redirectUri`.
+     */
+    manualRedirectUri?: string;
+    scopes: string;
+    codeChallengeMethod: "S256";
+    tokenRequestFormat: SubscriptionTokenRequestFormat;
+    authorizeExtraParams?: Readonly<Record<string, string>>;
+    issuer?: string;
+    deviceVerificationUrl?: string;
+    deviceUserCodeEndpoint?: string;
+    deviceTokenPollEndpoint?: string;
+    deviceRedirectUri?: string;
     usageEndpoint: string;
     profileEndpoint?: string;
     usagePathFallback?: string;
@@ -131,12 +150,8 @@ export declare function curatedModels(choice: string): readonly string[];
 export declare function smokeModelForTool(tool: string): string | undefined;
 export declare function samplingOverridesForModel(model: string): Readonly<Record<string, number>>;
 export declare function chatTemplateKwargsForModel(model: string): Readonly<Record<string, boolean>> | undefined;
-export type RegistryModelPricing = {
-    inputPer1mTokens: number;
-    outputPer1mTokens: number;
-};
-export declare const PRICING_ALIASES: Readonly<Record<string, string>>;
-export declare const DEFAULT_MODEL_PRICING: Readonly<Record<string, RegistryModelPricing>>;
+export type { CostActualCall, CostActuals, CostBillingMode, CostEstimate, CostEstimateCall, CostModelPricing, CostServiceShape, CostTokenUsage } from "./services/cost/service.js";
+export { attributeModelCosts, CostService, CostServiceLive, estimateModelCosts, formatCostUsd, lookupModelPricing, makeCostService } from "./services/cost/service.js";
 export type LocalModelRole = "general" | "coder";
 export type LocalCatalogModel = {
     repo: string;

package/dist/index.js

@@ -6,7 +6,8 @@
  * panel presets are deliberately excluded.
  */
 import { REGISTRY } from "./generated/data.js";
-export { REGISTRY };
+import { DEFAULT_MODEL_PRICING, PRICING_ALIASES } from "./pricing.js";
+export { DEFAULT_MODEL_PRICING, PRICING_ALIASES, REGISTRY };
 export const PROVIDERS = REGISTRY.providers;
 export function providerDefaultBaseUrl(provider) {
     return PROVIDERS[provider]?.baseUrl;
@@ -97,11 +98,7 @@ export function chatTemplateKwargsForModel(model) {
     }
     return undefined;
 }
-export const PRICING_ALIASES = (REGISTRY.pricing.aliases ?? {});
-export const DEFAULT_MODEL_PRICING = {
-    ...REGISTRY.pricing.models,
-    ...REGISTRY.pricing.manualOverrides
-};
+export { attributeModelCosts, CostService, CostServiceLive, estimateModelCosts, formatCostUsd, lookupModelPricing, makeCostService } from "./services/cost/service.js";
 export const LOCAL_CATALOG_ENTRIES = REGISTRY.localCatalog
     .entries;
 export const PREFERRED_LOCAL_MODELS = REGISTRY.localCatalog.preferred;

package/dist/pricing.d.ts

@@ -0,0 +1,6 @@
+export type RegistryModelPricing = {
+    readonly inputPer1mTokens: number;
+    readonly outputPer1mTokens: number;
+};
+export declare const PRICING_ALIASES: Readonly<Record<string, string>>;
+export declare const DEFAULT_MODEL_PRICING: Readonly<Record<string, RegistryModelPricing>>;

package/dist/pricing.js

@@ -0,0 +1,6 @@
+import { REGISTRY } from "./generated/data.js";
+export const PRICING_ALIASES = (REGISTRY.pricing.aliases ?? {});
+export const DEFAULT_MODEL_PRICING = {
+    ...REGISTRY.pricing.models,
+    ...REGISTRY.pricing.manualOverrides
+};

package/dist/services/cost/service.d.ts

@@ -0,0 +1,66 @@
+import { Context, Effect, Layer } from "effect";
+export type CostBillingMode = "metered-api" | "subscription" | "upstream-managed" | "unknown";
+export type CostModelPricing = {
+    readonly inputPer1mTokens: number;
+    readonly outputPer1mTokens: number;
+    readonly currency?: string;
+};
+export type CostTokenUsage = {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+};
+export type CostEstimateCall = {
+    readonly model: string;
+    readonly callCount: number;
+    readonly maximumInputTokens?: number;
+    readonly maximumOutputTokens?: number;
+    readonly billingMode?: CostBillingMode;
+    readonly reasoningEffort?: string;
+};
+export type CostEstimate = {
+    readonly callCount: number;
+    readonly knownInputTokens: number;
+    readonly knownOutputTokens: number;
+    readonly unknownTokenCalls: number;
+    readonly maximumCostUsd?: number;
+    readonly knownPricedMaximumUsd: number;
+    readonly unpricedCalls: number;
+    readonly subscriptionUnitCalls: number;
+    readonly upstreamManagedCalls: number;
+    readonly unknownBillingCalls: number;
+    readonly unknowns: readonly string[];
+};
+export type CostActualCall = {
+    readonly model: string;
+    readonly usage?: CostTokenUsage;
+    readonly billingMode?: CostBillingMode;
+    readonly providerCostUsd?: number;
+};
+export type CostActuals = {
+    readonly callCount: number;
+    readonly knownInputTokens: number;
+    readonly knownOutputTokens: number;
+    readonly unknownTokenCalls: number;
+    readonly knownCostUsd?: number;
+    readonly knownPricedSubtotalUsd: number;
+    readonly unpricedCalls: number;
+    readonly subscriptionUnitCalls: number;
+    readonly upstreamManagedCalls: number;
+    readonly unknownBillingCalls: number;
+    readonly unknowns: readonly string[];
+};
+export type CostServiceShape = {
+    readonly lookupPricing: (model: string, overrides?: Readonly<Record<string, CostModelPricing>>) => Effect.Effect<CostModelPricing | undefined>;
+    readonly estimate: (calls: readonly CostEstimateCall[]) => Effect.Effect<CostEstimate>;
+    readonly actuals: (calls: readonly CostActualCall[]) => Effect.Effect<CostActuals>;
+};
+declare const CostService_base: Context.ServiceClass<CostService, "@velum-labs/routekit-registry/CostService", CostServiceShape>;
+export declare class CostService extends CostService_base {
+}
+export declare const estimateModelCosts: (calls: readonly CostEstimateCall[], overrides?: Readonly<Record<string, CostModelPricing>>) => CostEstimate;
+export declare const attributeModelCosts: (calls: readonly CostActualCall[], overrides?: Readonly<Record<string, CostModelPricing>>) => CostActuals;
+export declare const makeCostService: (overrides?: Readonly<Record<string, CostModelPricing>>) => CostService["Service"];
+export declare const CostServiceLive: Layer.Layer<CostService, never, never>;
+export declare const lookupModelPricing: (model: string, overrides?: Readonly<Record<string, CostModelPricing>>) => CostModelPricing | undefined;
+export declare const formatCostUsd: (amount: number, currency?: string) => string;
+export {};

package/dist/services/cost/service.js

@@ -0,0 +1,225 @@
+import { Context, Effect, Layer } from "effect";
+import { REGISTRY } from "../../generated/data.js";
+import { DEFAULT_MODEL_PRICING, PRICING_ALIASES } from "../../pricing.js";
+export class CostService extends Context.Service()("@velum-labs/routekit-registry/CostService") {
+}
+const DEFAULT_CURRENCY = "USD";
+const modelNames = (model) => [
+    model,
+    ...(model.includes("/") ? [model.slice(model.indexOf("/") + 1)] : [])
+];
+const lookupPricing = (model, overrides = {}) => {
+    const combined = {
+        ...DEFAULT_MODEL_PRICING,
+        ...overrides
+    };
+    for (const name of modelNames(model)) {
+        const direct = Object.entries(combined).find(([candidate]) => candidate.toLowerCase() === name.toLowerCase())?.[1];
+        if (direct !== undefined)
+            return direct;
+        const alias = Object.entries(PRICING_ALIASES).find(([candidate]) => candidate.toLowerCase() === name.toLowerCase())?.[1];
+        if (alias === undefined)
+            continue;
+        const resolved = Object.entries(combined).find(([candidate]) => candidate.toLowerCase() === alias.toLowerCase())?.[1];
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return undefined;
+};
+const dollars = (usage, pricing) => (usage.inputTokens * pricing.inputPer1mTokens +
+    usage.outputTokens * pricing.outputPer1mTokens) /
+    1_000_000;
+const addUnknown = (unknowns, value) => {
+    unknowns.add(value);
+};
+const validCallCount = (value) => Number.isSafeInteger(value) && value >= 0;
+const validTokenCount = (value) => value === undefined || (Number.isSafeInteger(value) && value >= 0);
+const billingModeOf = (model, mode, pricing) => {
+    if (mode !== undefined)
+        return mode;
+    const provider = model.split("/", 1)[0]?.toLowerCase();
+    if (provider !== undefined && provider in REGISTRY.subscriptions)
+        return "subscription";
+    if (provider !== undefined && provider in REGISTRY.providers)
+        return "metered-api";
+    return pricing === undefined ? "unknown" : "metered-api";
+};
+export const estimateModelCosts = (calls, overrides = {}) => {
+    let callCount = 0;
+    let knownInputTokens = 0;
+    let knownOutputTokens = 0;
+    let unknownTokenCalls = 0;
+    let maximumCostUsd = 0;
+    let pricedCalls = 0;
+    let unpricedCalls = 0;
+    let subscriptionUnitCalls = 0;
+    let upstreamManagedCalls = 0;
+    let unknownBillingCalls = 0;
+    const unknowns = new Set();
+    for (const call of calls) {
+        if (!validCallCount(call.callCount) ||
+            !validTokenCount(call.maximumInputTokens) ||
+            !validTokenCount(call.maximumOutputTokens)) {
+            throw new Error("cost estimate calls require non-negative safe integer counts");
+        }
+        callCount += call.callCount;
+        const pricing = lookupPricing(call.model, overrides);
+        const billingMode = billingModeOf(call.model, call.billingMode, pricing);
+        if (call.maximumInputTokens === undefined || call.maximumOutputTokens === undefined) {
+            unknownTokenCalls += call.callCount;
+            addUnknown(unknowns, `token bounds for ${call.model}`);
+        }
+        if (call.maximumInputTokens !== undefined) {
+            knownInputTokens += call.maximumInputTokens * call.callCount;
+        }
+        if (call.maximumOutputTokens !== undefined) {
+            knownOutputTokens += call.maximumOutputTokens * call.callCount;
+        }
+        if (call.reasoningEffort !== undefined) {
+            addUnknown(unknowns, `reasoning-token multiplier for ${call.model}:${call.reasoningEffort}`);
+        }
+        if (billingMode === "subscription") {
+            subscriptionUnitCalls += call.callCount;
+            continue;
+        }
+        if (billingMode === "upstream-managed") {
+            upstreamManagedCalls += call.callCount;
+            addUnknown(unknowns, `upstream-managed billing for ${call.model}`);
+            continue;
+        }
+        if (billingMode === "unknown") {
+            unknownBillingCalls += call.callCount;
+            addUnknown(unknowns, `billing mode for ${call.model}`);
+            continue;
+        }
+        if (pricing === undefined) {
+            unpricedCalls += call.callCount;
+            addUnknown(unknowns, `pricing for ${call.model}`);
+            continue;
+        }
+        pricedCalls += call.callCount;
+        if (call.maximumInputTokens !== undefined && call.maximumOutputTokens !== undefined) {
+            maximumCostUsd +=
+                dollars({
+                    inputTokens: call.maximumInputTokens,
+                    outputTokens: call.maximumOutputTokens
+                }, pricing) * call.callCount;
+        }
+    }
+    const allDollarCallsPriced = unpricedCalls === 0 &&
+        upstreamManagedCalls === 0 &&
+        unknownBillingCalls === 0 &&
+        unknownTokenCalls === 0 &&
+        unknowns.size === 0;
+    return {
+        callCount,
+        knownInputTokens,
+        knownOutputTokens,
+        unknownTokenCalls,
+        ...(allDollarCallsPriced && pricedCalls > 0 ? { maximumCostUsd } : {}),
+        knownPricedMaximumUsd: maximumCostUsd,
+        unpricedCalls,
+        subscriptionUnitCalls,
+        upstreamManagedCalls,
+        unknownBillingCalls,
+        unknowns: [...unknowns].sort()
+    };
+};
+export const attributeModelCosts = (calls, overrides = {}) => {
+    let knownInputTokens = 0;
+    let knownOutputTokens = 0;
+    let unknownTokenCalls = 0;
+    let knownCostUsd = 0;
+    let pricedCalls = 0;
+    let unpricedCalls = 0;
+    let subscriptionUnitCalls = 0;
+    let upstreamManagedCalls = 0;
+    let unknownBillingCalls = 0;
+    const unknowns = new Set();
+    for (const call of calls) {
+        if (!validTokenCount(call.usage?.inputTokens) ||
+            !validTokenCount(call.usage?.outputTokens) ||
+            (call.providerCostUsd !== undefined &&
+                (!Number.isFinite(call.providerCostUsd) || call.providerCostUsd < 0))) {
+            throw new Error("cost actuals require non-negative finite usage and cost values");
+        }
+        const pricing = lookupPricing(call.model, overrides);
+        const billingMode = billingModeOf(call.model, call.billingMode, pricing);
+        if (call.usage?.inputTokens === undefined || call.usage.outputTokens === undefined) {
+            unknownTokenCalls += 1;
+            addUnknown(unknowns, `observed token usage for ${call.model}`);
+        }
+        if (call.usage?.inputTokens !== undefined) {
+            knownInputTokens += call.usage.inputTokens;
+        }
+        if (call.usage?.outputTokens !== undefined) {
+            knownOutputTokens += call.usage.outputTokens;
+        }
+        if (call.providerCostUsd !== undefined) {
+            pricedCalls += 1;
+            knownCostUsd += call.providerCostUsd;
+            if (billingMode === "subscription")
+                subscriptionUnitCalls += 1;
+            continue;
+        }
+        if (billingMode === "subscription") {
+            subscriptionUnitCalls += 1;
+            continue;
+        }
+        if (billingMode === "upstream-managed") {
+            upstreamManagedCalls += 1;
+            addUnknown(unknowns, `upstream-managed billing for ${call.model}`);
+            continue;
+        }
+        if (billingMode === "unknown") {
+            unknownBillingCalls += 1;
+            addUnknown(unknowns, `billing mode for ${call.model}`);
+            continue;
+        }
+        const cost = call.usage?.inputTokens === undefined ||
+            call.usage.outputTokens === undefined ||
+            pricing === undefined
+            ? undefined
+            : dollars({
+                inputTokens: call.usage.inputTokens,
+                outputTokens: call.usage.outputTokens
+            }, pricing);
+        if (cost === undefined) {
+            unpricedCalls += 1;
+            addUnknown(unknowns, `actual cost for ${call.model}`);
+        }
+        else {
+            pricedCalls += 1;
+            knownCostUsd += cost;
+        }
+    }
+    const allDollarCallsPriced = unpricedCalls === 0 &&
+        upstreamManagedCalls === 0 &&
+        unknownBillingCalls === 0;
+    return {
+        callCount: calls.length,
+        knownInputTokens,
+        knownOutputTokens,
+        unknownTokenCalls,
+        ...(allDollarCallsPriced && pricedCalls > 0 ? { knownCostUsd } : {}),
+        knownPricedSubtotalUsd: knownCostUsd,
+        unpricedCalls,
+        subscriptionUnitCalls,
+        upstreamManagedCalls,
+        unknownBillingCalls,
+        unknowns: [...unknowns].sort()
+    };
+};
+export const makeCostService = (overrides = {}) => {
+    return CostService.of({
+        lookupPricing: (model, configuredOverrides) => Effect.succeed(lookupPricing(model, { ...overrides, ...configuredOverrides })),
+        estimate: (calls) => Effect.sync(() => estimateModelCosts(calls, overrides)),
+        actuals: (calls) => Effect.sync(() => attributeModelCosts(calls, overrides))
+    });
+};
+export const CostServiceLive = Layer.effect(CostService, Effect.sync(() => makeCostService()));
+export const lookupModelPricing = (model, overrides = {}) => lookupPricing(model, overrides);
+export const formatCostUsd = (amount, currency = DEFAULT_CURRENCY) => {
+    const digits = amount >= 1 ? 2 : 4;
+    return `${currency === "USD" ? "$" : ""}${amount.toFixed(digits)}${currency === "USD" ? "" : ` ${currency}`}`;
+};

package/dist/test/registry.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
-import { ACCOUNT_CONNECTORS, DEFAULT_MODEL_PRICING, GATEWAY_DEFAULT_MLX_MODEL, LOCAL_CATALOG_ENTRIES, LOCAL_PROBE_MODEL, PREFERRED_LOCAL_MODELS, REGISTRY, accountKindChoices, accountKindForCliproxyAuthType, providerDiscovery, resolveAccountConnector } from "../index.js";
+import { ACCOUNT_CONNECTORS, DEFAULT_MODEL_PRICING, GATEWAY_DEFAULT_MLX_MODEL, LOCAL_CATALOG_ENTRIES, LOCAL_PROBE_MODEL, PREFERRED_LOCAL_MODELS, REGISTRY, accountKindChoices, accountKindForCliproxyAuthType, attributeModelCosts, estimateModelCosts, lookupModelPricing, providerDiscovery, resolveAccountConnector } from "../index.js";
 const FORBIDDEN_PRODUCT = ["fu", "sion", "kit"].join("");
 test("neutral generated registry excludes product and panel data", () => {
     assert.equal("fusion" in REGISTRY, false);
@@ -38,6 +38,120 @@ test("neutral pricing and provider metadata remain available", () => {
     assert.equal(REGISTRY.providers.openrouter.discovery.extraHeaders["X-Title"], "RouteKit");
     assert.equal(REGISTRY.subscriptions.codex.defaultHeaders.originator, "routekit");
 });
+test("cost service centralizes lookup, estimates, and observed actuals", () => {
+    assert.deepEqual(lookupModelPricing("openai/gpt-5.5"), {
+        inputPer1mTokens: 1.25,
+        outputPer1mTokens: 10
+    });
+    const estimate = estimateModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            callCount: 2,
+            maximumInputTokens: 1_000,
+            maximumOutputTokens: 200,
+            reasoningEffort: "high"
+        }
+    ]);
+    assert.equal(estimate.callCount, 2);
+    assert.equal(estimate.knownInputTokens, 2_000);
+    assert.equal(estimate.knownOutputTokens, 400);
+    assert.equal(estimate.maximumCostUsd, undefined);
+    assert.equal(estimate.knownPricedMaximumUsd, 0.0065);
+    assert.deepEqual(estimate.unknowns, ["reasoning-token multiplier for openai/gpt-5.5:high"]);
+    const actuals = attributeModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            usage: { inputTokens: 1_000, outputTokens: 200 }
+        },
+        {
+            model: "codex/gpt-5.5-codex",
+            billingMode: "subscription",
+            usage: { inputTokens: 500, outputTokens: 100 }
+        }
+    ]);
+    assert.equal(actuals.callCount, 2);
+    assert.equal(actuals.knownInputTokens, 1_500);
+    assert.equal(actuals.knownOutputTokens, 300);
+    assert.equal(actuals.knownCostUsd, 0.00325);
+    assert.equal(actuals.knownPricedSubtotalUsd, 0.00325);
+    assert.equal(actuals.subscriptionUnitCalls, 1);
+});
+test("cost estimates scale with N and the candidate set", () => {
+    const once = estimateModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            callCount: 1,
+            maximumInputTokens: 1_000,
+            maximumOutputTokens: 200
+        }
+    ]);
+    const twice = estimateModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            callCount: 2,
+            maximumInputTokens: 1_000,
+            maximumOutputTokens: 200
+        }
+    ]);
+    const twoCandidates = estimateModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            callCount: 1,
+            maximumInputTokens: 1_000,
+            maximumOutputTokens: 200
+        },
+        {
+            model: "openai/gpt-4.1",
+            callCount: 1,
+            maximumInputTokens: 1_000,
+            maximumOutputTokens: 200
+        }
+    ]);
+    assert.equal(twice.callCount, once.callCount * 2);
+    assert.equal(twice.knownPricedMaximumUsd, once.knownPricedMaximumUsd * 2);
+    assert.equal(twoCandidates.callCount, once.callCount + 1);
+    assert.ok(twoCandidates.knownPricedMaximumUsd > once.knownPricedMaximumUsd);
+});
+test("cost service preserves explicit unknowns instead of inventing zero", () => {
+    const estimate = estimateModelCosts([
+        {
+            model: "openai/unlisted",
+            callCount: 3,
+            maximumInputTokens: 100,
+            maximumOutputTokens: 50
+        }
+    ]);
+    assert.equal(estimate.maximumCostUsd, undefined);
+    assert.equal(estimate.unpricedCalls, 3);
+    assert.deepEqual(estimate.unknowns, ["pricing for openai/unlisted"]);
+    const actuals = attributeModelCosts([{ model: "openai/unlisted" }]);
+    assert.equal(actuals.knownCostUsd, undefined);
+    assert.equal(actuals.unpricedCalls, 1);
+    assert.equal(actuals.unknownTokenCalls, 1);
+});
+test("cost actuals retain partial usage and provider-reported subscription cost", () => {
+    const partial = attributeModelCosts([
+        {
+            model: "openai/gpt-5.5",
+            usage: { inputTokens: 123 }
+        }
+    ]);
+    assert.equal(partial.knownInputTokens, 123);
+    assert.equal(partial.knownOutputTokens, 0);
+    assert.equal(partial.unknownTokenCalls, 1);
+    assert.equal(partial.knownCostUsd, undefined);
+    const providerReported = attributeModelCosts([
+        {
+            model: "codex/gpt-5.5-codex",
+            billingMode: "subscription",
+            usage: { inputTokens: 50, outputTokens: 10 },
+            providerCostUsd: 0.002
+        }
+    ]);
+    assert.equal(providerReported.knownCostUsd, 0.002);
+    assert.equal(providerReported.knownPricedSubtotalUsd, 0.002);
+    assert.equal(providerReported.subscriptionUnitCalls, 1);
+});
 test("account connector map resolves canonical kinds, aliases, and auth types", () => {
     // Native subscription kinds stay native; every native kind has full
     // subscription metadata in the subscriptions section.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-registry",
   "private": false,
-  "version": "1.3.2",
+  "version": "1.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -33,7 +33,8 @@
     "models"
   ],
   "dependencies": {
-    "@velum-labs/routekit-contracts": "1.3.2"
+    "effect": "4.0.0-rc.108",
+    "@velum-labs/routekit-contracts": "1.4.0"
   },
   "scripts": {
     "build": "tsc -b",