@flame0510/project-aether 1.9.1 → 1.10.0

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -11,7 +11,7 @@ Understanding how current the data in Rev4a is — and what is truly real-time v
 **Update frequency:** every 30 seconds
 
 The daemon polls `openclaw sessions --json --all-agents` on a fixed 30-second
-timer. Session statuses, token counts, and costs are therefore up to 30 seconds
+timer. Session statuses and token counts are therefore up to 30 seconds
 behind reality.
 
 The interval is fixed: it does not speed up while a session is `working`. Do not tell
@@ -56,12 +56,24 @@ the collector is not running instead of showing stale numbers as current.
 
 ---
 
-## Cost totals
+## Agent costs (Costs page)
 
-**Update frequency:** every 30 seconds (recalculated from sessions on each API call)
+**Update frequency:** every 5 minutes. The Rev4a daemon asks each running agent
+what it spent and keeps the figures in their own database (`costs.db`); the page
+refreshes every minute. An agent whose figures could not be read recently is listed
+under **Not current** with the reason.
 
-The cost figures shown in the dashboard are always computed fresh from the
-database on each page load or SSE push. They are not cached.
+The costs are computed by each agent's own OpenClaw, with the prices Rev4a writes
+into the agent for every model. A call to a model without a price is counted but not
+priced: the page lists those under **Calls without a price**. Days are UTC. DeepSeek
+bills half price off-peak; Rev4a switches the agents' prices at each change, so each
+call is priced at the rate it ran at.
+
+## Cost totals (dashboard)
+
+The dashboard's "Spent today" card and "Spent by model" list show the same figures as the
+Costs page, for today (UTC day): up to 5 minutes behind the agents. The vendor readings
+behind *Against the bill* on the Costs page are taken once an hour.
 
 **Cost override:** `/api/cost-override` exists, but no page in the dashboard
 reads or writes it. There is no UI for setting one, so do not direct a user to
@@ -143,7 +155,7 @@ The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md
 
 System health is a card on the **Dashboard**, not a page of its own. Its checks
 cover session runtime, the daemon heartbeat, errors in the last 24 hours, today's
-usage-based cost, and cron jobs. CPU, RAM and disk are on the System page (`/system`)
+what the agents spent today, and cron jobs. CPU, RAM and disk are on the System page (`/system`)
 and the Dashboard's Machine card instead.
 
 To check directly on the server:

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -31,7 +31,10 @@ A communication channel (Telegram) configured on an agent. Channels allow users
 Modal in the agent detail panel for configuring Telegram channels. Connect with bot token, restart agent, manage pairings (approve pending codes, revoke approved senders). Pairings are polled every 5 seconds with automatic cancellation of stale requests via AbortController.
 
 ## Cost
-The estimated cost of an agent session in USD, calculated from tokens used and per-model pricing. Rev4a shows cost by today, 7 days, 30 days, all-time, and by model.
+What an agent spent in USD. Each agent's OpenClaw prices every model call itself, with the prices Rev4a writes into it (input, output, cached input), and Rev4a reads those figures every 5 minutes. The Costs page (`/costs`) shows them for today, 7 or 30 days — by day, by agent, by model, and the most expensive sessions. The dashboard's "Spent today" card shows the same figures for today, and each agent's panel on the Agents page has a COSTS section with its own. The Costs page also compares the agents' figures with what DeepSeek and OpenRouter actually billed (their balance or usage, read every hour).
+
+## Off-peak
+DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header shows the current band.
 
 ## Cost Override
 A manual correction for a month's total cost, stored through `/api/cost-override`. There is currently no screen for it: no page in the dashboard reads or writes an override, so it can only be set by calling the API directly.
@@ -85,7 +88,7 @@ Replace an agent's persistent volume with a previously created backup. The conta
 Undo an agent's latest OpenClaw update: the backup taken just before the update is put back and the agent starts again on its previous version. Anything the agent did after the update is lost. Offered in the agent's OPENCLAW VERSION section while that backup exists.
 
 ## Session
