@cat-factory/spend 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/SpendService.d.ts

@@ -0,0 +1,43 @@
+import type { SpendStatus } from '@cat-factory/contracts';
+import type { AgentTokenUsage } from '@cat-factory/kernel';
+import type { Clock, IdGenerator } from '@cat-factory/kernel';
+import type { TokenUsageRepository } from '@cat-factory/kernel';
+import { type SpendPricing } from './pricing.js';
+export interface SpendServiceDependencies {
+    tokenUsageRepository: TokenUsageRepository;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    pricing: SpendPricing;
+}
+/** Details of a single metered LLM call, handed in by the execution engine. */
+export interface RecordUsageInput {
+    workspaceId: string;
+    executionId: string | null;
+    agentKind: string;
+    /** Model identifier as `provider:model` (as produced by AgentRunResult.model). */
+    model: string;
+    usage: AgentTokenUsage;
+}
+/**
+ * The spend safeguard. It meters token usage into a persistent ledger, prices
+ * each call into a single currency, and reports the current billing period's
+ * spend against the configured budget. The execution engine consults
+ * {@link isOverBudget} before every agent step and pauses when the budget is
+ * exhausted; the worker surfaces {@link status} so the frontend can warn.
+ */
+export declare class SpendService {
+    private readonly tokenUsageRepository;
+    private readonly idGenerator;
+    private readonly clock;
+    private readonly pricing;
+    constructor({ tokenUsageRepository, idGenerator, clock, pricing }: SpendServiceDependencies);
+    /** Parse a `provider:model` identifier into a {@link ModelRef}. */
+    private parseModel;
+    /** Meter and persist one LLM call; returns its estimated cost. */
+    record(input: RecordUsageInput): Promise<number>;
+    /** The current billing period's spend against the configured budget. */
+    status(): Promise<SpendStatus>;
+    /** Whether this period's spend has reached the budget (runs should pause). */
+    isOverBudget(): Promise<boolean>;
+}
+//# sourceMappingURL=SpendService.d.ts.map

package/dist/SpendService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendService.d.ts","sourceRoot":"","sources":["../src/SpendService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAE1D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,KAAK,YAAY,EAAiC,MAAM,cAAc,CAAA;AAE/E,MAAM,WAAW,wBAAwB;IACvC,oBAAoB,EAAE,oBAAoB,CAAA;IAC1C,WAAW,EAAE,WAAW,CAAA;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,YAAY,CAAA;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,eAAe,CAAA;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,wBAAwB,EAK1F;IAED,mEAAmE;IACnE,OAAO,CAAC,UAAU;IAMlB,kEAAkE;IAC5D,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrD;IAED,wEAAwE;IAClE,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,CAYnC;IAED,8EAA8E;IACxE,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAIrC;CACF"}

package/dist/SpendService.js

@@ -0,0 +1,66 @@
+import { estimateCost, startOfMonthUtc } from './pricing.js';
+/**
+ * The spend safeguard. It meters token usage into a persistent ledger, prices
+ * each call into a single currency, and reports the current billing period's
+ * spend against the configured budget. The execution engine consults
+ * {@link isOverBudget} before every agent step and pauses when the budget is
+ * exhausted; the worker surfaces {@link status} so the frontend can warn.
+ */
+export class SpendService {
+    tokenUsageRepository;
+    idGenerator;
+    clock;
+    pricing;
+    constructor({ tokenUsageRepository, idGenerator, clock, pricing }) {
+        this.tokenUsageRepository = tokenUsageRepository;
+        this.idGenerator = idGenerator;
+        this.clock = clock;
+        this.pricing = pricing;
+    }
+    /** Parse a `provider:model` identifier into a {@link ModelRef}. */
+    parseModel(model) {
+        const idx = model.indexOf(':');
+        if (idx === -1)
+            return { provider: model, model: '' };
+        return { provider: model.slice(0, idx), model: model.slice(idx + 1) };
+    }
+    /** Meter and persist one LLM call; returns its estimated cost. */
+    async record(input) {
+        const ref = this.parseModel(input.model);
+        const costEstimate = estimateCost(this.pricing, ref, input.usage);
+        await this.tokenUsageRepository.record({
+            id: this.idGenerator.next('tok'),
+            workspaceId: input.workspaceId,
+            executionId: input.executionId,
+            agentKind: input.agentKind,
+            provider: ref.provider,
+            model: ref.model,
+            inputTokens: input.usage.inputTokens,
+            outputTokens: input.usage.outputTokens,
+            costEstimate,
+            createdAt: this.clock.now(),
+        });
+        return costEstimate;
+    }
+    /** The current billing period's spend against the configured budget. */
+    async status() {
+        const periodStart = startOfMonthUtc(this.clock.now());
+        const totals = await this.tokenUsageRepository.totalsSince(periodStart);
+        return {
+            periodStart,
+            inputTokens: totals.inputTokens,
+            outputTokens: totals.outputTokens,
+            costSpent: totals.costEstimate,
+            costLimit: this.pricing.monthlyLimit,
+            currency: this.pricing.currency,
+            exceeded: totals.costEstimate >= this.pricing.monthlyLimit,
+        };
+    }
+    /** Whether this period's spend has reached the budget (runs should pause). */
+    async isOverBudget() {
+        const periodStart = startOfMonthUtc(this.clock.now());
+        const totals = await this.tokenUsageRepository.totalsSince(periodStart);
+        return totals.costEstimate >= this.pricing.monthlyLimit;
+    }
+}
+//# sourceMappingURL=SpendService.js.map

