A local-first multi-agent app development platform, built on PenguinHarness
feat(server): 用量成本在写入用量行时就定格
lmliheng6c30e14aca46
diff --git a/changelog/unreleased/2026-10-08-usage-cost-at-record-time.md b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.mdnew file mode 100644index 00000000..1d1ee415--- /dev/null+++ b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.md@@ -0,0 +1,62 @@+# A request's cost is fixed when its usage row is written++- **Date:** 2026-10-08+- **Type:** feature+- **Scope:** `server`+- **Breaking:** yes — a price change no longer re-prices usage already recorded++[中文版](2026-10-08-usage-cost-at-record-time.zh.md)++Each usage record now carries the cost of the Request it summarises, fixed at the moment the row is+written, at the price the Project stores for that paired reference then. Editing a price, running+**Sync presets**, or a promotion starting or ending changes only what later Requests cost: the cost+center, the conversation toolbar, `penguin cost` and company-mode budgets sum the stored costs, and+none of their queries looks a price up any more.++## Server++- `db/schema.ts` and migration **14** `usage-record-cost` add `cost` (REAL; NULL = the model has no+ price) and `cost_settled` (INTEGER, default 0) to `usage_records`, via `ensureColumn` so a+ declarative-track database that already has them is untouched. The migration deliberately does not+ cost the rows already there: pricing them needs each Project's config, which SQLite does not have.+- `db/repos/usage.ts`: `insert` writes both columns; the aggregates sum `cost` and count `uncosted`+ instead of returning raw Token sums, so a group's cost is the bill and `hasUncosted` still flags a+ lower bound. `unsettledRefs` / `unsettledRows` / `settle` drive the one-time compatibility pass.+- `runtime/usage-recorder.ts` prices each row from `ProjectConfigStore.getPricing(projectId,+ provider, modelId, at)` at its own clock's instant, and takes that as the bill. A price that+ cannot be read counts as no price: the row is written anyway, since losing the Tokens would be+ worse than not costing them.+- `services/project-config-service.ts`: `getPricing` now takes the instant and returns the one rate+ in force then — the stored price, less the row's promotion, at the tier that instant falls in+ (`scheduledRateAt`, next to the existing `promotedRates`). A hand-typed price is billed as typed in+ both tiers: nothing here knows whether it is a peak rate, and halving it would invent a discount.+- `services/usage-service.ts`: the queries no longer price anything; a row's cost is what the+ recorder fixed. `lifetimeCost` (the admin backend's per-account cost column) is the same recorded+ sum, one unfiltered grouped scan.+- `services/trace-service.ts`: the Trace page is unchanged in kind — it still prices each Request at+ the Project's current price, at that Request's own timestamp (memoized per hour and reference), so+ after a price change it can differ from the cost center, which stays the bill.++## Compatibility++Rows written before this change carry no cost. `Startup` settles them once, before anything reads the+cost center (`UsageService.settleUnsettledCosts`, idempotent, keyed on `cost_settled`), at the price+each Project stores now and at the tier each row's own timestamp fell in. A failure is recorded+(`usage_cost_settle_failed`) rather than thrown, and those rows then read as uncosted until a later+boot. Remove `cost_settled` and the settle two releases after this one.++## Deliberately not adopted from upstream++This is upstream's `feat/usage-cost-at-record-time`, still unmerged, of which only the server half is+taken — in this tree the per-row promotion lives in `web.db`'s `model_promotions` table, which the+core process cannot read, so core cannot stamp the rate a Request was billed at on its `token_usage`+event. Left out, with the reason:++- Core's `token_usage.pricing` stamp and the `resolveBilledPricing` / `billedRates` helpers that read+ it. With the promotion in `web.db`, core sees only the file's list price, so a stamped rate would+ bill every promoted row at full price.+- The catalog's `discountUntil` / `discountRateAt`. A promotion here is a row in `model_promotions`+ with no end instant, so a time-bounded discount has nowhere to live yet.++The complete version of this feature would move the promotion into the Project's own config beside+the list price and let core stamp the rate. That is a product decision, not a mechanical port.diff --git a/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.md b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.mdnew file mode 100644index 00000000..84a82971--- /dev/null+++ b/changelog/unreleased/2026-10-08-usage-cost-at-record-time.zh.md@@ -0,0 +1,54 @@+# 请求成本在写入用量行时就定格++- **Date:** 2026-10-08+- **Type:** feature+- **Scope:** `server`+- **Breaking:** yes — 改价不再重算已记录的用量++[English](2026-10-08-usage-cost-at-record-time.md)++每条用量记录现在都带上它所代表那次请求的成本,在写入这一行的那一刻、按 Project 当时为这个+provider/model 组合存下的价格定格。改价、执行**同步预置**、促销开始或结束,都只影响之后的请求:+成本中心、对话页工具栏、`penguin cost` 与公司模式预算都改为加总存下的成本,查询时一律不再取价。++## 服务端++- `db/schema.ts` 与迁移 **14** `usage-record-cost` 给 `usage_records` 加上 `cost`(REAL,+ NULL = 该模型没有价格)与 `cost_settled`(INTEGER,默认 0),走 `ensureColumn` —— 声明式那条+ 轨道已经加过这两列的库不受影响。迁移本身**有意不给已有行算成本**:算它要读每个 Project 的配置,+ SQLite 里没有。+- `db/repos/usage.ts`:`insert` 同时写入这两列;聚合改为对 `cost` 求和、统计 `uncosted`,不再返回+ 原始 token 汇总 —— 于是每组的成本就是账单,`hasUncosted` 仍然说明它只是下限。+ `unsettledRefs` / `unsettledRows` / `settle` 支撑那一次性的兼容补算。+- `runtime/usage-recorder.ts` 按自己的时钟时刻调用 `ProjectConfigStore.getPricing(projectId,+ provider, modelId, at)` 给每一行定价,并把它当作账单。取价失败按「没有价格」处理:这一行照写,+ 丢掉 token 比不记账更糟。+- `services/project-config-service.ts`:`getPricing` 现在多收一个时刻,返回那一刻实际生效的单一费率+ —— 存下的价格、扣掉该行的促销、再按那一刻落在的分时段档位折算(新增的 `scheduledRateAt`,与既有的+ `promotedRates` 并列)。手工改过的价格在两个档位都按原样计费:这里并不知道它是不是高峰价,+ 减半等于凭空造出一个折扣。+- `services/usage-service.ts`:查询不再做任何定价,成本就是 recorder 定格的那个数。`lifetimeCost`+ (管理后台每账号的开销列)也是同一个「已记录成本」求和,一句不带筛选的分组扫描。+- `services/trace-service.ts`:Trace 页的性质不变 —— 仍按 Project 当前价格、以每个请求自己的+ 时间戳定价(按小时与 provider/model 记忆化),所以改价之后它可以与成本中心不同,而账单以成本中心为准。++## 兼容性++升级前的用量记录没有成本。`Startup` 会在任何东西读取成本中心之前补算一次+(`UsageService.settleUnsettledCosts`,幂等,以 `cost_settled` 为准):按每个 Project **现在**存的价格、+按每一行自己时间戳所在的档位。失败会被记进错误表(`usage_cost_settle_failed`)而不是抛出,+那些行在此后的一次启动前一直读作「未计价」。这个补算与 `cost_settled` 列在本版之后两个发布上移除。++## 有意未采用的上游部分++这条来自上游尚未合入的 `feat/usage-cost-at-record-time`,只取了服务端那一半 —— 在我们的树里,+逐行促销存在 `web.db` 的 `model_promotions` 表里,core 进程读不到,因此 core 无法把一次请求实际+计费的单价盖在它的 `token_usage` 事件上。未采用的部分与理由:++- core 的 `token_usage.pricing` 戳记,以及读它的 `resolveBilledPricing` / `billedRates`。促销在+ `web.db` 里,core 只看得到文件里的牌价,盖上的费率会把每一行促销模型都按原价计费。+- 目录的 `discountUntil` / `discountRateAt`。这里的促销是 `model_promotions` 里的一行、没有截止时刻,+ 带时限的折扣暂时无处安放。++这个功能的完整形态是把促销搬进 Project 自己的配置、与牌价并排存放,再由 core 盖戳费率。+那是一个产品决定,不是一次机械移植。diff --git a/packages/server/src/db/migrations.ts b/packages/server/src/db/migrations.tsindex 33c921e9..d93cd489 100644--- a/packages/server/src/db/migrations.ts+++ b/packages/server/src/db/migrations.ts@@ -554,6 +554,33 @@ export const MIGRATIONS: readonly Migration[] = [db.exec(`DROP TABLE IF EXISTS org_desk_mentions;`);},},+ {+ version: 14,+ name: "usage-record-cost",+ // Two columns with defaults on usage_records, nothing existing rewritten: a platform rolled+ // back to a predecessor that does not know them keeps inserting rows without a cost, which+ // simply read unsettled (cost_settled 0) and are settled by the next build that boots.+ swapSafe: true,+ up(db) {+ // Frozen copy of the DDL as of fixing a request's cost at record time; do not re-derive+ // from schema.ts. ensureColumn because the declarative track may already have added them+ // (ADOPTION). The rows already in the table are costed by the startup settle+ // (UsageService.settleUnsettledCosts), not here: pricing them needs each Project's config.+ ensureColumn(db, "usage_records", "cost", "REAL");+ ensureColumn(db, "usage_records", "cost_settled", "INTEGER NOT NULL DEFAULT 0");+ },+ // LOSES every fixed cost. A build with this migration adds the columns back unsettled and+ // costs every row again at startup, at the prices the Projects store by then — so a price+ // changed in between re-prices history, the one thing the columns exist to prevent.+ // Dropped in reverse order for symmetry with `up`; neither column is indexed, which is what+ // lets SQLite drop them at all.+ down(db) {+ const cols = db.prepare("PRAGMA table_info(usage_records)").all() as { name: string }[];+ const has = (name: string): boolean => cols.some((c) => c.name === name);+ if (has("cost_settled")) db.exec("ALTER TABLE usage_records DROP COLUMN cost_settled");+ if (has("cost")) db.exec("ALTER TABLE usage_records DROP COLUMN cost");+ },+ },];/** The highest version this build knows how to reach. */diff --git a/packages/server/src/db/repos/usage.ts b/packages/server/src/db/repos/usage.tsindex f34f5f35..a45a0fe2 100644--- a/packages/server/src/db/repos/usage.ts+++ b/packages/server/src/db/repos/usage.ts@@ -1,9 +1,9 @@/*** usage_records table repo:- * one row per token_usage (per-request bucket). Stores Token counts only, not cost —- * cost is computed on the fly by usage-service against current pricing at query time,- * so every aggregation is broken down by the `(provider, model_id)` pair and returns- * raw Token sums (a model_id shared across providers is aggregated separately; never concatenated).+ * one row per token_usage (per-request bucket), with the Request's cost fixed when the row is+ * written (see usage-recorder) — no aggregation re-prices anything, it sums what was recorded.+ * Every aggregation is still broken down by the `(provider, model_id)` pair (a model_id shared+ * across providers is aggregated separately; never concatenated).*/import type { UsageGroupBy } from "../../api/types.js";import { Component, Use } from "@lmliheng/penguin-core/kernel";@@ -27,6 +27,8 @@ export interface UsageRecordInsert {total: number;/** Request outcome; defaults to completed (success, carries tokens). Failed requests are stored with 0 tokens + status, for success-rate calculations. */status?: string;+ /** The Request's cost in USD, fixed now and never re-derived; null = the model had no price. */+ cost: number | null;}/** Generic filter: date range + agent / model dimensions (cost center top bar switches by agent/model). */@@ -53,26 +55,19 @@ export interface UsageModelSums {output: number;total: number;requests: number;- /**- * Which tier of a time-based price these Tokens ran in, decided from each record's own `ts`.- *- * A model with no schedule has one price and every row reports `true`. A scheduled one is- * summed into two rows per reference, so a week that straddles the boundary is priced at the- * rate each request actually ran at — rather than at whichever tier happens to be in force- * when someone opens the page, which would move a finished week's cost twice a day.- */- peak: boolean;+ /** Sum of the recorded costs (USD); null when no row in the group has one. */+ cost: number | null;+ /** Rows in the group with no recorded cost — the model had no price — which makes `cost` a lower bound. */+ uncosted: number;}-/** A time-based price to split an aggregation by: which references carry it, and when it is peak. */-export interface PeakTier {- refs: ReadonlyArray<{ provider: string; modelId: string }>;- /** Minutes east of UTC the schedule's local hours are written in. */- utcOffsetMinutes: number;- /** ISO weekday numbers the windows apply to; a day not listed is off-peak throughout. */- peakDays: readonly number[];- /** `[startHour, endHour)` in the schedule's own local hours. */- peakHours: readonly (readonly [number, number])[];+/** One usage row still waiting for its cost (see UsageRepo.unsettledRows). */+export interface UnsettledUsageRow {+ id: number;+ ts: string;+ cacheRead: number;+ cacheWrite: number;+ output: number;}/** Raw Token sums by group key x Model. */@@ -131,57 +126,25 @@ const GROUP_COLUMNS: Record<UsageGroupBy, string> = {session: "session_id",};-/**- * A `1`/`0` expression naming the tier a row's own `ts` fell in, for the references that have- * one; every other row is `1`, the single price it has.- *- * Written from the schedule rather than hardcoded so a second vendor's windows cost one more- * entry and no more SQL. The hours compare as integers because a window boundary is a whole- * hour in every schedule the catalog can express; a half-hour boundary would need the minutes.- * Literals only — the numbers come from the catalog and the references are bound.- */-function peakExpr(tiers: readonly PeakTier[]): { sql: string; params: Record<string, string> } {- if (tiers.length === 0) return { sql: "1", params: {} };- const params: Record<string, string> = {};- const branches: string[] = [];- tiers.forEach((tier, ti) => {- if (tier.refs.length === 0 || tier.peakDays.length === 0) return;- const shift = `'${tier.utcOffsetMinutes >= 0 ? "+" : "-"}${Math.abs(tier.utcOffsetMinutes)} minutes'`;- const refs = tier.refs.map((ref, ri) => {- const p = `t${ti}p${ri}`;- const m = `t${ti}m${ri}`;- params[p] = ref.provider;- params[m] = ref.modelId;- return `(provider = :${p} AND model_id = :${m})`;- });- // `%w` is 0=Sunday; the schedule counts ISO days, so Sunday maps to 7.- const day = `CASE CAST(strftime('%w', ts, ${shift}) AS INTEGER) WHEN 0 THEN 7 ELSE CAST(strftime('%w', ts, ${shift}) AS INTEGER) END`;- const hour = `CAST(strftime('%H', ts, ${shift}) AS INTEGER)`;- const windows = tier.peakHours.map(([from, to]) => `(${hour} >= ${from} AND ${hour} < ${to})`);- branches.push(- `WHEN (${refs.join(" OR ")}) THEN (CASE WHEN ${day} IN (${tier.peakDays.join(", ")}) AND (${windows.join(" OR ")}) THEN 1 ELSE 0 END)`,- );- });- if (branches.length === 0) return { sql: "1", params: {} };- return { sql: `CASE ${branches.join(" ")} ELSE 1 END`, params };-}-const SUM_COLUMNS = `COALESCE(SUM(cache_read), 0) AS cache_read,COALESCE(SUM(cache_write), 0) AS cache_write,COALESCE(SUM(output), 0) AS output,COALESCE(SUM(total), 0) AS total,- COUNT(*) AS requests`;+ COUNT(*) AS requests,+ SUM(cost) AS cost,+ COUNT(*) - COUNT(cost) AS uncosted`;function toSums(r: Record<string, unknown>): UsageModelSums {return {provider: r.provider as string,modelId: r.model_id as string,- peak: r.peak !== 0,cacheRead: r.cache_read as number,cacheWrite: r.cache_write as number,output: r.output as number,total: r.total as number,requests: r.requests as number,+ cost: r.cost === null || r.cost === undefined ? null : (r.cost as number),+ uncosted: r.uncosted as number,};}@@ -194,8 +157,8 @@ export class UsageRepo implements UsageStore {.prepare(`INSERT INTO usage_records(ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id,- cache_read, cache_write, output, total, status)- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,+ cache_read, cache_write, output, total, status, cost, cost_settled)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)`,).run(r.ts,@@ -211,9 +174,60 @@ export class UsageRepo implements UsageStore {r.output,r.total,r.status ?? "completed",+ r.cost,);}+ /**+ * The paired references (per Project) that still have rows without a fixed cost: rows written+ * before costs were fixed at record time, or by an older build a hot update rolled back to.+ */+ unsettledRefs(): Array<{ projectId: string; provider: string; modelId: string }> {+ const rows = this.db+ .prepare(+ `SELECT DISTINCT project_id, provider, model_id FROM usage_records WHERE cost_settled = 0`,+ )+ .all();+ return rows.map((r) => ({+ projectId: r.project_id as string,+ provider: r.provider as string,+ modelId: r.model_id as string,+ }));+ }++ /** One reference's rows still without a fixed cost, with what pricing them needs. */+ unsettledRows(projectId: string, provider: string, modelId: string): UnsettledUsageRow[] {+ const rows = this.db+ .prepare(+ `SELECT id, ts, cache_read, cache_write, output FROM usage_records+ WHERE cost_settled = 0 AND project_id = ? AND provider = ? AND model_id = ?`,+ )+ .all(projectId, provider, modelId);+ return rows.map((r) => ({+ id: r.id as number,+ ts: r.ts as string,+ cacheRead: r.cache_read as number,+ cacheWrite: r.cache_write as number,+ output: r.output as number,+ }));+ }++ /** Fixes the given rows' costs in one transaction; a row settled in the meantime is left alone. */+ settle(rows: ReadonlyArray<{ id: number; cost: number | null }>): void {+ if (rows.length === 0) return;+ const stmt = this.db.prepare(+ "UPDATE usage_records SET cost = ?, cost_settled = 1 WHERE id = ? AND cost_settled = 0",+ );+ this.db.exec("BEGIN IMMEDIATE");+ try {+ for (const r of rows) stmt.run(r.cost, r.id);+ this.db.exec("COMMIT");+ } catch (err) {+ this.db.exec("ROLLBACK");+ throw err;+ }+ }+/** WHERE fragment (project + optional date/agent/model) plus named params. */private conds(projectId: string,@@ -263,24 +277,16 @@ export class UsageRepo implements UsageStore {return { where: conds.join(" AND "), params };}- /**- * Sums (broken down by paired reference, and by price tier where one applies): date range +- * optional agent/model filter.- */- bucketByModel(- projectId: string,- f: UsageFilter = {},- tiers: readonly PeakTier[] = [],- ): UsageModelSums[] {+ /** Sums (broken down by paired reference): date range + optional agent/model filter. */+ bucketByModel(projectId: string, f: UsageFilter = {}): UsageModelSums[] {const { where, params } = this.conds(projectId, f);- const peak = peakExpr(tiers);const rows = this.db.prepare(- `SELECT provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS}+ `SELECT provider, model_id, ${SUM_COLUMNS}FROM usage_records WHERE ${where}- GROUP BY provider, model_id, peak`,+ GROUP BY provider, model_id`,)- .all({ ...params, ...peak.params });+ .all(params);return rows.map(toSums);}@@ -289,18 +295,16 @@ export class UsageRepo implements UsageStore {projectId: string,groupBy: UsageGroupBy,f: UsageFilter = {},- tiers: readonly PeakTier[] = [],): UsageGroupModelSums[] {const col = GROUP_COLUMNS[groupBy];const { where, params } = this.conds(projectId, f);- const peak = peakExpr(tiers);const rows = this.db.prepare(- `SELECT ${col} AS key, provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS}+ `SELECT ${col} AS key, provider, model_id, ${SUM_COLUMNS}FROM usage_records WHERE ${where}- GROUP BY ${col}, provider, model_id, peak`,+ GROUP BY ${col}, provider, model_id`,)- .all({ ...params, ...peak.params });+ .all(params);return rows.map((r) => ({ key: r.key as string, ...toSums(r) }));}@@ -314,20 +318,18 @@ export class UsageRepo implements UsageStore {projectId: string,granularity: UsageSeriesGranularity,f: UsageFilter = {},- tiers: readonly PeakTier[] = [],): UsageSeriesModelSums[] {const expr = BUCKET_EXPRS[granularity];const { where, params } = this.conds(projectId, f);- const peak = peakExpr(tiers);const rows = this.db.prepare(- `SELECT ${expr} AS key, provider, model_id, ${peak.sql} AS peak, ${SUM_COLUMNS},+ `SELECT ${expr} AS key, provider, model_id, ${SUM_COLUMNS},COALESCE(SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END), 0) AS completed,COALESCE(SUM(CASE WHEN status <> 'aborted' THEN 1 ELSE 0 END), 0) AS denominatorFROM usage_records WHERE ${where}- GROUP BY key, provider, model_id, peak`,+ GROUP BY key, provider, model_id`,)- .all({ ...params, ...peak.params });+ .all(params);return rows.map((r) => ({key: r.key as string,...toSums(r),diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.tsindex 1cc2d24a..b9a0068e 100644--- a/packages/server/src/db/schema.ts+++ b/packages/server/src/db/schema.ts@@ -110,8 +110,10 @@ CREATE TABLE IF NOT EXISTS usage_records (cache_write INTEGER NOT NULL,output INTEGER NOT NULL,total INTEGER NOT NULL, -- from token_usage.request (one row per Request)- status TEXT NOT NULL DEFAULT 'completed' -- request outcome: completed=success (with tokens); others=failure (0 tokens, for success rate)-); -- cost is not stored: computed at query time from current pricing+ status TEXT NOT NULL DEFAULT 'completed', -- request outcome: completed=success (with tokens); others=failure (0 tokens, for success rate)+ cost REAL, -- USD, fixed by the recorder when the row is written, from the price the Project stores at that instant; NULL = the model has no price (or the row is not settled yet)+ cost_settled INTEGER NOT NULL DEFAULT 0 -- 1 once cost is fixed; 0 = written by a build that did not price rows (settled once at startup)+); -- rebuildable from the Traces: the token counts still come from token_usageCREATE INDEX IF NOT EXISTS idx_usage_project_date ON usage_records(project_id, date);CREATE INDEX IF NOT EXISTS idx_usage_session_ts ON usage_records(session_id, ts); -- (session_id) alone was idx_usage_session (dropped on open): ts makes the last_active_at backfill's MAX(ts) a covering index scan instead of a random row lookup per usage recordCREATE TABLE IF NOT EXISTS error_records ( -- server-side error capture (the Costs page's "Errors" tab)diff --git a/packages/server/src/mechanisms/observability.ts b/packages/server/src/mechanisms/observability.tsindex 9f84ddcc..eca4a6b7 100644--- a/packages/server/src/mechanisms/observability.ts+++ b/packages/server/src/mechanisms/observability.ts@@ -19,7 +19,7 @@ import type {UsageRecordInsert,UsageSeriesGranularity,UsageSeriesModelSums,- PeakTier,+ UnsettledUsageRow,} from "../db/repos/usage.js";import type {UsageErrorsPage,@@ -90,22 +90,19 @@ export abstract class Errors {@Interface()export abstract class UsageStore {abstract insert(r: UsageRecordInsert): void;- abstract bucketByModel(- projectId: string,- f?: UsageFilter,- tiers?: readonly PeakTier[],- ): UsageModelSums[];+ abstract unsettledRefs(): Array<{ projectId: string; provider: string; modelId: string }>;+ abstract unsettledRows(projectId: string, provider: string, modelId: string): UnsettledUsageRow[];+ abstract settle(rows: ReadonlyArray<{ id: number; cost: number | null }>): void;+ abstract bucketByModel(projectId: string, f?: UsageFilter): UsageModelSums[];abstract groupsByModel(projectId: string,groupBy: UsageGroupBy,f?: UsageFilter,- tiers?: readonly PeakTier[],): UsageGroupModelSums[];abstract seriesByModel(projectId: string,granularity: UsageSeriesGranularity,f?: UsageFilter,- tiers?: readonly PeakTier[],): UsageSeriesModelSums[];abstract agentSeries(projectId: string,@@ -130,10 +127,12 @@ export abstract class UsageQueries {abstract queryErrors(projectId: string, q: UsageErrorsQuery): UsageErrorsPage;abstract clearErrors(projectId: string, q: UsageErrorsClearQuery): number;abstract modelTotals(projectId: string): UsageModelTotals;+ /** Fixes the cost of every usage row that has none yet; returns how many it settled. */+ abstract settleUnsettledCosts(): Promise<number>;/**- * The Project's lifetime cost: every usage record it ever wrote, folded with the same- * per-reference rate lookup `query` uses (current prices). `unpriced` says some of that usage- * ran on a model this Project has no price for, so `cost` is a lower bound.+ * The Project's lifetime cost: every usage record it ever wrote, summed from the costs fixed+ * when the rows were written. `unpriced` says some of that usage ran on a model this Project+ * has no price for, so `cost` is a lower bound.*/abstract lifetimeCost(projectId: string,diff --git a/packages/server/src/mechanisms/projects.ts b/packages/server/src/mechanisms/projects.tsindex 75d38e11..bb5ee84f 100644--- a/packages/server/src/mechanisms/projects.ts+++ b/packages/server/src/mechanisms/projects.ts@@ -33,7 +33,7 @@ import type {PluginTables,ProjectConfig,} from "@lmliheng/penguin-core";-import type { TieredRates } from "../services/usage-service.js";+import type { PricingRates } from "../services/usage-service.js";import type {PlatformModelApplyResult,PlatformModelCatalog,@@ -145,7 +145,8 @@ export abstract class ProjectConfigStore {projectId: string,provider: string,modelId: string,- ): Promise<TieredRates | undefined>;+ at: Date,+ ): Promise<PricingRates | undefined>;abstract detectVision(projectId: string,req: ModelVisionDetectRequest,diff --git a/packages/server/src/platform.ts b/packages/server/src/platform.tsindex 56aff570..fc0c13fd 100644--- a/packages/server/src/platform.ts+++ b/packages/server/src/platform.ts@@ -198,6 +198,7 @@ export class Startup {@Use() private readonly machines!: Machines;@Use() private readonly errors!: Errors;@Use() private readonly projectConfig!: ProjectConfigStore;+ @Use() private readonly usage!: UsageQueries;async setup() {// The shared default Project's display name, on every start rather than only where it is@@ -206,6 +207,15 @@ export class Startup {// showing the raw id as the Project's label. Idempotent and file-guarded — a root without// that Project's config file is untouched, so nothing is ever created here.await this.projectConfig.ensureDisplayName(DEFAULT_PROJECT_ID, DEFAULT_PROJECT_NAME);+ // Usage rows with no fixed cost yet — from before costs were fixed at record time, or+ // written by an older build a hot update rolled back to — are costed once, before anything+ // reads the cost center (COMPATIBILITY: see UsageService.settleUnsettledCosts). Awaited, but+ // a failure is recorded rather than thrown: the rows then read as uncosted until a later boot.+ try {+ await this.usage.settleUnsettledCosts();+ } catch (err) {+ this.errors.record({ source: "process", err, code: "usage_cost_settle_failed" });+ }// Schedule scheduler: startup reconciliation (missed, don't backfill) + periodic scan.await this.scheduler.start();// Company mode's scheduler: same lifetime and the same startup rule (reconcile once,diff --git a/packages/server/src/runtime/usage-recorder.ts b/packages/server/src/runtime/usage-recorder.tsindex 5664e971..47cb76c5 100644--- a/packages/server/src/runtime/usage-recorder.ts+++ b/packages/server/src/runtime/usage-recorder.ts@@ -7,9 +7,14 @@* cost is priced against the actual Model used);* - `token_usage` → inserts one usage_records row: the four token fields come from* `payload.request` (per-Request increment; subagents are recorded one row at a- * time, with `session_id` attributed to their owning main Session). Only tokens are- * persisted, not cost — pricing may be added later, and cost is computed on the fly- * against current pricing when usage-service queries.+ * time, with `session_id` attributed to their owning main Session), and the Request's+ * cost is FIXED here, from the price the Project stores for that paired reference at+ * this instant. Nothing re-prices a row afterwards: a later price edit, preset sync or+ * promotion only changes what later Requests cost.+ *+ * The price is read from the Project's own config (getPricing, which folds in the row's+ * promotion), not from the rates a `token_usage` event may carry: a promotion lives in+ * web.db beside the file's list price, so only this side can state what a Request was billed.* The attribution key is always the paired reference `(provider, model_id)` (the same* model_id name across different vendors is attributed separately).*/@@ -19,6 +24,9 @@ import { formatLocalDate } from "../internal/dates.js";import { Component, Use } from "@lmliheng/penguin-core/kernel";import type { Clock } from "../hmr/capabilities.js";import type { UsageRecording, UsageStore } from "../mechanisms/observability.js";+import type { ProjectConfigStore } from "../mechanisms/projects.js";+import { requestCostUsd } from "../services/usage-service.js";+import type { PricingLookup } from "../services/usage-service.js";/** Attribution context for one record (top-level Session scope). */export interface UsageContext {@@ -42,6 +50,30 @@ export class UsageRecorder implements UsageRecording {@Use() private readonly usage!: UsageStore;@Use() private readonly clock!: Clock;+ @Use() private readonly projectConfig!: ProjectConfigStore;+ private lookupPricing: PricingLookup = (projectId, provider, modelId, at) =>+ this.projectConfig.getPricing(projectId, provider, modelId, at);++ /**+ * A record's cost, fixed now: the three buckets at the price the Project stores for this+ * reference at this instant — `null` when it stores none (an uncosted model). A price that+ * cannot be read counts as no price: the row is written either way, since losing the Tokens+ * would be worse than not costing them.+ */+ private async costOf(+ projectId: string,+ ref: { provider: string; modelId: string },+ counts: { cacheRead: number; cacheWrite: number; output: number },+ at: Date,+ ): Promise<number | null> {+ try {+ const rates = await this.lookupPricing(projectId, ref.provider, ref.modelId, at);+ if (rates === undefined) return null;+ return requestCostUsd(counts, rates);+ } catch {+ return null;+ }+ }/** Consume one outgoing message; messages other than session_meta / token_usage are a no-op. */async record(ctx: UsageContext, msg: OmniMessage): Promise<void> {@@ -91,12 +123,12 @@ export class UsageRecorder implements UsageRecording {if (payload.type === "token_usage" && payload.request) {// A successful request: persist along with tokens (status defaults to completed).const r = payload.request;+ const counts = { cacheRead: r.cache_read, cacheWrite: r.cache_write, output: r.output };this.usage.insert({...base,- cacheRead: r.cache_read,- cacheWrite: r.cache_write,- output: r.output,+ ...counts,total: r.total,+ cost: await this.costOf(ctx.projectId, ref, counts, now),});return;}@@ -104,13 +136,14 @@ export class UsageRecorder implements UsageRecording {// persist 0 tokens + status, feeding the "model success rate" stat; a successful// request is already counted once via the token_usage branch above, not repeated here.if (payload.type === "request_end" && payload.status && payload.status !== "completed") {+ const counts = { cacheRead: 0, cacheWrite: 0, output: 0 };this.usage.insert({...base,- cacheRead: 0,- cacheWrite: 0,- output: 0,+ ...counts,total: 0,status: payload.status,+ // Zero, not null, for a priced model: nothing was billed, and the group is not uncosted.+ cost: await this.costOf(ctx.projectId, ref, counts, now),});}}diff --git a/packages/server/src/services/admin-service.ts b/packages/server/src/services/admin-service.tsindex 61bd18fd..df247e0f 100644--- a/packages/server/src/services/admin-service.ts+++ b/packages/server/src/services/admin-service.ts@@ -43,11 +43,11 @@ export class AdminService implements Admin {* avatar is a data URL of up to 128 KiB and this list is unpaged, so carrying one per account* would answer a table that only shows the nickname with megabytes.*- * The cost is summed per Project because pricing is per Project (each one carries its own- * configured rates), and it is read at the CURRENT rates for every record ever written — the- * one figure the cost center's "cumulative" card shows, extended over everything the account- * owns. `costUnpriced` travels with it: a Model this deployment has no price for makes the sum- * a lower bound, and a table that presented it as exact would overstate its own accuracy.+ * The cost is summed per Project because a Project is what carries the price a Request was+ * billed at, and every record contributes the cost fixed when it was written — the one figure+ * the cost center's "cumulative" card shows, extended over everything the account owns.+ * `costUnpriced` travels with it: a Model this deployment had no price for makes the sum a+ * lower bound, and a table that presented it as exact would overstate its own accuracy.*/async listUsers(): Promise<UserInfo[]> {const out: UserInfo[] = [];diff --git a/packages/server/src/services/project-config-service.ts b/packages/server/src/services/project-config-service.tsindex f1369f69..b65a0888 100644--- a/packages/server/src/services/project-config-service.ts+++ b/packages/server/src/services/project-config-service.ts@@ -43,6 +43,7 @@ import {defaultProjectConfig,imageUrlMessage,metaMaxTokens,+ offPeakAt,presetPromotions,projectConfigFromTable,projectConfigPath,@@ -103,7 +104,7 @@ import {classifyVisionProbe,classifyVisionProbeError,} from "./vision-detect.js";-import type { PricingRates, TieredRates } from "./usage-service.js";+import type { PricingRates } from "./usage-service.js";import { Component, Use } from "@lmliheng/penguin-core/kernel";import type { Config, Paths } from "../hmr/capabilities.js";import type {@@ -190,40 +191,33 @@ function promotedRates(rates: PricingRates, discount: number): PricingRates {}/**- * Both tiers of a price read from a Project's config.+ * A price read from a Project's config, at the instant it is billed.** A scheduled row stores its PEAK price — the one number that is true whatever hour it is- * written — and the reduced rate is derived here. Both are returned rather than one of them- * chosen, because the caller prices a RANGE: a week that straddles a boundary holds Tokens of- * both kinds, and each is billed at the rate it actually ran at. Choosing here would mean- * pricing a finished week at whichever tier happened to be in force when someone opened the- * page, which moves a settled number twice a day.- *- * The two tiers differ only while the stored price is still exactly the catalog's peak: once- * the user has typed their own number, nothing here knows whether it is a peak rate, and+ * written — and the reduced tier is derived here, from the instant the Request completed or the+ * record ran. The two differ only while the stored price is still exactly the catalog's peak:+ * once the user has typed their own number, nothing here knows whether it is a peak rate, and* halving it would invent a discount. The models page's badge bails on the same condition, so* the card and the bill always agree about what this row costs.*/-function tieredRates(provider: string, modelId: string, rates: PricingRates): TieredRates {+function scheduledRateAt(+ provider: string,+ modelId: string,+ rates: PricingRates,+ at: Date,+): PricingRates {const entry = catalogEntryFor(provider, modelId);const schedule = entry?.offPeakDiscount;- if (schedule === undefined || entry?.pricing === undefined)- return { peak: rates, offPeak: rates };+ if (schedule === undefined || entry?.pricing === undefined || Number.isNaN(at.getTime())) {+ return rates;+ }const peak = entry.pricing;const untouched =rates.cacheRead === peak.cache_read &&rates.cacheWrite === peak.cache_write &&rates.output === peak.output;- if (!untouched) return { peak: rates, offPeak: rates };- const off = (v: number): number => Math.round(v * (1 - schedule.rate) * 1e6) / 1e6;- return {- peak: rates,- offPeak: {- cacheRead: off(rates.cacheRead),- cacheWrite: off(rates.cacheWrite),- output: off(rates.output),- },- };+ if (!untouched || !offPeakAt(schedule, at)) return rates;+ return promotedRates(rates, schedule.rate);}function optStr(v: unknown): string | undefined {@@ -777,26 +771,25 @@ export class ProjectConfigService implements ProjectConfigStore {}/**- * Pricing lookup for usage-recorder: the current pricing for this paired reference (undefined- * if none -> cost is NULL). The file holds the list price; a stored promotion takes its- * fraction off both tiers, so a scheduled row on a promotion bills the two factors multiplied.+ * The price a Request on this paired reference is billed at, completing at `at`, or undefined+ * when the Project stores no price for it (-> the record's cost is NULL). The file holds the+ * list price and the row's promotion its fraction; both are folded here, at the tier `at` falls+ * in, so the recorder fixes a Request's cost with the one figure in force when it completed and+ * the Trace page can ask the same question at a past Request's own timestamp.*/async getPricing(projectId: string,provider: string,modelId: string,- ): Promise<TieredRates | undefined> {+ at: Date,+ ): Promise<PricingRates | undefined> {const raw = await this.readRaw(projectId);const entry = asArray(raw.models).find((m) => entryMatches(m, provider, modelId));const rates = pricingDtoOf(entry?.pricing);if (rates === undefined) return undefined;- const tiered = tieredRates(provider, modelId, rates);+ const scheduled = scheduledRateAt(provider, modelId, rates, at);const discount = this.promotions?.get(projectId, provider, modelId);- if (discount === undefined) return tiered;- return {- peak: promotedRates(tiered.peak, discount),- offPeak: promotedRates(tiered.offPeak, discount),- };+ return discount === undefined ? scheduled : promotedRates(scheduled, discount);}/**diff --git a/packages/server/src/services/trace-service.ts b/packages/server/src/services/trace-service.tsindex fca177cd..cf4d92f6 100644--- a/packages/server/src/services/trace-service.ts+++ b/packages/server/src/services/trace-service.ts@@ -54,8 +54,8 @@ import type { SessionRow } from "../db/repos/sessions.js";import type { TraceFileRow, TraceSessionRow } from "../db/repos/trace-index.js";import { HttpError } from "../http/errors.js";import { formatLocalDate } from "../internal/dates.js";-import { ratesAt, requestCostUsd } from "./usage-service.js";-import type { PricingLookup, TieredRates } from "./usage-service.js";+import { requestCostUsd } from "./usage-service.js";+import type { PricingLookup, PricingRates } from "./usage-service.js";import type { ProjectConfigStore } from "../mechanisms/projects.js";import {cloneScanState,@@ -289,13 +289,14 @@ export class TraceService implements Traces {@Use() private readonly sources?: SessionOrigins;@Use() private readonly projectConfig?: ProjectConfigStore;/**- * The Project's current price for a paired reference — the same lookup the cost center- * prices `usage_records` with, so the analysis' per-turn cost and the toolbar's figure come- * from one price table. Narrow tests wire their own or none; without a price the analysis- * carries no cost at all.+ * What the Project bills for a paired reference, at the instant asked for. The analysis answers+ * "what these Requests are worth at today's price": each Request is priced with this, at its own+ * timestamp's tier — it never reads the rates the Request recorded, so after a price change it+ * can differ from the cost center's fixed figures, which stay the bill. Narrow tests wire their+ * own or none; without it the analysis carries no cost at all.*/- private lookupPricing: PricingLookup = async (projectId, provider, modelId) =>- this.projectConfig?.getPricing(projectId, provider, modelId);+ private lookupPricing: PricingLookup = async (projectId, provider, modelId, at) =>+ this.projectConfig?.getPricing(projectId, provider, modelId, at);/*** Test observability: called with the path of every Trace shard this service reads* from disk (windowed-read tests assert an old-window request never touches the@@ -975,16 +976,16 @@ export class TraceService implements Traces {}/**- * The price table the analysis costs a file's Requests against: the Project's current rates- * for the model named by the file's own `session_meta` head, in both tiers. Null when there- * is no lookup, when the model has no pricing, and for a head that names no provider — such- * a Trace is legacy data (core refuses to resume it), and the id alone can exist under- * several providers at different prices, so nothing is priced rather than a first match.+ * What the analysis prices a file's Requests on: the paired reference named by the file's own+ * `session_meta` head. Null when there is no lookup and for a head that names no provider —+ * such a Trace is legacy data (core refuses to resume it), and the id alone can exist under+ * several providers at different prices, so nothing is priced rather than a first match. The+ * rate itself is asked for per Request (see analyze): it depends on that Request's timestamp.*/private async filePricing(projectId: string,meta: OmniMessage | undefined,- ): Promise<{ provider: string; modelId: string; rates: TieredRates } | null> {+ ): Promise<{ provider: string; modelId: string } | null> {if (meta === undefined) return null;const { provider, model_id: modelId } = meta.payload as {provider?: unknown;@@ -992,8 +993,7 @@ export class TraceService implements Traces {};if (typeof provider !== "string" || provider === "") return null;if (typeof modelId !== "string" || modelId === "") return null;- const rates = await this.lookupPricing(projectId, provider, modelId);- return rates === undefined ? null : { provider, modelId, rates };+ return { provider, modelId };}/** Performance analysis: derived from a single Trace file. */@@ -1009,6 +1009,17 @@ export class TraceService implements Traces {(m) => isSessionMeta(m) && (m.origin === undefined || m.origin.length === 0),);const pricing = await this.filePricing(projectId, meta);+ // The rates the file's Requests are priced at, memoized by hour: a tier boundary is a whole+ // hour in every schedule the catalog can express, so one lookup per hour a Trace spans is+ // enough, and a long Trace does not read the Project's config once per Request. Lives only as+ // long as this analysis.+ const fileRates = new Map<string, PricingRates | undefined>();+ // Whether the Project prices this reference AT ALL, which the instant does not affect+ // (`getPricing` answers undefined only when no price is stored for it). Read off the lookups+ // this pass already makes: a priced file states a cost for every turn — a turn with no+ // Request included — so its cards read $0, while a file nothing could price carries no cost+ // field at all, which is what "no price" means to the card. See the task finalize below.+ let priced = false;const headWindow = (meta?.payload as { model_context_window?: unknown } | undefined)?.model_context_window;const modelContextWindow =@@ -1080,9 +1091,8 @@ export class TraceService implements Traces {startTs: "",endTs: "",tokens: { cacheRead: 0, cacheWrite: 0, output: 0 },- // A priced file states a cost for every turn, a turn with no Request included: the- // card then reads $0 rather than "no price", which is what an absent field means.- ...(pricing !== null ? { cost: 0 } : {}),+ // `cost` is filled in below: either by the Turn's own Requests, or — for a Turn with+ // none, on a file whose reference the Project does price — with a zero at finalize.llmMs: 0,toolMs: 0,};@@ -1362,24 +1372,32 @@ export class TraceService implements Traces {t.tokens.cacheWrite += request?.cache_write ?? 0;t.tokens.output += request?.output ?? 0;if (pricing !== null) {- // Priced per Request, at the tier this Request's own timestamp fell in — the- // rule the cost center applies to the usage row this same event produced, so- // the two figures for one request are the same figure.- t.cost =- (t.cost ?? 0) +- requestCostUsd(- {- cacheRead: request?.cache_read ?? 0,- cacheWrite: request?.cache_write ?? 0,- output: request?.output ?? 0,- },- ratesAt(- pricing.rates,- pricing.provider,- pricing.modelId,- new Date(msg.timestamp),- ),+ // Priced per Request at the price the Project stores TODAY, at the tier that+ // Request's own timestamp fell in (see lookupPricing) — the rule it was billed by,+ // applied to today's price. After a price change this can therefore differ from the+ // cost center's figure, which stays the bill.+ const at = new Date(msg.timestamp);+ const key = `${pricing.provider}\0${pricing.modelId}\0${Math.floor(at.getTime() / 3_600_000)}`;+ if (!fileRates.has(key)) {+ fileRates.set(+ key,+ await this.lookupPricing(projectId, pricing.provider, pricing.modelId, at),);+ }+ const rates = fileRates.get(key);+ if (rates !== undefined) {+ priced = true;+ t.cost =+ (t.cost ?? 0) ++ requestCostUsd(+ {+ cacheRead: request?.cache_read ?? 0,+ cacheWrite: request?.cache_write ?? 0,+ output: request?.output ?? 0,+ },+ rates,+ );+ }}if (!compactionActive) {// The context snapshot only takes non-compaction Requests: tokens@@ -1550,7 +1568,11 @@ export class TraceService implements Traces {// follows above, so a reader adding up the turn cards lands on the totals.const apiMs = tasks.reduce((sum, t) => sum + t.llmMs, 0);const toolMs = tasks.reduce((sum, t) => sum + t.toolMs, 0);- const cost = pricing !== null ? tasks.reduce((sum, t) => sum + (t.cost ?? 0), 0) : undefined;+ // A file the Project prices states a cost for every Turn, including one that made no+ // Request (a billed zero, so the card reads $0); a file it prices nothing in carries no cost+ // at all, which the card draws as "no price". This is where `priced` decides the difference.+ if (priced) for (const t of tasks) t.cost ??= 0;+ const cost = priced ? tasks.reduce((sum, t) => sum + (t.cost ?? 0), 0) : undefined;return {elapsedMs,apiMs,diff --git a/packages/server/src/services/usage-service.ts b/packages/server/src/services/usage-service.tsindex 4946bd6d..40014347 100644--- a/packages/server/src/services/usage-service.ts+++ b/packages/server/src/services/usage-service.ts@@ -1,12 +1,12 @@/*** Usage statistics query.*- * Cost is **computed in real time**: usage_records only stores Tokens (pricing may- * be added later), so at query time each Model's cost is converted using the- * current Project's configured pricing — the repo returns raw Token totals broken- * down by `(provider, model_id)` paired reference, and this service looks up each- * reference's price once and folds it into cost / hasUncosted (if a Model has no- * pricing, its consumption is excluded from cost and hasUncosted is flagged).+ * Cost is **fixed when a Request completes**: every usage_records row carries the cost the+ * recorder computed from the rates in force at that moment, and nothing here re-prices it — a+ * price edited, synced or discounted later only changes what later Requests cost. The repo+ * returns sums broken down by `(provider, model_id)` paired reference, and this service folds+ * them into cost / hasUncosted (a row whose model had no price is excluded from cost and flags+ * hasUncosted).* Summary cards (today / last 7 days / cumulative), grouped aggregation (date /* agent / model / session, with the session dimension supporting agentId drill-down* filtering), and the zero-filled time series the cost center's charts draw.@@ -30,18 +30,12 @@ import type {UsageSeriesPoint,} from "../api/types.js";import type { ErrorFilter } from "../db/repos/errors.js";-import {- catalogEntryFor,- offPeakAt,- offPeakScheduledRefs,-} from "@lmliheng/penguin-core/model-catalog";import type {UsageModelSums,UsageGroupModelSums,UsageSeriesModelSums,UsageAgentBucketCount,UsageFilter,- PeakTier,} from "../db/repos/usage.js";import {enumerateBuckets,@@ -71,23 +65,16 @@ export interface PricingRates {}/**- * What one Model costs, in the tiers it can be billed in.- *- * `offPeak` differs from `peak` only for a catalog row on a time-based schedule whose stored- * price is still the catalog's own. Both are returned together because a query spans time: a- * week that straddles the boundary contains Tokens of both kinds, and each half is priced at- * the rate it actually ran at rather than at whichever tier is in force when it is read.+ * The price a Project stores for a paired reference — what a Request on it is billed at when+ * it completes at `at` (the Project's list price for the row, less its promotion, at the tier+ * in force then); undefined = the Project stores no price for it.*/-export interface TieredRates {- peak: PricingRates;- offPeak: PricingRates;-}-export type PricingLookup = (projectId: string,provider: string,modelId: string,-) => Promise<TieredRates | undefined>;+ at: Date,+) => Promise<PricingRates | undefined>;export interface UsageQuery {from?: string;@@ -165,32 +152,6 @@ export function requestCostUsd();}-/**- * The rates one usage record is billed at, decided from the record's own timestamp: the- * off-peak tier when the reference carries a catalog schedule and `at` falls outside its peak- * windows, the peak tier otherwise. For a reference with no schedule, or whose stored price is- * no longer the catalog's, the two tiers are the same figure (see project-config-service's- * `tieredRates`), so the decision changes nothing there. `peakExpr` in the usage repo is this- * rule written in SQL for the aggregations; the two must agree record for record, which is why- * an unreadable timestamp — which the repo never stores — takes the peak tier rather than- * inventing a discount.- */-export function ratesAt(- tiered: TieredRates,- provider: string,- modelId: string,- at: Date,-): PricingRates {- const schedule = catalogEntryFor(provider, modelId)?.offPeakDiscount;- if (schedule === undefined || Number.isNaN(at.getTime())) return tiered.peak;- return offPeakAt(schedule, at) ? tiered.offPeak : tiered.peak;-}--/** Cost formula: sum of the three buckets at the tier these Tokens ran in, USD per million. */-function costOf(sums: UsageModelSums, tiered: TieredRates): number {- return requestCostUsd(sums, sums.peak ? tiered.peak : tiered.offPeak);-}-/** In-process Map key for a paired reference (\0-separated, the same style as session-manager's agentKey; never persisted). */function refKey(provider: string, modelId: string): string {return `${provider}\0${modelId}`;@@ -202,31 +163,44 @@ export class UsageService implements UsageQueries {@Use() private readonly errors!: ErrorLog;@Use() private readonly projectConfig!: ProjectConfigStore;@Use() private readonly clock!: Clock;- private lookupPricing: PricingLookup = (projectId, provider, modelId) =>- this.projectConfig.getPricing(projectId, provider, modelId);+ private lookupPricing: PricingLookup = (projectId, provider, modelId, at) =>+ this.projectConfig.getPricing(projectId, provider, modelId, at);/**- * The catalog's time-based schedules, as the aggregations want them.- *- * Split by the SCHEDULE, not by whether this Project is on the catalog's price: a Project- * that edited the price gets one rate for both halves from {@link lookupPricing}, so the extra- * dimension costs a row and changes no number. Doing it the other way round would need the- * config read before the query that discovers which references occur.+ * COMPATIBILITY — remove two releases after the one that fixes costs at record time, together+ * with the `cost_settled` column. Fixes the cost of every usage record that has none yet: rows+ * written before costs were fixed at record time, and rows an older build wrote after a hot+ * update rolled back to it. Each is priced at the price its Project stores now, at the tier the+ * record's own timestamp fell in — the read-time cost center's promotion, with the tier pinned+ * to the row rather than to the hour the page happened to be opened. That is the one figure+ * which moves at the upgrade (a row the old page showed in the other tier corrects itself) and+ * never again after it. Idempotent — a settled row is never touched again — and safe beside the+ * recorder, whose rows are settled when written. Returns how many rows it settled.*/- private tiers(): PeakTier[] {- return offPeakScheduledRefs().map(({ schedule, refs }) => ({- refs,- utcOffsetMinutes: schedule.utcOffsetMinutes,- peakDays: schedule.peakDays,- peakHours: schedule.peakHours,- }));+ async settleUnsettledCosts(): Promise<number> {+ let settled = 0;+ for (const ref of this.usage.unsettledRefs()) {+ const rows = this.usage.unsettledRows(ref.projectId, ref.provider, ref.modelId);+ const costs: Array<{ id: number; cost: number | null }> = [];+ for (const r of rows) {+ const rates = await this.lookupPricing(+ ref.projectId,+ ref.provider,+ ref.modelId,+ new Date(r.ts),+ );+ costs.push({ id: r.id, cost: rates === undefined ? null : requestCostUsd(r, rates) });+ }+ this.usage.settle(costs);+ settled += rows.length;+ }+ return settled;}/*** Period cost per session, for company mode's attribution by the sessions an organization- * owns: sums by paired reference priced at the current rates (each half at the tier its own- * records ran in). `unpriced` says some usage ran on a model without pricing, so the numbers- * are a lower bound.+ * owns: the recorded costs summed per session. `unpriced` says some usage ran on a model+ * without pricing, so the numbers are a lower bound.*/async costBySession(projectId: string,@@ -236,25 +210,11 @@ export class UsageService implements UsageQueries {): Promise<{ bySession: Map<string, number>; unpriced: boolean }> {const bySession = new Map<string, number>();if (sessionIds.length === 0) return { bySession, unpriced: false };- const rows = this.usage.groupsByModel(- projectId,- "session",- { sessionIds, fromTs, toTs },- this.tiers(),- );- const rates = new Map<string, TieredRates | undefined>();+ const rows = this.usage.groupsByModel(projectId, "session", { sessionIds, fromTs, toTs });let unpriced = false;for (const r of rows) {- const key = refKey(r.provider, r.modelId);- if (!rates.has(key)) {- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));- }- const rate = rates.get(key);- if (!rate) {- unpriced = true;- continue;- }- bySession.set(r.key, (bySession.get(r.key) ?? 0) + costOf(r, rate));+ if (r.uncosted > 0) unpriced = true;+ if (r.cost !== null) bySession.set(r.key, (bySession.get(r.key) ?? 0) + r.cost);}return { bySession, unpriced };}@@ -267,22 +227,10 @@ export class UsageService implements UsageQueries {toTs: string,): Promise<Array<{ date: string; cost: number }>> {if (sessionIds.length === 0) return [];- const rows = this.usage.seriesByModel(- projectId,- "day",- { sessionIds, fromTs, toTs },- this.tiers(),- );- const rates = new Map<string, TieredRates | undefined>();+ const rows = this.usage.seriesByModel(projectId, "day", { sessionIds, fromTs, toTs });const byDate = new Map<string, number>();for (const r of rows) {- const key = refKey(r.provider, r.modelId);- if (!rates.has(key)) {- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));- }- const rate = rates.get(key);- if (!rate) continue;- byDate.set(r.key, (byDate.get(r.key) ?? 0) + costOf(r, rate));+ if (r.cost !== null) byDate.set(r.key, (byDate.get(r.key) ?? 0) + r.cost);}return [...byDate.entries()].sort(([a], [b]) => a.localeCompare(b))@@ -310,20 +258,16 @@ export class UsageService implements UsageQueries {...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),...(q.toTs !== undefined ? { toTs: q.toTs } : {}),};- const tiers = this.tiers();- const todayRows = this.usage.bucketByModel(projectId, win(today, today), tiers);+ const todayRows = this.usage.bucketByModel(projectId, win(today, today));const last7dRows = this.usage.bucketByModel(projectId,win(localDateMinusDays(this.clock.now(), 6)),- tiers,- );- const totalRows = this.usage.bucketByModel(projectId, { ...win(q.from, q.to), ...ts }, tiers);- const groupRows = this.usage.groupsByModel(- projectId,- q.groupBy,- { ...win(q.from, q.to), ...ts },- tiers,);+ const totalRows = this.usage.bucketByModel(projectId, { ...win(q.from, q.to), ...ts });+ const groupRows = this.usage.groupsByModel(projectId, q.groupBy, {+ ...win(q.from, q.to),+ ...ts,+ });// Time series at the requested precision, zero-filled over the requested// range, defaulting to the last 30 days when no range is given.const granularity = q.granularity ?? "day";@@ -351,12 +295,10 @@ export class UsageService implements UsageQueries {"Date range too wide for this granularity; narrow the range or coarsen the granularity.",);}- const seriesRows = this.usage.seriesByModel(- projectId,- granularity,- { ...win(seriesFrom, seriesTo), ...ts },- tiers,- );+ const seriesRows = this.usage.seriesByModel(projectId, granularity, {+ ...win(seriesFrom, seriesTo),+ ...ts,+ });// Per-Agent and per-Model series: each drops its own dimension's filter (its// chart draws that dimension's whole breakdown) but honors the other// dimension plus the selected range.@@ -395,26 +337,16 @@ export class UsageService implements UsageQueries {...(q.includeGlobalErrors === true ? { includeGlobal: true } : {}),};- // Each paired reference that occurs is looked up for its current price only once.- const rates = new Map<string, TieredRates | undefined>();- const allRefs = new Map<string, { provider: string; modelId: string }>();- for (const r of [...todayRows, ...last7dRows, ...totalRows, ...groupRows, ...seriesRows]) {- allRefs.set(refKey(r.provider, r.modelId), { provider: r.provider, modelId: r.modelId });- }- for (const [key, ref] of allRefs) {- rates.set(key, await this.lookupPricing(projectId, ref.provider, ref.modelId));- }-return {summary: {- today: this.foldBucket(todayRows, rates),- last7d: this.foldBucket(last7dRows, rates),- total: this.foldBucket(totalRows, rates),+ today: this.foldBucket(todayRows),+ last7d: this.foldBucket(last7dRows),+ total: this.foldBucket(totalRows),},groupBy: q.groupBy,- groups: this.foldGroups(groupRows, rates, q.groupBy),+ groups: this.foldGroups(groupRows, q.groupBy),granularity,- series: this.foldSeries(bucketKeys, seriesRows, rates),+ series: this.foldSeries(bucketKeys, seriesRows),byAgentSeries: foldAgentSeries(bucketKeys, agentBucketRows),byModelSeries: foldModelSeries(bucketKeys, modelBucketRows),errors: this.foldErrors(projectId, errorFilter, q.utcOffsetMinutes),@@ -508,28 +440,17 @@ export class UsageService implements UsageQueries {/*** The Project's lifetime cost — one unfiltered grouped scan, the same one `modelTotals` runs,- * priced at the current rates. Its consumer is a per-account figure (the admin user backend's- * cost column), so there is exactly one number: `cost` stays null while nothing could be- * priced rather than reporting a zero the caller cannot tell from "ran for free", and- * `unpriced` marks a lower bound.+ * summing the costs fixed when the rows were written. Its consumer is a per-account figure+ * (the admin user backend's cost column), so there is exactly one number: `cost` stays null+ * while nothing could be priced rather than reporting a zero the caller cannot tell from "ran+ * for free", and `unpriced` marks a lower bound.*/async lifetimeCost(projectId: string): Promise<{ cost: number | null; unpriced: boolean }> {- const rows = this.usage.bucketByModel(projectId, {}, this.tiers());- const rates = new Map<string, TieredRates | undefined>();- for (const r of rows) {- const key = refKey(r.provider, r.modelId);- if (!rates.has(key)) {- rates.set(key, await this.lookupPricing(projectId, r.provider, r.modelId));- }- }- const { cost, hasUncosted } = this.foldBucket(rows, rates);+ const { cost, hasUncosted } = this.foldBucket(this.usage.bucketByModel(projectId));return { cost, unpriced: hasUncosted };}- private foldBucket(- rows: UsageModelSums[],- rates: Map<string, TieredRates | undefined>,- ): UsageBucket {+ private foldBucket(rows: UsageModelSums[]): UsageBucket {let total = 0;let requests = 0;let cost: number | null = null;@@ -537,18 +458,13 @@ export class UsageService implements UsageQueries {for (const r of rows) {total += r.total;requests += r.requests;- const rate = rates.get(refKey(r.provider, r.modelId));- if (rate) cost = (cost ?? 0) + costOf(r, rate);- else hasUncosted = true;+ if (r.cost !== null) cost = (cost ?? 0) + r.cost;+ if (r.uncosted > 0) hasUncosted = true;}return { total, requests, cost, hasUncosted };}- private foldGroups(- rows: UsageGroupModelSums[],- rates: Map<string, TieredRates | undefined>,- groupBy: UsageGroupBy,- ): UsageGroupRow[] {+ private foldGroups(rows: UsageGroupModelSums[], groupBy: UsageGroupBy): UsageGroupRow[] {// The model dimension folds by paired reference (a shared model_id name across providers is split into separate rows); other dimensions fold by their group key.const keyOf = (r: UsageGroupModelSums): string =>groupBy === "model" ? refKey(r.provider, r.key) : r.key;@@ -570,9 +486,8 @@ export class UsageService implements UsageQueries {acc.output += r.output;acc.total += r.total;acc.requests += r.requests;- const rate = rates.get(refKey(r.provider, r.modelId));- if (rate) acc.cost = (acc.cost ?? 0) + costOf(r, rate);- else acc.hasUncosted = true;+ if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;+ if (r.uncosted > 0) acc.hasUncosted = true;byKey.set(keyOf(r), acc);}const out = [...byKey.values()];@@ -591,11 +506,7 @@ export class UsageService implements UsageQueries {* `ts` and can therefore fall outside a skeleton built from `date` if a row* was recorded under a different clock.*/- private foldSeries(- keys: string[],- rows: UsageSeriesModelSums[],- rates: Map<string, TieredRates | undefined>,- ): UsageSeriesPoint[] {+ private foldSeries(keys: string[], rows: UsageSeriesModelSums[]): UsageSeriesPoint[] {const byKey = new Map<string, UsageSeriesPoint>(keys.map((bucket) => [bucket,@@ -622,8 +533,7 @@ export class UsageService implements UsageQueries {acc.requests += r.requests;acc.completed += r.completed;acc.denominator += r.denominator;- const rate = rates.get(refKey(r.provider, r.modelId));- if (rate) acc.cost = (acc.cost ?? 0) + costOf(r, rate);+ if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;}return keys.map((k) => byKey.get(k)!);}diff --git a/packages/server/test/admin-users.test.ts b/packages/server/test/admin-users.test.tsindex 288d2612..78abcb7e 100644--- a/packages/server/test/admin-users.test.ts+++ b/packages/server/test/admin-users.test.ts@@ -155,7 +155,7 @@ describe("admin users backend", () => {/*** The two read-only columns the user backend carries. Both are the server's own figures: the* sign-in stamp AuthService writes on a password login, and the lifetime cost of the Projects- * the account OWNS, priced at the current rates.+ * the account OWNS — every record's cost as it was fixed when the row was written.*/it("user list: last sign-in is stamped by the login that succeeded, absent for an account never used", async () => {const kate = await provisionUser(t.app, "kate");@@ -178,8 +178,8 @@ describe("admin users backend", () => {it("user list: cost sums the Projects the account owns, and says so when a model has no price", async () => {const kate = await provisionUser(t.app, "kate");- // Two models in Kate's own Project: `m-priced` costs (10*1 + 1*2 + 5*3)/1e6 per record,- // `m-free` carries no pricing block at all.+ // Kate's Project stores a price for `m-priced` — (10*1 + 1*2 + 5*3)/1e6 per record — and none+ // at all for `m-free`, so a row on the latter is recorded without a cost.await saveProjectConfig(t.root, "kate-default_project", {default_model: { provider: "custom", model_id: "m-priced" },models: [@@ -191,11 +191,12 @@ describe("admin users backend", () => {{ provider: "custom", model_id: "m-free" },],});- const insertUsage = (modelId: string, date: string): void => {+ /** A row as the recorder writes it: the Tokens, and the cost its Project's price fixed. */+ const insertUsage = (modelId: string, date: string, cost: number | null): void => {t.deps.db.prepare(- "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id, cache_read, cache_write, output, total)" +- " VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?)",+ "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, origin_session_id, provider, model_id, cache_read, cache_write, output, total, cost, cost_settled)" ++ " VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, 1)",).run(`${date}T00:00:00.000Z`,@@ -209,21 +210,23 @@ describe("admin users backend", () => {1,5,16,+ cost,);};- insertUsage("m-priced", "2026-10-01");- insertUsage("m-priced", "2026-10-02");+ const ROW_COST = (10 * 1 + 1 * 2 + 5 * 3) / 1e6;+ insertUsage("m-priced", "2026-10-01", ROW_COST);+ insertUsage("m-priced", "2026-10-02", ROW_COST);// Nobody else's: the admin's own default Project has no usage, and Kate's cost counts only// what her own Project recorded — the figure is per owned Project, not per caller.let list = (await (await admin.get("/api/admin/users")).json()) as AdminUsersResponse;const priced = list.users.find((u) => u.userId === "kate")!;- expect(priced.totalCostUsd).toBeCloseTo((2 * (10 * 1 + 1 * 2 + 5 * 3)) / 1e6, 12);+ expect(priced.totalCostUsd).toBeCloseTo(2 * ROW_COST, 12);expect(priced.costUnpriced).toBeUndefined();expect(list.users.find((u) => u.userId === "admin")!.totalCostUsd).toBeUndefined();- // A record on a model with no price block makes the sum a lower bound — reported as such- // instead of silently dropped.- insertUsage("m-free", "2026-10-03");+ // A record whose model had no price when it was written makes the sum a lower bound —+ // reported as such instead of silently dropped.+ insertUsage("m-free", "2026-10-03", null);list = (await (await admin.get("/api/admin/users")).json()) as AdminUsersResponse;const bounded = list.users.find((u) => u.userId === "kate")!;expect(bounded.totalCostUsd).toBeCloseTo(priced.totalCostUsd!, 12);diff --git a/packages/server/test/db-migrations.test.ts b/packages/server/test/db-migrations.test.tsindex 40404990..9eca5f69 100644--- a/packages/server/test/db-migrations.test.ts+++ b/packages/server/test/db-migrations.test.ts@@ -1,8 +1,8 @@/*** The ordered-migration mechanism, the 0.2.4 → 0.2.7 migration that is its first entry, the- * 0.2.9 → 0.2.10 drop that is its first restart-only one, the additive column pair that- * the user profile added to `users`, and the channels migration that is its first table- * recreation.+ * 0.2.9 → 0.2.10 drop that is its first restart-only one, the additive column pairs that+ * the user profile added to `users` and the fixed cost added to `usage_records`, and the+ * channels migration that is its first table recreation.** Two properties carry everything else: a real 0.2.4 database reaches exactly the shape a* fresh one is created with (so a runtime older than the platform pushed onto it becomes@@ -80,6 +80,7 @@ function open024(): DatabaseSync {// must come off, or a round trip through migration 5's down would land on a narrower// `users` than this fixture and read as a rollback that lost something.dropProfileColumns(db);+ dropUsageCostColumns(db);db.exec(GOAL_STATE_DDL);return db;}@@ -115,9 +116,11 @@ function open6(): DatabaseSync {db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");db.exec("DROP TABLE IF EXISTS model_promotions");db.exec(PRE_CHANNEL_CHAT_DDL);- // SCHEMA_SQL declares the CURRENT shape; migration 8's queue and migration 13's came after 6.+ // SCHEMA_SQL declares the CURRENT shape; migration 8's queue, migration 13's came after 6, and+ // the cost columns are migration 14's.db.exec("DROP TABLE IF EXISTS org_desk_notices");db.exec("DROP TABLE IF EXISTS org_desk_mentions");+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 6");return db;}@@ -130,6 +133,7 @@ function open7(): DatabaseSync {db.exec("DROP TABLE IF EXISTS org_desk_mentions");db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");db.exec("DROP TABLE IF EXISTS model_promotions");+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 7");return db;}@@ -141,6 +145,7 @@ function open8(): DatabaseSync {db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");db.exec("DROP TABLE IF EXISTS model_promotions");db.exec("DROP TABLE IF EXISTS org_desk_mentions");+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 8");return db;}@@ -151,6 +156,7 @@ function open9(): DatabaseSync {db.exec(SCHEMA_SQL);db.exec("DROP TABLE IF EXISTS model_provider_auth_tokens");db.exec("DROP TABLE IF EXISTS org_desk_mentions");+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 9");return db;}@@ -160,6 +166,7 @@ function open12(): DatabaseSync {const db = new sqlite.DatabaseSync(":memory:");db.exec(SCHEMA_SQL);db.exec("DROP TABLE IF EXISTS org_desk_mentions");+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 12");return db;}@@ -177,6 +184,7 @@ function open029(): DatabaseSync {// both the fixture is a database no release made.db.exec("DROP TABLE machine_project; DROP TABLE machines; DROP TABLE machine;");dropProfileColumns(db);+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 2");return db;}@@ -195,10 +203,23 @@ function openPreProfile(): DatabaseSync {// Version 4 predates company mode as well: its three migrations (6–8) come after the// profile's, so a database at 4 has none of their tables.dropCompanyTables(db);+ dropUsageCostColumns(db);db.exec("PRAGMA user_version = 4");return db;}+/**+ * A database from before costs were fixed at record time: today's declaration minus exactly the+ * two usage_records columns migration 14 adds, stamped at the version before it.+ */+function openPreUsageCost(): DatabaseSync {+ const db = new sqlite.DatabaseSync(":memory:");+ db.exec(SCHEMA_SQL);+ dropUsageCostColumns(db);+ db.exec("PRAGMA user_version = 13");+ return db;+}+/** Takes everything migrations 6–8 and 13 create off a database built from the current declaration. */function dropCompanyTables(db: DatabaseSync): void {db.exec(`@@ -223,6 +244,18 @@ function dropProfileColumns(db: DatabaseSync): void {db.exec("ALTER TABLE users DROP COLUMN display_name");}+/** Takes migration 9's two usage_records columns off a database built from the current declaration. */+function dropUsageCostColumns(db: DatabaseSync): void {+ db.exec("ALTER TABLE usage_records DROP COLUMN cost_settled");+ db.exec("ALTER TABLE usage_records DROP COLUMN cost");+}++/** Column names of `usage_records`. */+function usageColumns(db: DatabaseSync): string[] {+ const rows = db.prepare("PRAGMA table_info(usage_records)").all() as { name: string }[];+ return rows.map((r) => r.name);+}+/** Column names of `users`, for the two cases that are about columns rather than whole shapes. */function userColumns(db: DatabaseSync): string[] {const rows = db.prepare("PRAGMA table_info(users)").all() as { name: string }[];@@ -590,8 +623,9 @@ describe("migration 8 → current: model-promotions", () => {"sessions-sandbox","machines-columns","company-mode-desk-mentions",+ "usage-record-cost",]);- expect(schemaVersion(db)).toBe(13);+ expect(schemaVersion(db)).toBe(14);expect(promotionsTableExists()).toEqual({ "1": 1 });expect(authTokensTableExists()).toEqual({ "1": 1 });@@ -613,8 +647,9 @@ describe("migration 8 → current: model-promotions", () => {"sessions-sandbox","machines-columns","company-mode-desk-mentions",+ "usage-record-cost",]);- expect(schemaVersion(db)).toBe(13);+ expect(schemaVersion(db)).toBe(14);} finally {db.close();}@@ -636,8 +671,9 @@ describe("migration 9 → current: model-provider-auth-tokens", () => {"sessions-sandbox","machines-columns","company-mode-desk-mentions",+ "usage-record-cost",]);- expect(schemaVersion(db)).toBe(13);+ expect(schemaVersion(db)).toBe(14);expect(tableExists()).toEqual({ "1": 1 });db.exec("INSERT INTO users (user_id, password_hash, is_admin, created_at)" +@@ -680,7 +716,7 @@ describe("migration 12 → current: company-mode-desk-mentions", () => {try {fresh.exec(SCHEMA_SQL);expect(shape(db)).not.toBe(shape(fresh));- expect(migrate(db).applied).toEqual(["company-mode-desk-mentions"]);+ expect(migrate(db).applied).toEqual(["company-mode-desk-mentions", "usage-record-cost"]);expect(schemaVersion(db)).toBe(LATEST_VERSION);expect(shape(db)).toBe(shape(fresh));queue(db, "msg-1");@@ -716,6 +752,70 @@ describe("migration 12 → current: company-mode-desk-mentions", () => {});});+describe("pre-cost → current: usage-record-cost", () => {+ const legacyRow =+ "INSERT INTO usage_records (ts, date, project_id, agent_id, session_id, provider, model_id, cache_read, cache_write, output, total)" ++ " VALUES ('2026-09-01T00:00:00Z', '2026-09-01', 'p1', 'a1', 's1', 'custom', 'm1', 10, 1, 5, 16)";++ it("adds both columns with every existing row unsettled, and a database that already has them migrates the same", () => {+ const db = openPreUsageCost();+ const fresh = new sqlite.DatabaseSync(":memory:");+ try {+ fresh.exec(SCHEMA_SQL);+ db.exec(legacyRow);+ expect(usageColumns(db)).not.toContain("cost");+ expect(migrate(db).applied).toEqual(+ MIGRATIONS.filter((m) => m.version > 13).map((m) => m.name),+ );+ expect(shape(db)).toBe(shape(fresh));+ // The row a pre-cost build wrote waits for the startup settle: no cost, not settled.+ expect(db.prepare("SELECT cost, cost_settled FROM usage_records").all()).toEqual([+ { cost: null, cost_settled: 0 },+ ]);++ // ADOPTION: on a database this build created, the declarative track already added both.+ fresh.exec("PRAGMA user_version = 13");+ expect(migrate(fresh).applied).toEqual(+ MIGRATIONS.filter((m) => m.version > 13).map((m) => m.name),+ );+ expect(usageColumns(fresh).filter((c) => c === "cost")).toEqual(["cost"]);+ } finally {+ db.close();+ fresh.close();+ }+ });++ it("is swap-safe: a rolled-back predecessor keeps inserting, and its rows read unsettled", () => {+ const db = openPreUsageCost();+ try {+ migrate(db, { swapPath: true });+ db.exec(legacyRow); // what a predecessor that does not know the columns writes+ expect(db.prepare("SELECT cost, cost_settled FROM usage_records").all()).toEqual([+ { cost: null, cost_settled: 0 },+ ]);+ } finally {+ db.close();+ }+ });++ it("down removes both columns, taking every fixed cost with them; the rows survive", () => {+ const db = openPreUsageCost();+ try {+ db.exec(legacyRow);+ const before = shape(db);+ migrate(db);+ db.exec("UPDATE usage_records SET cost = 0.5, cost_settled = 1");++ rollbackTo(db, 13);+ expect(shape(db)).toBe(before);+ expect(usageColumns(db)).not.toContain("cost_settled");+ expect(db.prepare("SELECT total FROM usage_records").all()).toEqual([{ total: 16 }]);+ } finally {+ db.close();+ }+ });+});+describe("0.2.4 → current", () => {/** The whole point: an older runtime's database becomes what a current build creates. */it("brings a 0.2.4 database to the shape a fresh one is created with", () => {diff --git a/packages/server/test/models.test.ts b/packages/server/test/models.test.tsindex eaad31f9..e0956ab3 100644--- a/packages/server/test/models.test.ts+++ b/packages/server/test/models.test.ts@@ -52,6 +52,7 @@ import type {SessionCreateResponse,} from "../src/api/types.js";import { ProjectConfigService } from "../src/services/project-config-service.js";+import type { RuntimeSession } from "../src/runtime/session-manager.js";import type { ChannelEvent } from "../src/runtime/channel.js";import { jsonResponse, stubFetch } from "./fixtures/fetch.js";import { fakeSession, sessionRow } from "./fixtures/session.js";@@ -978,17 +979,22 @@ describe("model-reference rekeying and the connectivity test", () => {expect(toml).not.toContain("openai/gpt-5.5");});- it("a scheduled row answers with both of its rates, from the one stable price on disk", async () => {- // No clock is passed and none is wanted: which tier a given request ran in is decided from- // that record's own timestamp when the usage is aggregated, so the price lookup's whole job- // is to say what the two tiers are. The number on disk is the peak one either way.+ // 2026-08-31 is a Monday: 01:30Z is 09:30 in Beijing (peak), 12:00Z is 20:00 (off-peak).+ const PEAK = new Date("2026-08-31T01:30:00Z");+ const OFF_PEAK = new Date("2026-08-31T12:00:00Z");++ it("a scheduled row stores the one stable price, and the tier is derived from a Request's own instant", async () => {+ // The number on disk is the peak price whatever the hour; which tier a Request bills at is+ // decided by when it completed, so the same stored price bills twice as much at 09:30 as at+ // 20:00 on the same Monday.const svc = wire(ProjectConfigService, { paths: { root: t.root } });- const rates = await svc.getPricing(projectId, "deepseek", "deepseek-flash");+ const peak = await svc.getPricing(projectId, "deepseek", "deepseek-flash", PEAK);const catalogPeak = catalogEntryFor("deepseek", "deepseek-flash")!.pricing!;- expect(rates!.peak.output).toBe(catalogPeak.output);- expect(rates!.offPeak.output).toBeCloseTo(catalogPeak.output / 2, 5);- expect(rates!.peak.cacheRead).toBe(catalogPeak.cache_read);- expect(rates!.offPeak.cacheRead).toBeCloseTo(catalogPeak.cache_read / 2, 6);+ expect(peak!.output).toBe(catalogPeak.output);+ expect(peak!.cacheRead).toBe(catalogPeak.cache_read);+ const off = await svc.getPricing(projectId, "deepseek", "deepseek-flash", OFF_PEAK);+ expect(off!.output).toBeCloseTo(catalogPeak.output / 2, 5);+ expect(off!.cacheRead).toBeCloseTo(catalogPeak.cache_read / 2, 6);});it("a hand-edited price on a scheduled row is billed as typed, in both tiers", async () => {@@ -1012,12 +1018,10 @@ describe("model-reference rekeying and the connectivity test", () => {await api.put(url(), { models: entries });const svc = wire(ProjectConfigService, { paths: { root: t.root } });// Nothing here knows whether 3 is a peak rate, so halving it would invent a discount: the- // two tiers collapse to the typed number and the split costs a row and changes nothing.+ // typed number is what bills, whenever the Request runs.const typed = { cacheRead: 1, cacheWrite: 2, output: 3 };- expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash")).toEqual({- peak: typed,- offPeak: typed,- });+ expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash", PEAK)).toEqual(typed);+ expect(await svc.getPricing(projectId, "deepseek", "deepseek-flash", OFF_PEAK)).toEqual(typed);});it("a stored promotion takes its fraction off the list price on disk, multiplied with a scheduled row's off-peak tier", async () => {@@ -1030,10 +1034,7 @@ describe("model-reference rekeying and the connectivity test", () => {cacheWrite: off(list.cache_write, 0.1),output: off(list.output, 0.1),};- expect(await svc.getPricing(projectId, "tokendance", "glm-5.3-flash")).toEqual({- peak: promoted,- offPeak: promoted,- });+ expect(await svc.getPricing(projectId, "tokendance", "glm-5.3-flash", PEAK)).toEqual(promoted);// A scheduled row still at the catalog's peak price, with a promotion of its own: peak bills// the promotion alone, off-peak the half-price tier with the promotion taken off it too.@@ -1052,9 +1053,15 @@ describe("model-reference rekeying and the connectivity test", () => {},],});- const rates = (await svc.getPricing(projectId, "deepseek", "deepseek-v4-flash"))!;- expect(rates.peak.output).toBe(off(peak.output, 0.2));- expect(rates.offPeak.output).toBe(off(off(peak.output, 0.5), 0.2));+ const peakRates = (await svc.getPricing(projectId, "deepseek", "deepseek-v4-flash", PEAK))!;+ expect(peakRates.output).toBe(off(peak.output, 0.2));+ const offPeakRates = (await svc.getPricing(+ projectId,+ "deepseek",+ "deepseek-v4-flash",+ OFF_PEAK,+ ))!;+ expect(offPeakRates.output).toBe(off(off(peak.output, 0.5), 0.2));});it("PUT discount: a declared one is stored and null clears it; an omitted one survives only on an unrenamed row at an unchanged price", async () => {diff --git a/packages/server/test/project-config-cache.test.ts b/packages/server/test/project-config-cache.test.tsindex ba53eeb3..325a8325 100644--- a/packages/server/test/project-config-cache.test.ts+++ b/packages/server/test/project-config-cache.test.ts@@ -46,19 +46,14 @@ describe("project-config read cache", () => {await fs.rm(root, { recursive: true, force: true });});- /** This fixture's model has no schedule, so both tiers are the one price it stores. */+ /** The price this fixture's model stores. Its id has no schedule, so the instant is immaterial. */const RATES = { cacheRead: 1, cacheWrite: 2, output: 3 };+ const AT = new Date("2026-08-31T01:30:00Z");it("repeat reads cost one readFile: pricing, name and the typed loadConfig view share the cached parse", async () => {const reads = vi.spyOn(fs, "readFile");- expect(await svc.getPricing(P, "custom", "m1")).toEqual({- peak: RATES,- offPeak: RATES,- });- expect(await svc.getPricing(P, "custom", "m1")).toEqual({- peak: RATES,- offPeak: RATES,- });+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);expect(await svc.getName(P)).toBe("cached");expect((await svc.loadConfig(P)).models.map((m) => m.model_id)).toEqual(["m1"]);expect(reads).toHaveBeenCalledTimes(1);@@ -70,10 +65,7 @@ describe("project-config read cache", () => {await backdate(file, "2026-01-01T00:01:00Z");const reads = vi.spyOn(fs, "readFile");expect(await svc.getName(P)).toBe("renamed");- expect(await svc.getPricing(P, "custom", "m1")).toEqual({- peak: RATES,- offPeak: RATES,- });+ expect(await svc.getPricing(P, "custom", "m1", AT)).toEqual(RATES);expect(reads).toHaveBeenCalledTimes(1);});@@ -87,7 +79,7 @@ describe("project-config read cache", () => {await backdate(file, "2026-01-01T00:02:00Z"); // Stable, but a different mtime than cached.expect(await svc.getName(P)).toBe("edited");expect((await svc.loadConfig(P)).models.map((m) => m.model_id)).toEqual(["m2"]);- expect(await svc.getPricing(P, "custom", "m1")).toBeUndefined();+ expect(await svc.getPricing(P, "custom", "m1", AT)).toBeUndefined();});it("a fresh mtime is never cached as clean: reads keep hitting disk until the file has been quiet", async () => {diff --git a/packages/server/test/trace-service.test.ts b/packages/server/test/trace-service.test.tsindex fb38312d..e07bf7b3 100644--- a/packages/server/test/trace-service.test.ts+++ b/packages/server/test/trace-service.test.ts@@ -6,15 +6,18 @@import fs from "node:fs/promises";import { afterEach, beforeEach, describe, expect, it } from "vitest";import {+ DEEPSEEK_OFF_PEAK,abortEvent,approvalDecision,assistantText,buildBackgroundTaskDoneMessage,+ catalogEntryFor,compactionBegin,compactionEnd,imageUrlMessage,mcpConnectBegin,mcpConnectEnd,+ offPeakAt,requestBegin,requestEnd,sessionMeta,@@ -42,7 +45,8 @@ import { wire } from "@lmliheng/penguin-core/kernel";import { ErrorsRepo } from "../src/db/repos/errors.js";import { UsageRepo } from "../src/db/repos/usage.js";import { SessionSources } from "../src/runtime/session-sources.js";-import { UsageService } from "../src/services/usage-service.js";+import { UsageRecorder } from "../src/runtime/usage-recorder.js";+import { UsageService, requestCostUsd } from "../src/services/usage-service.js";import type { PricingLookup } from "../src/services/usage-service.js";import { makeTempRoot, makeTraceHarness, writeTraceFile } from "./helpers.js";@@ -242,59 +246,86 @@ describe("trace-service", () => {];};- it("prices each Request at the tier its own timestamp ran in, and the file adds up to what the cost center bills the same rows", async () => {- // A DeepSeek reference carries the catalog's Beijing-hours schedule; the lookup answers- // both tiers, as project-config-service does for a row still at the catalog's price.+ it("prices each Request at the tier its own timestamp ran in, and the file adds up to what the cost center fixed for the same rows", async () => {+ // A DeepSeek reference still storing the catalog's peak price bills by the catalog's+ // Beijing-hours schedule, so the lookup answers as project-config-service does for such a+ // row: the peak rate inside the windows, half of it outside, for the instant it is asked for.const REF = { provider: "deepseek", model_id: "deepseek-flash" };+ const peak = catalogEntryFor(REF.provider, REF.model_id)!.pricing!;+ const stored = {+ cacheRead: peak.cache_read,+ cacheWrite: peak.cache_write,+ output: peak.output,+ };+ const half = (v: number): number => Math.round(v * 0.5 * 1e6) / 1e6;+ const offPeakRates = {+ cacheRead: half(stored.cacheRead),+ cacheWrite: half(stored.cacheWrite),+ output: half(stored.output),+ };const lookups: string[] = [];- const lookup: PricingLookup = async (projectId, provider, modelId) => {- lookups.push(`${projectId}/${provider}/${modelId}`);- return {- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },- };+ const lookup: PricingLookup = async (projectId, provider, modelId, at) => {+ lookups.push(`${projectId}/${provider}/${modelId}@${at.toISOString()}`);+ return offPeakAt(DEEPSEEK_OFF_PEAK, at) ? offPeakRates : stored;};const priced = makeTraceHarness(root, { lookupPricing: lookup });const usage = buckets(10, 1, 5);- // Tuesday 10:30 Beijing (peak), Tuesday 21:00 Beijing (off-peak), Sunday 11:00 Beijing- // (an hour a weekday bills at peak, off-peak on a weekend).+ const counts = { cacheRead: 10, cacheWrite: 1, output: 5 };+ // Tuesday 10:30 Beijing (peak), Tuesday 21:00 Beijing (off-peak), Sunday 11:00 Beijing (an+ // hour a weekday bills at peak, off-peak on a weekend) and ten minutes after that last one,+ // which must share its lookup rather than read the Project's config again.const stamps = ["2026-07-07T02:30:00.000Z","2026-07-07T13:00:00.000Z","2026-07-12T03:00:00.000Z",+ "2026-07-12T03:10:00.000Z",];+ /** The instant a turn's usage is stamped at: its request plus the three seconds of `priceTurn`. */+ const usageAt = (ts: string): string => new Date(Date.parse(ts) + 3000).toISOString();try {await writeTraceFile(root, P, A, "2026-07-07", S, 1, [sessionMeta(metaPayload(REF)),...stamps.flatMap((ts) => priceTurn(ts, usage)),]);const a = await priced.service.analyze(P, A, S, 1);- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;- expect(a.tasks.map((t) => t.cost)).toEqual([peakCost, peakCost / 2, peakCost / 2]);- expect(a.cost).toBeCloseTo(peakCost * 2, 12);- expect(lookups).toEqual([`${P}/deepseek/deepseek-flash`]);+ const peakCost = requestCostUsd(counts, stored);+ const offPeakCost = requestCostUsd(counts, offPeakRates);+ expect(offPeakCost).toBeLessThan(peakCost);+ expect(a.tasks.map((t) => t.cost)).toEqual([peakCost, offPeakCost, offPeakCost, offPeakCost]);+ expect(a.cost).toBeCloseTo(peakCost + offPeakCost * 3, 12);+ // One lookup per hour a Trace spans, not one per Request: the four stamps fall in three+ // hours (two of them off-peak for different reasons), and each is asked for at its own+ // instant.+ expect(lookups).toEqual([+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[0]!)}`,+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[1]!)}`,+ `${P}/deepseek/deepseek-flash@${usageAt(stamps[2]!)}`,+ ]);- // The same three requests as usage rows, priced by the cost center's session grouping —- // the figure the conversation toolbar shows — land on the file's total.+ // The same Requests as the recorder fixes them — each priced at its own completion,+ // from the same lookup — summed by the cost center's session grouping (the figure the+ // conversation toolbar shows) land on the file's total.const db = openDatabase(":memory:");try {const rows = wire(UsageRepo, { db });for (const ts of stamps) {- const at = new Date(Date.parse(ts) + 3000).toISOString();- rows.insert({- ts: at,- date: at.slice(0, 10),- projectId: P,- agentId: A,- sessionId: S,- originSessionId: null,- provider: REF.provider,- modelId: REF.model_id,- cacheRead: usage.cache_read,- cacheWrite: usage.cache_write,- output: usage.output,- total: usage.total,+ const done = new Date(Date.parse(ts) + 3000);+ const event = tokenUsage(usage, usage);+ const recorder = wire(UsageRecorder, {+ usage: rows,+ clock: { now: () => done },+ lookupPricing: lookup,});+ await recorder.record(+ {+ projectId: P,+ agentId: A,+ sessionId: S,+ provider: REF.provider,+ modelId: REF.model_id,+ },+ event,+ );}const center = wire(UsageService, {usage: rows,@@ -317,13 +348,7 @@ describe("trace-service", () => {const priced = makeTraceHarness(root, {lookupPricing: async (_projectId, provider, modelId) => {lookups.push(`${provider}/${modelId}`);- // A second tier the schedule gate must never reach for an unscheduled reference.- return modelId === "m1"- ? {- peak: { cacheRead: 1, cacheWrite: 1, output: 1 },- offPeak: { cacheRead: 0, cacheWrite: 0, output: 0 },- }- : undefined;+ return modelId === "m1" ? { cacheRead: 1, cacheWrite: 1, output: 1 } : undefined;},});try {diff --git a/packages/server/test/usage.test.ts b/packages/server/test/usage.test.tsindex 030ec926..f8c7cf8d 100644--- a/packages/server/test/usage.test.ts+++ b/packages/server/test/usage.test.ts@@ -1,25 +1,27 @@/**- * Usage persistence and statistics behind the cost center. Only Tokens are persisted; cost is- * priced against the current pricing at query time.+ * Usage persistence and statistics behind the cost center. Each record's cost is fixed when the+ * row is written, from the price its Project stores for the paired reference at that instant: a+ * later price edit, preset sync or promotion only changes what later Requests cost.** Recording:- * - A token_usage message is one row of Tokens (never a cost); anything else writes nothing.+ * - A token_usage message is one row, with its cost fixed by the recorder here; a request_end+ * that is not `completed` writes 0 tokens + status, priced the same way (0 for a priced model).* - A sub-session's usage is attributed to its own model through its session_meta, and falls* back to the main Session's model when that mapping is missing or was evicted past its cap.** Querying:- * - A scheduled model is priced per record by the tier its request ran in, each seller by its- * own windows, so a finished period's total never moves with the clock.- * - The summary cards cover today, the last 7 days and everything; a model without pricing is- * flagged, and a price added later prices past records at once; only the references the- * response prices are looked up.+ * - Nothing is re-priced: every figure sums the costs recorded, so a finished period's total+ * never moves with the clock.+ * - The summary cards cover today, the last 7 days and everything; a Model with no price is+ * flagged, a price added later never re-prices the rows already written, and no query looks a+ * price up at all.* - Groups aggregate by date (newest first), Agent, model and Session, folded across models and* narrowed by Agent and range.* - Success counts completed requests over every non-aborted one: a user's Stop is not a model* failure.* - Model totals sum every record a model ever wrote, per paired reference, per Project.- * - Lifetime cost is that same whole history priced at the current rates, one number per- * Project: null while nothing could be priced, and flagged when a Model has no price.+ * - Lifetime cost is that same whole history summed from the recorded costs, one number per+ * Project: null while nothing was priced, and flagged when a Model has no price.* - Series are zero-filled buckets by minute, hour (local clock), day, ISO week or month, with* per-Agent and per-model series aligned to them; a minute series needs a timestamp window,* the range defaults to 30 days, and an oversized series is refused.@@ -29,13 +31,20 @@* covered through its route in errors.test.ts).*/import { afterEach, beforeEach, describe, expect, it } from "vitest";-import { sessionMeta, tokenUsage, withOrigin } from "@lmliheng/penguin-core";+import {+ catalogEntryFor,+ offPeakAt,+ requestEnd,+ sessionMeta,+ tokenUsage,+ withOrigin,+} from "@lmliheng/penguin-core";import type { SessionMetaPayload, TokenCounts } from "@lmliheng/penguin-core";import { ORIGIN_MODELS_MAX, UsageRecorder } from "../src/runtime/usage-recorder.js";import { ErrorsRepo } from "../src/db/repos/errors.js";import { UsageRepo } from "../src/db/repos/usage.js";-import { UsageService } from "../src/services/usage-service.js";-import type { PricingRates } from "../src/services/usage-service.js";+import { UsageService, requestCostUsd } from "../src/services/usage-service.js";+import type { PricingLookup, PricingRates } from "../src/services/usage-service.js";import { openDatabase } from "../src/db/database.js";import { enumerateBuckets, enumerateTsBuckets, formatLocalDate } from "../src/internal/dates.js";import type { DatabaseSync } from "node:sqlite";@@ -68,6 +77,9 @@ function meta(sessionId: string, modelId: string, provider = "custom"): SessionMdescribe("usage-recorder", () => {let db: DatabaseSync;let repo: UsageRepo;+ /** A recorder whose price lookup answers `stored` (default: no price anywhere). */+ const recorder = (lookupPricing: PricingLookup = async () => undefined, now = new Date()) =>+ wire(UsageRecorder, { usage: repo, clock: { now: () => now }, lookupPricing });beforeEach(() => {db = openDatabase(":memory:");@@ -75,9 +87,14 @@ describe("usage-recorder", () => {});afterEach(() => db.close());- it("token_usage → one row (the request bucket; only Tokens persisted, never cost)", async () => {- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });- await rec.record(CTX, tokenUsage(counts(1000), counts(115)));+ it("token_usage → one row (the request bucket), its cost fixed from the price the Project stores", async () => {+ // The lookup stands in for getPricing: the one price the Project bills for a reference. What+ // core stamps on the event is not consulted at all — a promotion lives in web.db beside the+ // file's list price, so only this side can state what a Request cost.+ await recorder(async () => ({ cacheRead: 1, cacheWrite: 2, output: 4 })).record(+ CTX,+ tokenUsage(counts(1000), counts(115)),+ );const rows = db.prepare("SELECT * FROM usage_records").all();expect(rows).toHaveLength(1);const row = rows[0]!;@@ -86,10 +103,92 @@ describe("usage-recorder", () => {expect(row.model_id).toBe("main-model");expect(row.total).toBe(115); // taken from request.totalexpect(row.cache_read).toBe(100);+ expect(row.cost).toBeCloseTo((100 * 1 + 10 * 2 + 5 * 4) / 1e6, 15);+ expect(row.cost_settled).toBe(1);+ });++ it("a model with no price: the row is written uncosted, and settled", async () => {+ await recorder(async () => undefined).record(CTX, tokenUsage(counts(10), counts(10)));+ const row = db.prepare("SELECT cost, cost_settled FROM usage_records").get()!;+ expect(row.cost).toBeNull();+ expect(row.cost_settled).toBe(1);+ });++ it("the price is asked at the instant the row is written: the same stored peak price bills half off-peak", async () => {+ // A DeepSeek row still storing the catalog's peak price, written at 20:00 Beijing on a Monday+ // (2026-08-31), is billed the off-peak tier — the tier is a fact about when the row was+ // written, never about when someone opens the page (the defect this change fixes).+ //+ // The lookup stands in for getPricing, which folds the stored price, the row's promotion and+ // that instant's tier: what this test pins is that the recorder asks it at its OWN clock's+ // instant and takes the answer as the bill.+ const entry = catalogEntryFor("deepseek", "deepseek-flash")!;+ const peak = entry.pricing!;+ const schedule = entry.offPeakDiscount!;+ const off = (v: number): number => Math.round(v * (1 - schedule.rate) * 1e6) / 1e6;+ const stored = {+ cacheRead: peak.cache_read,+ cacheWrite: peak.cache_write,+ output: peak.output,+ };+ const asked: string[] = [];+ const ctx = { ...CTX, provider: "deepseek", modelId: "deepseek-flash" };+ const recorderAt = (at: Date) =>+ recorder(async (_p, provider, modelId, when) => {+ asked.push(`${provider}/${modelId}@${when.toISOString()}`);+ return offPeakAt(schedule, when)+ ? {+ cacheRead: off(stored.cacheRead),+ cacheWrite: off(stored.cacheWrite),+ output: off(stored.output),+ }+ : stored;+ }, at);++ await recorderAt(new Date("2026-08-31T01:30:00Z")).record(+ ctx,+ tokenUsage(counts(115), counts(115)),+ );+ const peakRow = db.prepare("SELECT cost FROM usage_records").get()!;+ db.prepare("DELETE FROM usage_records").run();+ await recorderAt(new Date("2026-08-31T12:00:00Z")).record(+ ctx,+ tokenUsage(counts(115), counts(115)),+ );+ const offRow = db.prepare("SELECT cost FROM usage_records").get()!;++ expect(asked).toEqual([+ "deepseek/deepseek-flash@2026-08-31T01:30:00.000Z",+ "deepseek/deepseek-flash@2026-08-31T12:00:00.000Z",+ ]);+ expect(peakRow.cost).toBeCloseTo(+ requestCostUsd({ cacheRead: 100, cacheWrite: 10, output: 5 }, stored),+ 15,+ );+ // The off-peak rates are the stored ones rounded to six decimals, so the half-price figure+ // agrees with the peak one to a few parts in 1e12 rather than exactly.+ expect(offRow.cost).toBeCloseTo((peakRow.cost as number) * (1 - schedule.rate), 10);+ });++ it("a failed Request costs 0 on a priced model and nothing on an unpriced one; a failing lookup still writes the row", async () => {+ await recorder(async () => ({ cacheRead: 1, cacheWrite: 1, output: 1 })).record(+ CTX,+ requestEnd("fatal"),+ );+ await recorder(async () => undefined).record(CTX, requestEnd("fatal"));+ await recorder(async () => {+ throw new Error("config unreadable");+ }).record(CTX, tokenUsage(counts(5), counts(5)));+ const rows = db.prepare("SELECT status, cost FROM usage_records ORDER BY id").all();+ expect(rows).toEqual([+ { status: "fatal", cost: 0 },+ { status: "fatal", cost: null },+ { status: "completed", cost: null },+ ]);});it("a sub-session's session_meta registers the origin→model mapping; token_usage is attributed via it", async () => {- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });+ const rec = recorder();const childMeta = withOrigin(sessionMeta(meta("session-child", "child-model")),"session-child",@@ -103,20 +202,20 @@ describe("usage-recorder", () => {});it("falls back to the main Session's Model when the origin mapping is missing", async () => {- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });+ const rec = recorder();await rec.record(CTX, withOrigin(tokenUsage(counts(5), counts(5)), "session-unknown"));const row = db.prepare("SELECT model_id FROM usage_records").get()!;expect(row.model_id).toBe("main-model");});it("non-token_usage messages are a no-op", async () => {- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });+ const rec = recorder();await rec.record(CTX, sessionMeta(meta("session-main", "main-model")));expect(db.prepare("SELECT COUNT(*) AS n FROM usage_records").get()!.n).toBe(0);});it("the origin mapping is capped: past the limit the earliest entry is evicted and falls back to the main Session's Model", async () => {- const rec = wire(UsageRecorder, { usage: repo, clock: { now: () => new Date() } });+ const rec = recorder();for (let i = 0; i <= ORIGIN_MODELS_MAX; i++) {// ORIGIN_MODELS_MAX + 1 entries total: the earliest, sub-0, gets evicted.await rec.record(CTX, withOrigin(sessionMeta(meta(`sub-${i}`, "sub-model")), `sub-${i}`));@@ -129,19 +228,20 @@ describe("usage-recorder", () => {});});-describe("usage-service (cost computed on the fly)", () => {+describe("usage-service (sums the costs fixed at record time)", () => {let db: DatabaseSync;let repo: UsageRepo;let service: (now: Date) => UsageService;- /** Mutable pricing table: simulates a "price added later" — change the price after inserting a record, and the query reflects it immediately. */+ /**+ * The price each model has when a row is WRITTEN: `insert` fixes the row's cost from it, as the+ * recorder does. Changing it afterwards simulates a later price edit — which must not move a+ * recorded row.+ */let pricing: Record<string, PricingRates | undefined>;- // The pricing lookup callback takes three params (projectId, provider, modelId): locates the- // price via the paired reference. These fixtures use models with no schedule, so both tiers- // are the one rate — a scheduled model's two tiers are exercised in the peak-split test below.- const lookup = async (_p: string, _provider: string, modelId: string) => {- const rates = pricing[modelId];- return rates === undefined ? undefined : { peak: rates, offPeak: rates };+ /** Queries never look a price up: they sum what was recorded. */+ const lookup: PricingLookup = async () => {+ throw new Error("a usage query must not re-price recorded rows");};beforeEach(() => {@@ -158,7 +258,16 @@ describe("usage-service (cost computed on the fly)", () => {const ROW_COST = (10 * 0.3 + 1 * 3.75 + 5 * 15) / 1e6;function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {+ const row = {+ cacheRead: 10,+ cacheWrite: 1,+ output: 5,+ modelId: "m1",+ ...opts,+ };+ const rates = pricing[row.modelId];repo.insert({+ cost: rates === undefined ? null : requestCostUsd(row, rates),ts: `${date}T00:00:00.000Z`,date,projectId: "p1",@@ -175,63 +284,21 @@ describe("usage-service (cost computed on the fly)", () => {});}- it("a scheduled model is priced per record, and the total does not move with the clock", async () => {- // The defect this pins: pricing the whole table at whichever tier is in force when the page- // is opened made a finished week's cost double at 09:00 Beijing and halve at 12:00. The tier- // is a fact about when each request ran, so it is decided from that record's own `ts`.- //- // 2026-08-31 is a Monday. 01:30Z is 09:30 in Beijing (peak); 12:00Z is 20:00 (off-peak).- const REF = { provider: "deepseek", modelId: "deepseek-flash" };- insert("2026-08-31", { ...REF, ts: "2026-08-31T01:30:00.000Z" });- insert("2026-08-31", { ...REF, ts: "2026-08-31T12:00:00.000Z" });- pricing["deepseek-flash"] = { cacheRead: 1, cacheWrite: 2, output: 4 };- const tiered = async () => ({- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },- });- // One row's Tokens are cacheRead 10 / cacheWrite 1 / output 5, so the peak record costs- // (10*1 + 1*2 + 5*4)/1e6 and the off-peak one exactly half of that.- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;- const expected = peakCost + peakCost / 2;+ it("a query sums the recorded costs, and the total does not move with the clock", async () => {+ // Two rows fixed at different rates (the tier each ran in, decided when it was recorded):+ // reading them at any hour gives the same total.+ insert("2026-08-31", { ts: "2026-08-31T01:30:00.000Z", cost: 0.002 });+ insert("2026-08-31", { ts: "2026-08-31T12:00:00.000Z", cost: 0.001 });for (const at of ["2026-08-31T01:30:00Z", "2026-08-31T12:00:00Z", "2026-09-06T01:30:00Z"]) {- const svc = wire(UsageService, {- usage: repo,- errors: wire(ErrorsRepo, { db: db }),- lookupPricing: tiered,- clock: { now: () => new Date(at) },+ const res = await service(new Date(at)).query("p1", {+ groupBy: "date",+ from: "2026-08-31",+ to: "2026-08-31",});- const res = await svc.query("p1", { groupBy: "date", from: "2026-08-31", to: "2026-08-31" });- expect(res.summary.total.cost, at).toBeCloseTo(expected, 10);+ expect(res.summary.total.cost, at).toBeCloseTo(0.003, 12);}});- it("each scheduled reference is priced by its own seller's windows in the same query", async () => {- // Two schedules in the catalog: Qwen's DeepSeek rows bill peak 08:00-22:00 Beijing every- // day, DeepSeek's own rows only in weekday office hours. 2026-09-05 is a Saturday: 02:00Z- // is 10:00 in Beijing (peak for Qwen, off-peak for DeepSeek), 15:00Z is 23:00 (off-peak for- // both).- const QWEN = { provider: "qwen-pay-as-you-go", modelId: "deepseek-v4.1-flash" };- const DEEPSEEK = { provider: "deepseek", modelId: "deepseek-flash" };- insert("2026-09-05", { ...QWEN, ts: "2026-09-05T02:00:00.000Z" });- insert("2026-09-05", { ...QWEN, ts: "2026-09-05T15:00:00.000Z" });- insert("2026-09-05", { ...DEEPSEEK, ts: "2026-09-05T02:00:00.000Z" });- const svc = wire(UsageService, {- usage: repo,- errors: wire(ErrorsRepo, { db: db }),- lookupPricing: async () => ({- peak: { cacheRead: 1, cacheWrite: 2, output: 4 },- offPeak: { cacheRead: 0.5, cacheWrite: 1, output: 2 },- }),- clock: { now: () => new Date("2026-09-05T12:00:00Z") },- });- const res = await svc.query("p1", { groupBy: "model", from: "2026-09-05", to: "2026-09-05" });- const costOf = (ref: { provider: string; modelId: string }) =>- res.groups.find((g) => g.provider === ref.provider && g.key === ref.modelId)?.cost;- const peakCost = (10 * 1 + 1 * 2 + 5 * 4) / 1e6;- expect(costOf(QWEN)).toBeCloseTo(peakCost + peakCost / 2, 10);- expect(costOf(DEEPSEEK)).toBeCloseTo(peakCost / 2, 10);- });-it("summary cards: today / last 7 days / cumulative; Models without pricing flag hasUncosted", async () => {const now = new Date("2026-07-06T10:00:00");const today = formatLocalDate(now);@@ -249,19 +316,27 @@ describe("usage-service (cost computed on the fly)", () => {expect(res.summary.last7d.hasUncosted).toBe(false);});- it("price added later: no pricing at insert time; once configured, queries price it immediately", async () => {+ it("a price changed later never re-prices a recorded row: only the rows written after it carry it", async () => {const now = new Date("2026-07-06T10:00:00");- insert("2026-07-06", { modelId: "m-late" });+ insert("2026-07-06", { modelId: "m-late" }); // no price yet: recorded uncosted+ insert("2026-07-06"); // m1 at its old priceconst svc = service(now);const before = await svc.query("p1", { groupBy: "date" });- expect(before.summary.total.cost).toBeNull();+ expect(before.summary.total.cost).toBeCloseTo(ROW_COST, 12);expect(before.summary.total.hasUncosted).toBe(true);+ // A price added for m-late and m1 re-priced: the two recorded rows keep their figures.pricing["m-late"] = { cacheRead: 1, cacheWrite: 1, output: 1 };+ pricing.m1 = { cacheRead: 100, cacheWrite: 100, output: 100 };+ const unchanged = await svc.query("p1", { groupBy: "date" });+ expect(unchanged.summary.total.cost).toBeCloseTo(ROW_COST, 12);+ expect(unchanged.summary.total.hasUncosted).toBe(true);++ insert("2026-07-06", { modelId: "m-late" });const after = await svc.query("p1", { groupBy: "date" });- expect(after.summary.total.cost).toBeCloseTo((10 + 1 + 5) / 1e6, 12);- expect(after.summary.total.hasUncosted).toBe(false);+ expect(after.summary.total.cost).toBeCloseTo(ROW_COST + (10 + 1 + 5) / 1e6, 12);+ expect(after.summary.total.hasUncosted).toBe(true); // the first m-late row stays uncosted});it("group aggregation: date sorted descending; agent/model/session dimensions with agentId drill-down; folded across Models", async () => {@@ -290,25 +365,16 @@ describe("usage-service (cost computed on the fly)", () => {expect(other.groups).toEqual([]);});- it("pricing is looked up for every reference the response prices, and only those", async () => {+ it("every cost figure in a response is the recorded sum, with no price lookup at all", async () => {const now = new Date("2026-07-06T10:00:00");- pricing["m-old"] = { cacheRead: 1, cacheWrite: 1, output: 1 };insert("2026-07-06", { modelId: "m1" });- // Inside the last 30 days but outside the requested range: no surviving aggregate- // covers it, so it must not be priced — and must not perturb the ones that are.- insert("2026-06-20", { modelId: "m-old" });- const asked: string[] = [];- const svc = wire(UsageService, {- usage: repo,- errors: wire(ErrorsRepo, { db: db }),- lookupPricing: async (p: string, provider: string, modelId: string) => {- asked.push(modelId);- return lookup(p, provider, modelId);- },- clock: { now: () => now },+ // Outside the requested range: it must not perturb the figures that are in range.+ insert("2026-06-20", { modelId: "m1", cost: 1 });+ const res = await service(now).query("p1", {+ groupBy: "date",+ from: "2026-07-06",+ to: "2026-07-06",});- const res = await svc.query("p1", { groupBy: "date", from: "2026-07-06", to: "2026-07-06" });- expect(asked).toEqual(["m1"]);expect(res.summary.total.cost).toBeCloseTo(ROW_COST, 12);expect(res.summary.today.cost).toBeCloseTo(ROW_COST, 12);expect(res.groups[0]!.cost).toBeCloseTo(ROW_COST, 12);@@ -433,6 +499,7 @@ describe("usage-service model totals (unfiltered, for the models page)", () => {function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {repo.insert({+ cost: null,ts: `${date}T00:00:00.000Z`,date,projectId: "p1",@@ -478,11 +545,9 @@ describe("usage-service series (zero-filled time-series buckets)", () => {let db: DatabaseSync;let repo: UsageRepo;let service: (now: Date) => UsageService;+ /** The price a row's cost is fixed at when `insert` writes it. */let pricing: Record<string, PricingRates | undefined>;- const lookup = async (_p: string, _provider: string, modelId: string) => {- const rates = pricing[modelId];- return rates === undefined ? undefined : { peak: rates, offPeak: rates };- };+ const lookup: PricingLookup = async () => undefined;beforeEach(() => {db = openDatabase(":memory:");@@ -497,7 +562,10 @@ describe("usage-service series (zero-filled time-series buckets)", () => {const ROW_COST = (10 * 0.3 + 1 * 3.75 + 5 * 15) / 1e6;function insert(date: string, opts: Partial<Parameters<UsageRepo["insert"]>[0]> = {}): void {+ const row = { cacheRead: 10, cacheWrite: 1, output: 5, modelId: "m1", ...opts };+ const rates = pricing[row.modelId];repo.insert({+ cost: rates === undefined ? null : requestCostUsd(row, rates),ts: `${date}T00:00:00.000Z`,date,projectId: "p1",@@ -706,6 +774,123 @@ describe("usage-service series (zero-filled time-series buckets)", () => {});});+describe("usage-service settleUnsettledCosts (COMPATIBILITY: rows from before costs were fixed)", () => {+ let db: DatabaseSync;+ let repo: UsageRepo;++ beforeEach(() => {+ db = openDatabase(":memory:");+ repo = wire(UsageRepo, { db: db });+ });+ afterEach(() => db.close());++ const COUNTS = { cacheRead: 10, cacheWrite: 1, output: 5 };++ /** A row as a build that did not price rows wrote it: Tokens only, cost_settled left at 0. */+ function legacyRow(ts: string, provider: string, modelId: string): void {+ db.prepare(+ `INSERT INTO usage_records+ (ts, date, project_id, agent_id, session_id, provider, model_id, cache_read, cache_write, output, total)+ VALUES (?, ?, 'p1', 'a1', 's1', ?, ?, 10, 1, 5, 16)`,+ ).run(ts, ts.slice(0, 10), provider, modelId);+ }++ it("costs each old row once, at the price its Project stores now, at the tier its own timestamp fell in", async () => {+ // The lookup stands in for `getPricing`: what the Project bills for a reference, at the+ // instant asked — list price, the row's promotion and that instant's tier, all folded in. A+ // scheduled reference's two legacy rows, eight hours of Beijing time apart, therefore settle+ // at the two different tiers they actually ran in rather than at one hour of the clock's.+ const deepseekEntry = catalogEntryFor("deepseek", "deepseek-v4-flash")!;+ const schedule = deepseekEntry.offPeakDiscount!;+ const peak = deepseekEntry.pricing!;+ const peakRate = {+ cacheRead: peak.cache_read,+ cacheWrite: peak.cache_write,+ output: peak.output,+ };+ const less = (v: number, fraction: number): number =>+ Math.round(v * (1 - fraction) * 1e6) / 1e6;+ const half = (v: number): number => less(v, schedule.rate);+ // A catalog row on a flat promotion: the Project's price for it is the list rate less that+ // fraction, at either tier (glm-5.3-flash has no schedule).+ const promoted = catalogEntryFor("tokendance", "glm-5.3-flash")!;+ expect(promoted.discount).toBeGreaterThan(0);+ const list = promoted.pricing!;+ const discounted = {+ cacheRead: less(list.cache_read, promoted.discount!),+ cacheWrite: less(list.cache_write, promoted.discount!),+ output: less(list.output, promoted.discount!),+ };+ const lookups: string[] = [];+ const svc = wire(UsageService, {+ usage: repo,+ errors: wire(ErrorsRepo, { db: db }),+ lookupPricing: async (_p: string, provider: string, modelId: string, at: Date) => {+ lookups.push(`${provider}/${modelId}@${at.toISOString()}`);+ if (provider === "deepseek") {+ return offPeakAt(schedule, at)+ ? {+ cacheRead: half(peakRate.cacheRead),+ cacheWrite: half(peakRate.cacheWrite),+ output: half(peakRate.output),+ }+ : peakRate;+ }+ if (provider === "tokendance") return discounted;+ return undefined;+ },+ clock: { now: () => new Date() },+ });+ // Monday 2026-08-31: 01:30Z is 09:30 Beijing (peak), 12:00Z is 20:00 (off-peak).+ legacyRow("2026-08-31T01:30:00.000Z", "deepseek", "deepseek-v4-flash");+ legacyRow("2026-08-31T12:00:00.000Z", "deepseek", "deepseek-v4-flash");+ legacyRow("2026-08-31T12:00:00.000Z", "tokendance", "glm-5.3-flash");+ legacyRow("2026-08-31T12:00:00.000Z", "custom", "m-unpriced");+ // A row the recorder fixed is never touched, and never priced for again.+ repo.insert({+ ts: "2026-08-31T12:00:00.000Z",+ date: "2026-08-31",+ projectId: "p1",+ agentId: "a1",+ sessionId: "s1",+ originSessionId: null,+ provider: "deepseek",+ modelId: "deepseek-v4-flash",+ ...COUNTS,+ total: 16,+ cost: 42,+ });++ expect(await svc.settleUnsettledCosts()).toBe(4);+ // Every unsettled row is asked for at its OWN timestamp (the settled one is not asked for at+ // all), so the two rows of one reference settle at the tier each actually ran in.+ expect([...lookups].sort()).toEqual(+ [+ "deepseek/deepseek-v4-flash@2026-08-31T01:30:00.000Z",+ "deepseek/deepseek-v4-flash@2026-08-31T12:00:00.000Z",+ "tokendance/glm-5.3-flash@2026-08-31T12:00:00.000Z",+ "custom/m-unpriced@2026-08-31T12:00:00.000Z",+ ].sort(),+ );+ const rows = db+ .prepare("SELECT cost, cost_settled FROM usage_records ORDER BY id")+ .all() as Array<{ cost: number | null; cost_settled: number }>;+ const peakCost = requestCostUsd(COUNTS, peakRate);+ expect(rows[0]!.cost).toBeCloseTo(peakCost, 15);+ expect(rows[1]!.cost).toBeCloseTo(peakCost * (1 - schedule.rate), 10);+ expect(rows[1]!.cost).toBeLessThan(rows[0]!.cost!);+ expect(rows[2]!.cost).toBeCloseTo(requestCostUsd(COUNTS, discounted), 15);+ expect(rows[3]!.cost).toBeNull();+ expect(rows[4]!.cost).toBe(42);+ expect(rows.every((r) => r.cost_settled === 1)).toBe(true);++ // A second boot finds nothing left to settle, and reads no price for it.+ lookups.length = 0;+ expect(await svc.settleUnsettledCosts()).toBe(0);+ expect(lookups).toEqual([]);+ });+});+describe("bucket enumeration across a DST transition", () => {// The zero-fill skeleton and SQLite's `strftime(..., 'localtime')` must agree key for key.// A fall-back replays a whole local hour, so two instants an hour apart share one key;