-One instance of an agent doing work. Tracks: start/end time, tokens used, cost, model, status, and task description. A session starts when an agent receives a task and ends when it completes or fails.
+One instance of an agent doing work. Tracks: start/end time, tokens used, model, status, and task description; what a session cost is on the Costs page (most expensive sessions). A session starts when an agent receives a task and ends when it completes or fails.
 
 ## Pairing
 A security mechanism for Telegram channels. When a user sends `/start` to the bot, a 4-digit pairing code is generated. An admin must approve this code in the Channel Manager to add the user to the allowlist. Approved senders can be revoked at any time.
@@ -134,6 +137,6 @@ The directory where an agent's operational files live (config, memory files, ski
 The page with the machine Rev4a runs on: CPU (with cores and load), memory and swap, and each disk's used and free space, now and over 1 hour, 24 hours, 7 days or 30 days. A bar turns yellow and then red when it reaches a threshold (CPU and memory 85 % / 95 %, disk 80 % / 90 %), and the level is written next to it.
 
 ## System Health
-A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, the daemon heartbeat (how old its latest machine sample is), errors in the last 24 hours, today's usage-based cost, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
+A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, the daemon heartbeat (how old its latest machine sample is), errors in the last 24 hours, today's what the agents spent today, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
 
 It reports no CPU, RAM, disk or load average: those are on the System page (`/system`), sampled every 30 seconds by the daemon and kept for 30 days.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
@@ -81,6 +81,9 @@ Full list of all Docker containers on the server, including stopped ones. Each r
 
 The page shows no CPU or memory figures and has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
 
+### Costs (`/costs`)
+What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS).
+
 ### System (`/system`)
 The machine Rev4a runs on. Three cards — CPU (percent, cores, load average), memory (used, available, swap) and storage (each disk with its used and free space, and whether it is the system disk, where Docker keeps agents, or where Rev4a keeps its data) — then charts of CPU, memory and each disk over 1 hour, 24 hours, 7 days or 30 days (for CPU and memory the average line with the peak shaded). Hover a chart (or focus it and use the arrow keys) to read a point; each chart has a Table view. Bars turn yellow and red when they reach their thresholds. Figures refresh every 30 seconds; history is kept 30 days.
 

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -20,7 +20,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How does the custom agent bootstrap work?"
 - "Where is the lineage graph?"
 - "How do I open the file explorer?"
-- "Which page shows costs?"
+- "Which page shows costs?" — The Costs page (`/costs`): what each agent spent, by day, agent, model and session.
 - "Where do I manage credentials (GitHub, Trello, etc.)?"
 - "How do I connect an agent to Telegram?"
 - "How do I approve a Telegram pairing?"
@@ -93,7 +93,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 ## Troubleshooting Questions
 
 - "Why is my agent not showing up?"
-- "Why are costs missing for some sessions?"
+- "Why are costs missing for some sessions?" — On the Costs page, calls to a model without a price are listed under "Calls without a price": the model left the catalogue or has no price yet.
 - "Why can't I connect to the container terminal?"
 - "Why is the gateway sync not working?"
 - "How do I check if the daemon is running?"

package/instrumentation.ts

@@ -7,12 +7,14 @@
  */
 export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