package/dist/SpendService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendService.js","sourceRoot":"","sources":["../src/SpendService.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAmB/E;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACN,oBAAoB,CAAsB;IAC1C,WAAW,CAAa;IACxB,KAAK,CAAO;IACZ,OAAO,CAAc;IAEtC,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAA4B;QACzF,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAA;QAChD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAED,mEAAmE;IAC3D,UAAU,CAAC,KAAa;QAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;QACrD,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAA;IACvE,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,MAAM,CAAC,KAAuB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACxC,MAAM,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QACjE,MAAM,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC;YACrC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;YAChC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW;YACpC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY;YACtC,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;SAC5B,CAAC,CAAA;QACF,OAAO,YAAY,CAAA;IACrB,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,MAAM;QACV,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC,WAAW,CAAC,CAAA;QACvE,OAAO;YACL,WAAW;YACX,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,SAAS,EAAE,MAAM,CAAC,YAAY;YAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY;YACpC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ;YAC/B,QAAQ,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY;SAC3D,CAAA;IACH,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,YAAY;QAChB,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC,WAAW,CAAC,CAAA;QACvE,OAAO,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,CAAA;IACzD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SpendService, type SpendServiceDependencies, type RecordUsageInput, } from './SpendService.js';
+export { type ModelPrice, type SpendPricing, DEFAULT_MODEL_PRICES, DEFAULT_MONTHLY_LIMIT_EUR, DEFAULT_SPEND_PRICING, priceFor, modelCostResolver, estimateCost, startOfMonthUtc, } from './pricing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,YAAY,EACZ,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACrB,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// Pricing tables and spend metering/gating for @cat-factory.
+export { SpendService, } from './SpendService.js';
+export { DEFAULT_MODEL_PRICES, DEFAULT_MONTHLY_LIMIT_EUR, DEFAULT_SPEND_PRICING, priceFor, modelCostResolver, estimateCost, startOfMonthUtc, } from './pricing.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EACL,YAAY,GAGb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAGL,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACrB,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/pricing.d.ts

@@ -0,0 +1,41 @@
+import type { ModelRef } from '@cat-factory/kernel';
+import type { AgentTokenUsage } from '@cat-factory/kernel';
+/** Price per 1M input/output tokens for one model. */
+export interface ModelPrice {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}
+export interface SpendPricing {
+    /** ISO 4217 currency all prices and budgets are expressed in. */
+    currency: string;
+    /** Budget for one billing period (a calendar month). */
+    monthlyLimit: number;
+    /** Per-model prices, keyed by `provider:model` then by bare `provider`. */
+    prices: Record<string, ModelPrice>;
+    /** Fallback price for any model without a specific or provider-level entry. */
+    defaultPrice: ModelPrice;
+}
+/**
+ * Built-in approximate EUR prices per 1M tokens. Keys are matched most-specific
+ * first: exact `provider:model`, then the bare `provider`, then `defaultPrice`.
+ */
+export declare const DEFAULT_MODEL_PRICES: Record<string, ModelPrice>;
+/** Default budget: roughly 100 EUR of tokens per calendar month. */
+export declare const DEFAULT_MONTHLY_LIMIT_EUR = 100;
+export declare const DEFAULT_SPEND_PRICING: SpendPricing;
+/** Resolve the price for a model, most-specific entry first. */
+export declare function priceFor(pricing: SpendPricing, ref: ModelRef): ModelPrice;
+/**
+ * A {@link ModelCostResolver}-shaped closure over a {@link SpendPricing}, for the
+ * model catalog to surface each model's informational list cost in the picker.
+ */
+export declare function modelCostResolver(pricing: SpendPricing): (ref: ModelRef) => {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    currency: string;
+};
+/** Cost of a single call's token usage, in the pricing currency. */
+export declare function estimateCost(pricing: SpendPricing, ref: ModelRef, usage: AgentTokenUsage): number;
+/** Start of the calendar month containing `epochMs`, in UTC (epoch ms). */
+export declare function startOfMonthUtc(epochMs: number): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAY1D,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAClC,+EAA+E;IAC/E,YAAY,EAAE,UAAU,CAAA;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAmD3D,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAA;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,GAAG,UAAU,CAMzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,EAAE,QAAQ,KAAK;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAS5F;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAMjG;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/dist/pricing.js