+    let startupSynced = false;
     try {
       const { syncAllAgents } = await import('./app/api/gateway/sync');
       // The outcome used to be discarded. syncAllAgents reports failures instead of
       // throwing, so the catch below never saw a sync that reached no container —
       // Docker not yet up at boot left the fleet stale with nothing in the log.
       const outcome = syncAllAgents();
+      startupSynced = outcome.ok;
       if (outcome.ok) {
         console.log(`[rev4a] Startup sync: ${outcome.summary}`);
       } else {
@@ -22,6 +24,15 @@ export async function register() {
       // Best-effort — don't block startup if sync fails
       console.warn('[rev4a] Failed to sync agents on startup');
     }
+    // Prices that change with the time of day (DeepSeek off-peak): write the new rates
+    // into every agent at each change, so OpenClaw prices each call at the rate it ran at.
+    // A startup sync that missed an agent is written again by the first check.
+    try {
+      const { startPriceScheduleSync } = await import('./lib/price-schedule-sync');
+      startPriceScheduleSync(startupSynced);
+    } catch {
+      console.warn('[rev4a] Could not start the price schedule re-sync');
+    }
     // Updates cut off by the restart: no job runs in a fresh process, so any update
     // still marked active becomes `interrupted` and waits for the operator.
     try {

package/lib/agent-costs.ts

@@ -0,0 +1,172 @@
+/**
+ * What the agents spent, read from costs.db — the figures each agent's own OpenClaw
+ * recorded, copied by daemon.js (see docs/dev/DATABASE.md, Costs Database). Nothing here
+ * computes a cost. The spend queries of every reader live here — the Costs page, the
+ * dashboard (GET /api/costs, the SSE stream, the system-health cost check) and the
+ * agent panel; the vendor readings are in lib/cost-reconciliation.ts.
+ *
+ * Days are UTC dates, as OpenClaw buckets them.
+ */
+import type Database from 'better-sqlite3';
+import { openCostsDb } from './costs-db';
+
+/** How often daemon.js reads the agents; a figure older than 3× this is not current. */
+export const COLLECT_INTERVAL_S = 300;
+
+export const utcDate = (ms: number) => new Date(ms).toISOString().slice(0, 10);
+
+/** The UTC dates of the last `days` days, today included, oldest first. */
+export function lastDays(days: number, now = Date.now()): string[] {
+  return Array.from({ length: days }, (_, i) => utcDate(now - (days - 1 - i) * 86_400_000));
+}
+
+export interface CostTotals {
+  cost: number; tokens: number; input: number; output: number; cacheRead: number; cacheWrite: number;
+  inputCost: number; outputCost: number; cacheReadCost: number; cacheWriteCost: number; missing: number;
+}
+export interface AgentCostRow {
+  container: string; agentId: string | null; name: string | null; cost: number; tokens: number; missing: number;
+  collectedAt: number | null; attemptedAt: number | null; error: string | null;
+}
+/**
+ * Rows without tokens or cost are left out: OpenClaw also counts internal entries as
+ * models (`gateway-injected`, messages the Gateway adds itself) that cost nothing.
+ */
+export interface ModelCostRow { provider: string; model: string; cost: number; tokens: number; calls: number }
+export interface SessionCostRow {
+  container: string; agentName: string | null; sessionId: string; sessionKey: string | null; label: string | null;
+  agentId: string | null; model: string | null; cost: number; tokens: number; missing: number; lastActivity: number | null;
+}
+export interface CostSummary {
+  totals: CostTotals;
+  daily: { date: string; cost: number; tokens: number; missing: number }[];
+  byAgent: AgentCostRow[];
+  byModel: ModelCostRow[];
+  sessions: SessionCostRow[];
+  /** Calls OpenClaw could not price, by model, over each agent's last 30 days. */
+  unpriced: { model: string; calls: number; agents: string[] }[];
+}
+
+interface SourceRow {
+  container: string; agent_id: string | null; name: string | null;
+  collected_at: number | null; attempted_at: number | null; error: string | null; missing_by_model: string | null;
+}
+
+export const EMPTY_TOTALS: CostTotals = {
+  cost: 0, tokens: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0,
+  inputCost: 0, outputCost: 0, cacheReadCost: 0, cacheWriteCost: 0, missing: 0,
+};
+
+const TOTALS_SQL = `
+  SELECT COALESCE(SUM(cost), 0) AS cost, COALESCE(SUM(total_tokens), 0) AS tokens,
+    COALESCE(SUM(input), 0) AS input, COALESCE(SUM(output), 0) AS output,
+    COALESCE(SUM(cache_read), 0) AS cacheRead, COALESCE(SUM(cache_write), 0) AS cacheWrite,
+    COALESCE(SUM(input_cost), 0) AS inputCost, COALESCE(SUM(output_cost), 0) AS outputCost,
+    COALESCE(SUM(cache_read_cost), 0) AS cacheReadCost, COALESCE(SUM(cache_write_cost), 0) AS cacheWriteCost,
+    COALESCE(SUM(missing), 0) AS missing
+  FROM agent_cost_daily`;
+
+/**
+ * Everything the Costs page shows for a range of UTC dates. `container` narrows it to
+ * one agent (the agent panel).
+ */
+export function readCostSummary(
+  db: Database.Database,
+  dates: string[],
+  opts: { container?: string; topSessions?: number } = {},
+): CostSummary {
+  const startDate = dates[0];
+  const endDate = dates[dates.length - 1];
+  const where = `date BETWEEN @startDate AND @endDate${opts.container ? ' AND container = @container' : ''}`;
+  const params = { startDate, endDate, container: opts.container ?? null };
+  const now = Date.now();
+
+  const totals = db.prepare(`${TOTALS_SQL} WHERE ${where}`).get(params) as CostTotals;
+
+  const dailyRows = db.prepare(`
+    SELECT date, SUM(cost) AS cost, SUM(total_tokens) AS tokens, SUM(missing) AS missing
+    FROM agent_cost_daily WHERE ${where} GROUP BY date`).all(params) as CostSummary['daily'];
+  const byDate = new Map(dailyRows.map((r) => [r.date, r]));
+  const daily = dates.map((date) => byDate.get(date) ?? { date, cost: 0, tokens: 0, missing: 0 });
+
+  const sources = (db.prepare('SELECT * FROM agent_cost_sources').all() as SourceRow[])
+    .filter((s) => !opts.container || s.container === opts.container);
+  const spend = new Map(
+    (db.prepare(`
+      SELECT container, SUM(cost) AS cost, SUM(total_tokens) AS tokens, SUM(missing) AS missing
+      FROM agent_cost_daily WHERE ${where} GROUP BY container`).all(params) as
+      { container: string; cost: number; tokens: number; missing: number }[]).map((r) => [r.container, r]),
+  );
+  const byAgent = sources
+    .map((s) => ({
+      container: s.container,
+      agentId: s.agent_id,
+      name: s.name,
+      cost: spend.get(s.container)?.cost ?? 0,
+      tokens: spend.get(s.container)?.tokens ?? 0,
+      missing: spend.get(s.container)?.missing ?? 0,
+      collectedAt: s.collected_at,
+      attemptedAt: s.attempted_at,
+      error: s.error,
+    }))
+    .filter((a) => a.tokens > 0 || a.missing > 0 || a.error || (a.attemptedAt ?? 0) > now - 3 * COLLECT_INTERVAL_S * 1000)
+    .sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
+
+  const byModel = db.prepare(`
+    SELECT provider, model, SUM(cost) AS cost, SUM(tokens) AS tokens, SUM(calls) AS calls
+    FROM agent_cost_model_daily WHERE ${where}
+    GROUP BY provider, model HAVING SUM(tokens) > 0 OR SUM(cost) > 0 ORDER BY cost DESC, tokens DESC`).all(params) as ModelCostRow[];
+
+  const names = new Map(sources.map((s) => [s.container, s.name]));
+  const since = Date.parse(`${startDate}T00:00:00Z`);
+  const sessions = (db.prepare(`
+    SELECT container, session_id AS sessionId, session_key AS sessionKey, label, agent_id AS agentId, model,
+      cost, tokens, missing, last_activity AS lastActivity
+    FROM agent_cost_sessions WHERE last_activity >= @since${opts.container ? ' AND container = @container' : ''}
+    ORDER BY cost DESC, tokens DESC LIMIT @limit`).all({ since, container: opts.container ?? null, limit: opts.topSessions ?? 20 }) as
+    Omit<SessionCostRow, 'agentName'>[])
+    .map((s) => ({ ...s, agentName: names.get(s.container) ?? null }));
+
+  const unpricedMap = new Map<string, { model: string; calls: number; agents: string[] }>();
+  for (const s of sources) {
+    let parsed: Record<string, number> = {};
+    try { parsed = JSON.parse(s.missing_by_model || '{}'); } catch { /* keep empty */ }
+    for (const [model, calls] of Object.entries(parsed)) {
+      if (!calls) continue;
+      const entry = unpricedMap.get(model) ?? { model, calls: 0, agents: [] };
+      entry.calls += calls;
+      entry.agents.push(s.name ?? s.container);
+      unpricedMap.set(model, entry);
+    }
+  }
+  const unpriced = [...unpricedMap.values()].sort((a, b) => b.calls - a.calls);
+
+  return { totals, daily, byAgent, byModel, sessions, unpriced };
+}
+
+/**
+ * Today's spend (UTC day) and all-time spend, by model today — for the dashboard. Null
+ * when there is nothing to read yet; never throws, so a broken costs.db cannot fail a
+ * page about something else (the reason is in `error`).
+ */
+export function dashboardCosts(): {
+  today: number; allTime: number; missingToday: number;
+  byModelToday: ModelCostRow[]; error?: string;
+} | null {
+  let db: Database.Database | null = null;
+  try {
+    db = openCostsDb();
+    if (!db) return null;
+    const today = utcDate(Date.now());
+    const t = db.prepare(`${TOTALS_SQL} WHERE date = ?`).get(today) as CostTotals;
+    const all = db.prepare(`${TOTALS_SQL}`).get() as CostTotals;
+    const byModelToday = db.prepare(`
+      SELECT provider, model, SUM(cost) AS cost, SUM(tokens) AS tokens, SUM(calls) AS calls
+      FROM agent_cost_model_daily WHERE date = ? GROUP BY provider, model HAVING SUM(tokens) > 0 OR SUM(cost) > 0 ORDER BY cost DESC, tokens DESC`).all(today) as ModelCostRow[];
+    return { today: t.cost, allTime: all.cost, missingToday: t.missing, byModelToday };
+  } catch (e) {
+    return { today: 0, allTime: 0, missingToday: 0, byModelToday: [], error: (e as Error).message };
+  } finally {
+    db?.close();
+  }
+}

package/lib/cost-reconciliation.ts

@@ -0,0 +1,78 @@
+/**
+ * The check against the bill: what each vendor charged, next to what the agents' OpenClaw
+ * priced, over the same interval. daemon.js writes `vendor_balance` rows in costs.db, each
+ * holding the vendor's figure and the agents' cumulative priced total for that vendor's
+ * models, read at the same moment. Between two rows:
+ *
+ * - billed — DeepSeek: the balance drops (a rise is a top-up, counted apart);
+ *   OpenRouter: the growth of its lifetime usage.
+ * - priced — the growth of the agents' total.
+ *
+ * A difference is expected when the same key serves more than the agents (the assistant,
+ * clients outside Rev4a), when a vendor bills late, and from DeepSeek's balance being
+ * given to the cent. Nothing here corrects either side.
+ */
+import type Database from 'better-sqlite3';
+
+export interface Reconciliation {
+  vendor: string;
+  currency: string | null;
+  /** Unix ms of the two readings compared; null when there are not two yet. */
+  from: number | null;
+  to: number | null;
+  billed: number | null;
+  priced: number | null;
+  /** Balance rises between the readings (DeepSeek): money added, not spent. */
+  topUps: number;
+  readings: number;
+  /** False when the vendor's figure is in another currency than the agents' dollars. */
+  comparable: boolean;
+}
+
+interface Row { ts: number; vendor: string; currency: string | null; balance: number | null; usage: number | null; agents_cost: number }
+
+const round = (n: number) => Math.round(n * 1e6) / 1e6;
+
+export function readReconciliation(db: Database.Database, startDate: string, endDate: string): Reconciliation[] {
+  const hasTable = db
+    .prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'vendor_balance'")
+    .get() as { n: number };
+  if (!hasTable.n) return [];
+  const start = Date.parse(`${startDate}T00:00:00Z`);
+  const end = Date.parse(`${endDate}T00:00:00Z`) + 86_400_000;
+  const vendors = (db.prepare('SELECT DISTINCT vendor FROM vendor_balance ORDER BY vendor').all() as { vendor: string }[]).map((v) => v.vendor);
+
+  return vendors.map((vendor) => {
+    // The reading at or just before the start of the range, else the first inside it.
+    const before = db.prepare('SELECT * FROM vendor_balance WHERE vendor = ? AND ts <= ? ORDER BY ts DESC LIMIT 1').get(vendor, start) as Row | undefined;
+    const inside = db.prepare('SELECT * FROM vendor_balance WHERE vendor = ? AND ts > ? AND ts < ? ORDER BY ts').all(vendor, start, end) as Row[];
+    const rows = before ? [before, ...inside] : inside;
+    const currency = rows[rows.length - 1]?.currency ?? null;
+    const empty: Reconciliation = {
+      vendor, currency, from: rows[0]?.ts ?? null, to: null, billed: null, priced: null, topUps: 0,
+      readings: rows.length, comparable: currency === 'USD',
+    };
+    if (rows.length < 2) return empty;
+
+    const a = rows[0];
+    const b = rows[rows.length - 1];
+    let billed = 0;
+    let topUps = 0;
+    if (vendor === 'openrouter') {
+      billed = (b.usage ?? 0) - (a.usage ?? 0);
+    } else {
+      for (let i = 1; i < rows.length; i++) {
+        const delta = (rows[i - 1].balance ?? 0) - (rows[i].balance ?? 0);
+        if (delta >= 0) billed += delta;
+        else topUps += -delta;
+      }
+    }
+    return {
+      ...empty,
+      to: b.ts,
+      billed: round(billed),
+      priced: round(b.agents_cost - a.agents_cost),
+      topUps: round(topUps),
+    };
+  });
+}

package/lib/costs-db.ts

@@ -0,0 +1,31 @@
+// Read access to the agent costs database (daemon.js writes it).
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { DB_PATH } from './db';
+
+/** Next to events.db, as daemon.js places it; its own file, like metrics.db. */
+export const COSTS_DB_PATH = path.join(path.dirname(DB_PATH), 'costs.db');
+
+const TABLES = ['agent_cost_daily', 'agent_cost_model_daily', 'agent_cost_sessions', 'agent_cost_sources'];
+
+/**
+ * Open the costs database read-only, or null when there is nothing to read yet: no file
+ * (first start, or a daemon that never ran) or one without the daemon's tables. The
+ * daemon owns the schema.
+ */
+export function openCostsDb(): Database.Database | null {
+  if (!fs.existsSync(COSTS_DB_PATH)) return null;
+  const db = new Database(COSTS_DB_PATH, { readonly: true, fileMustExist: true });
+  try {
+    const row = db
+      .prepare(`SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN (${TABLES.map(() => '?').join(', ')})`)
+      .get(...TABLES) as { n: number };
+    if (row.n === TABLES.length) return db;
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+  db.close();
+  return null;
+}

package/lib/model-pricing.ts

@@ -1,8 +1,12 @@
 /**
- * Model pricing data — static, from model-pricing.json in the project root.
+ * Model pricing data — static, from model-pricing.json in the project root, in $ per
+ * 1M tokens. `npm run refresh:pricing` regenerates the OpenRouter entries; the direct
+ * vendors' entries are kept by hand from each vendor's own pricing page.
  *
- * OpenRouter models are NOT included here; their pricing is fetched live
- * via the OpenRouter API and merged client-side.
+ * Besides the display, these prices are what every agent's OpenClaw computes its costs
+ * with: `buildRev4aProviderConfig()` writes `priceAt()` into each model of the synced
+ * `rev4a` block, and a vendor with time-of-day pricing (PRICE_SCHEDULES) is re-synced
+ * at each change of rate (lib/price-schedule-sync.ts).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -10,8 +14,48 @@ import * as path from 'path';
 export interface ModelPricing {
   input: number;
   output: number;
+  /** Cached input read. Absent when the vendor's cache rate is not known. */
+  cacheRead?: number;
+  /** Cached input written. Absent when not known or not billed apart from input. */
+  cacheWrite?: number;
 }
 
+/** The four rates OpenClaw's `models.providers.*.models[].cost` takes, $ per 1M tokens. */
+export interface ModelCost {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/**
+ * A vendor whose rates depend on the time of day: `peak` windows at the listed rates,
+ * every other hour at `offPeakFactor` times them. Hours are UTC, `[from, to)`; days are
+ * UTC weekdays, 0 = Sunday.
+ */
+export interface PriceSchedule {
+  source: string;
+  peak: { days: number[]; hours: [number, number][] };
+  offPeakFactor: number;
+}
+
+/**
+ * Keyed by the first segment of our model id: `deepseek/deepseek-flash` is DeepSeek's
+ * own API. `openrouter/deepseek/…` is OpenRouter's price and has no schedule.
+ *
+ * DeepSeek (checked 2026-09-27): "Off-peak rates are half of the peak rates. Peak hours
+ * are 01:00 - 04:00 and 06:00 - 10:00 UTC, Monday through Friday, excluding Chinese
+ * public holidays." Those holidays are not modelled: a call on one is priced at peak, a
+ * small overestimate on a few days a year.
+ */
+export const PRICE_SCHEDULES: Record<string, PriceSchedule> = {
+  deepseek: {
+    source: 'https://api-docs.deepseek.com/quick_start/pricing',
+    peak: { days: [1, 2, 3, 4, 5], hours: [[1, 4], [6, 10]] },
+    offPeakFactor: 0.5,
+  },
+};
+
 let _cache: Record<string, ModelPricing> | null = null;
 let _cacheMtime = 0;
 
@@ -61,3 +105,79 @@ export function formatPricing(p: ModelPricing | null | undefined): string {
   };
   return `${fmt(p.input)} / ${fmt(p.output)}`;
 }
+
+/** The time-of-day schedule a model is billed on, or null for a flat price. */
+export function priceScheduleFor(modelId: string): PriceSchedule | null {
+  return PRICE_SCHEDULES[modelId.split('/')[0]] ?? null;
+}
+
+function isPeak(schedule: PriceSchedule, at: Date): boolean {
+  if (!schedule.peak.days.includes(at.getUTCDay())) return false;
+  const h = at.getUTCHours();
+  return schedule.peak.hours.some(([from, to]) => h >= from && h < to);
+}
+
+/** 'peak' or 'off-peak' for a model on a schedule, null for a flat price. */
+export function priceBandAt(modelId: string, at: Date = new Date()): 'peak' | 'off-peak' | null {
+  const schedule = priceScheduleFor(modelId);
+  if (!schedule) return null;
+  return isPeak(schedule, at) ? 'peak' : 'off-peak';
+}
+
+const round6 = (n: number) => Math.round(n * 1e6) / 1e6;
+
+/**
+ * What a free model is written with. OpenClaw treats an all-zero cost as "no price" and
+ * counts every call as unpriced, which would flag free models as missing a price. One
+ * millionth of a dollar per 1M tokens makes them priced and, in practice, free: a billion
+ * tokens come to $0.001.
+ */
+const FREE_RATE = 0.000001;
+/**
+ * A cache write with no published rate, as a multiple of the input rate. Vendors that
+ * bill cache writes apart charge more than input (Anthropic: 1.25× for its default
+ * five-minute cache); the ones that do not report cache writes at all never use it.
+ */
+const CACHE_WRITE_FALLBACK = 1.25;
+
+/**
+ * The rates in force for a model at a moment, in the shape OpenClaw's config takes.
+ *
+ * Null when there is nothing to write: no entry, or a dynamic router price (-1), whose
+ * calls OpenClaw then counts as unpriced. A free model (all zero) gets FREE_RATE. A cache
+ * rate the file does not carry falls back to a rate that does not undercount: the input
+ * rate for a cache read (as if the cache gave no discount), CACHE_WRITE_FALLBACK × input
+ * for a cache write.
+ */
+export function priceAt(modelId: string, at: Date = new Date()): ModelCost | null {
+  const p = getPricing(modelId);
+  if (!p || p.input < 0 || p.output < 0) return null;
+  if (p.input === 0 && p.output === 0 && !p.cacheRead && !p.cacheWrite) {
+    return { input: FREE_RATE, output: FREE_RATE, cacheRead: FREE_RATE, cacheWrite: FREE_RATE };
+  }
+  const schedule = priceScheduleFor(modelId);
+  const factor = schedule && !isPeak(schedule, at) ? schedule.offPeakFactor : 1;
+  return {
+    input: round6(p.input * factor),
+    output: round6(p.output * factor),
+    cacheRead: round6((p.cacheRead ?? p.input) * factor),
+    cacheWrite: round6((p.cacheWrite ?? p.input * CACHE_WRITE_FALLBACK) * factor),
+  };
+}
+
+/**
+ * The next moment any of these models changes rate, or null when none is on a schedule.
+ * Every schedule changes on the hour, so the search walks hour marks (up to 8 days).
+ */
+export function nextPriceChange(modelIds: string[], from: Date = new Date()): Date | null {
+  const schedules = [...new Set(modelIds.map(priceScheduleFor).filter((s): s is PriceSchedule => s !== null))];
+  if (!schedules.length) return null;
+  const now = schedules.map((s) => isPeak(s, from));
+  const t = new Date(from);
+  t.setUTCMinutes(0, 0, 0);
+  for (let i = 0; i < 8 * 24; i++) {
+    t.setUTCHours(t.getUTCHours() + 1);
+    if (schedules.some((s, j) => isPeak(s, t) !== now[j])) return new Date(t);
+  }
+  return null;
+}