@@ -0,0 +1,96 @@
+/**
+ * Built-in approximate EUR prices per 1M tokens. Keys are matched most-specific
+ * first: exact `provider:model`, then the bare `provider`, then `defaultPrice`.
+ */
+export const DEFAULT_MODEL_PRICES = {
+    // Anthropic (list prices from the Claude model catalog, USD→EUR ~0.92).
+    'anthropic:claude-opus-4-8': { inputPerMillion: 4.6, outputPerMillion: 23 },
+    'anthropic:claude-sonnet-4-6': { inputPerMillion: 2.76, outputPerMillion: 13.8 },
+    'anthropic:claude-haiku-4-5': { inputPerMillion: 0.92, outputPerMillion: 4.6 },
+    anthropic: { inputPerMillion: 2.76, outputPerMillion: 13.8 },
+    // OpenAI (approximate list prices, USD→EUR ~0.92).
+    'openai:gpt-4o': { inputPerMillion: 2.3, outputPerMillion: 9.2 },
+    'openai:gpt-4o-mini': { inputPerMillion: 0.14, outputPerMillion: 0.55 },
+    // ChatGPT/Codex subscription models (informational list prices, USD→EUR ~0.92).
+    'openai:gpt-5.5-codex': { inputPerMillion: 4.6, outputPerMillion: 27.6 },
+    'openai:gpt-5.4-codex': { inputPerMillion: 2.3, outputPerMillion: 13.8 },
+    openai: { inputPerMillion: 0.14, outputPerMillion: 0.55 },
+    // Cloudflare Workers AI is billed per "neuron"; treat it as roughly free.
+    'workers-ai': { inputPerMillion: 0.1, outputPerMillion: 0.1 },
+    // DeepSeek V4 Pro runs on Workers AI but is a partner model billed at provider
+    // rates (served via Fireworks), not the near-free neuron rate above, so it needs
+    // its own entry. Approximate (USD→EUR ~0.92); tune via SPEND_MODEL_PRICES.
+    'workers-ai:deepseek/deepseek-v4-pro': { inputPerMillion: 0.5, outputPerMillion: 2 },
+    // Kimi K2.6 / K2.7 likewise run on Workers AI as partner models billed at Workers
+    // AI's published per-token rate, NOT the near-free `workers-ai` neuron rate — without
+    // these explicit entries a Cloudflare-Kimi run (the default coder) would fall back to
+    // 0.1/0.1 and meter as ~0.00. Cloudflare lists both at $0.95 in / $4.00 out per 1M
+    // (USD→EUR ~0.92); this is Cloudflare's marked-up rate, well above Moonshot's direct
+    // list (`moonshot:kimi-k2.6`). The spend table has no cached-input tier, so we use the
+    // standard cache-miss input rate. See workers-ai/platform/pricing. Tune via SPEND_MODEL_PRICES.
+    'workers-ai:@cf/moonshotai/kimi-k2.6': { inputPerMillion: 0.87, outputPerMillion: 3.68 },
+    'workers-ai:@cf/moonshotai/kimi-k2.7-code': { inputPerMillion: 0.87, outputPerMillion: 3.68 },
+    // DeepSeek API (approximate list prices for deepseek-chat, USD→EUR ~0.92).
+    'deepseek:deepseek-chat': { inputPerMillion: 0.26, outputPerMillion: 1.01 },
+    deepseek: { inputPerMillion: 0.26, outputPerMillion: 1.01 },
+    // Alibaba DashScope (approximate qwen3-max list prices, USD→EUR ~0.92).
+    'qwen:qwen3-max': { inputPerMillion: 1.1, outputPerMillion: 5.5 },
+    qwen: { inputPerMillion: 1.1, outputPerMillion: 5.5 },
+    // Moonshot AI direct (approximate kimi-k2.6 list prices, USD→EUR ~0.92).
+    'moonshot:kimi-k2.6': { inputPerMillion: 0.55, outputPerMillion: 2.3 },
+    moonshot: { inputPerMillion: 0.55, outputPerMillion: 2.3 },
+    // OpenRouter — a passthrough gateway billed at the underlying provider's rates (no
+    // per-token markup), so each curated model carries the upstream vendor's list price
+    // (USD→EUR ~0.92). Keyed by the OpenRouter `vendor/model` slug. The bare `openrouter`
+    // fallback is a mid-range guess for any uncatalogued slug — tune via SPEND_MODEL_PRICES.
+    'openrouter:anthropic/claude-opus-4.8': { inputPerMillion: 4.6, outputPerMillion: 23 },
+    'openrouter:google/gemini-3-pro': { inputPerMillion: 1.84, outputPerMillion: 11.04 },
+    'openrouter:openai/gpt-5.5': { inputPerMillion: 3.68, outputPerMillion: 22.08 },
+    'openrouter:deepseek/deepseek-chat': { inputPerMillion: 0.26, outputPerMillion: 1.01 },
+    'openrouter:meta-llama/llama-3.3-70b-instruct': { inputPerMillion: 0.12, outputPerMillion: 0.37 },
+    openrouter: { inputPerMillion: 1.84, outputPerMillion: 11.04 },
+    // LiteLLM — an operator-hosted gateway whose true cost depends entirely on the backend
+    // model it routes to, which we can't know here. Default to the generic fallback rate;
+    // operators should override per their routing via SPEND_MODEL_PRICES.
+    litellm: { inputPerMillion: 0.14, outputPerMillion: 0.55 },
+};
+/** Default budget: roughly 100 EUR of tokens per calendar month. */
+export const DEFAULT_MONTHLY_LIMIT_EUR = 100;
+export const DEFAULT_SPEND_PRICING = {
+    currency: 'EUR',
+    monthlyLimit: DEFAULT_MONTHLY_LIMIT_EUR,
+    prices: DEFAULT_MODEL_PRICES,
+    defaultPrice: { inputPerMillion: 0.14, outputPerMillion: 0.55 },
+};
+/** Resolve the price for a model, most-specific entry first. */
+export function priceFor(pricing, ref) {
+    return (pricing.prices[`${ref.provider}:${ref.model}`] ??
+        pricing.prices[ref.provider] ??
+        pricing.defaultPrice);
+}
+/**
+ * A {@link ModelCostResolver}-shaped closure over a {@link SpendPricing}, for the
+ * model catalog to surface each model's informational list cost in the picker.
+ */
+export function modelCostResolver(pricing) {
+    return (ref) => {
+        const price = priceFor(pricing, ref);
+        return {
+            inputPerMillion: price.inputPerMillion,
+            outputPerMillion: price.outputPerMillion,
+            currency: pricing.currency,
+        };
+    };
+}
+/** Cost of a single call's token usage, in the pricing currency. */
+export function estimateCost(pricing, ref, usage) {
+    const price = priceFor(pricing, ref);
+    return ((usage.inputTokens / 1_000_000) * price.inputPerMillion +
+        (usage.outputTokens / 1_000_000) * price.outputPerMillion);
+}
+/** Start of the calendar month containing `epochMs`, in UTC (epoch ms). */
+export function startOfMonthUtc(epochMs) {
+    const d = new Date(epochMs);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+}
+//# sourceMappingURL=pricing.js.map

package/dist/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cat-factory/spend",
+  "version": "0.6.0",
+  "description": "Pricing tables and spend metering for the Agent Architecture Board.",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cat-factory/contracts": "0.6.0",
+    "@cat-factory/kernel": "0.6.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.1-rc"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}