evolclaw 3.1.11 → 3.3.0

package/dist/core/stats/db.js

@@ -0,0 +1,314 @@
+/**
+ * Stats DB — SQLite 初始化、WAL、建表、索引、归档。
+ * 技术选型：node:sqlite (Node 22.5+)，与主包 config-store.ts 保持一致。
+ */
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { logger } from '../../utils/logger.js';
+const requireFromHere = createRequire(import.meta.url);
+let sqliteModule; // undefined=未尝试, null=不可用
+function loadSqlite() {
+    if (sqliteModule !== undefined)
+        return sqliteModule;
+    try {
+        sqliteModule = requireFromHere('node:sqlite');
+    }
+    catch {
+        logger.warn(`[StatsDB] node:sqlite unavailable (Node < 22.5?). Stats disabled.`);
+        sqliteModule = null;
+    }
+    return sqliteModule;
+}
+// 单例：写者（daemon）持有一个 read-write 实例
+let _db = null;
+export function getStatsDir(evolclawHome) {
+    return path.join(evolclawHome, 'data', 'stats');
+}
+export function getDbPath(evolclawHome) {
+    return path.join(getStatsDir(evolclawHome), 'usage.db');
+}
+/** 获取写者单例（daemon 调用）。首次调用时建表。 */
+export function getDb(evolclawHome) {
+    if (_db)
+        return _db;
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return null;
+    const dir = getStatsDir(evolclawHome);
+    fs.mkdirSync(dir, { recursive: true });
+    const dbPath = getDbPath(evolclawHome);
+    try {
+        _db = new sqlite.DatabaseSync(dbPath);
+        _db.exec('PRAGMA journal_mode=WAL');
+        _db.exec('PRAGMA synchronous=NORMAL');
+        _initTables(_db);
+        logger.info(`[StatsDB] Opened: ${dbPath}`);
+        return _db;
+    }
+    catch (e) {
+        logger.error(`[StatsDB] Failed to open DB: ${e}`);
+        return null;
+    }
+}
+/** 只读连接（CLI / ecweb 调用）。每次返回新连接，调用方负责 close()。 */
+export function openReadonlyDb(dbPath) {
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return null;
+    if (!fs.existsSync(dbPath))
+        return null;
+    try {
+        return new sqlite.DatabaseSync(dbPath, { readOnly: true });
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] Failed to open readonly DB ${dbPath}: ${e}`);
+        return null;
+    }
+}
+function _initTables(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts                    INTEGER NOT NULL,
+      agent_aid             TEXT    NOT NULL,
+      peer_key              TEXT    NOT NULL,
+      peer_type             TEXT,
+      session_id            TEXT,
+      model                 TEXT    NOT NULL,
+      billing_fn            TEXT    NOT NULL,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      cache_hit_tokens      INTEGER,
+      cache_miss_tokens     INTEGER,
+      image_tokens          INTEGER,
+      total_context_tokens  INTEGER,
+      turns                 INTEGER NOT NULL DEFAULT 1,
+      duration_ms           INTEGER,
+      context_window_pct    REAL
+    );
+    CREATE INDEX IF NOT EXISTS idx_ue_ts         ON usage_events(ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_agent_ts   ON usage_events(agent_aid, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_peer_ts    ON usage_events(agent_aid, peer_key, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_model_ts   ON usage_events(model, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_session_ts ON usage_events(session_id, ts);
+
+    CREATE TABLE IF NOT EXISTS context_breakdown (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts              INTEGER NOT NULL,
+      agent_aid       TEXT    NOT NULL,
+      session_id      TEXT    NOT NULL,
+      turn_count      INTEGER NOT NULL,
+      model           TEXT    NOT NULL,
+      max_tokens      INTEGER NOT NULL,
+      system_prompt   INTEGER,
+      system_tools    INTEGER,
+      mcp_tools       INTEGER,
+      custom_agents   INTEGER,
+      memory_files    INTEGER,
+      skills          INTEGER,
+      messages        INTEGER,
+      free_space      INTEGER,
+      total_estimated INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_cb_session ON context_breakdown(session_id, ts);
+    CREATE INDEX IF NOT EXISTS idx_cb_agent   ON context_breakdown(agent_aid, ts);
+
+    CREATE TABLE IF NOT EXISTS message_events (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts          INTEGER NOT NULL,
+      agent_aid   TEXT    NOT NULL,
+      peer_key    TEXT    NOT NULL,
+      direction   TEXT    NOT NULL,
+      msg_type    TEXT,
+      bytes       INTEGER NOT NULL DEFAULT 0,
+      encrypted   INTEGER DEFAULT 0,
+      chatmode    TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_me_ts       ON message_events(ts);
+    CREATE INDEX IF NOT EXISTS idx_me_agent_ts ON message_events(agent_aid, ts);
+    CREATE INDEX IF NOT EXISTS idx_me_peer_ts  ON message_events(agent_aid, peer_key, ts);
+
+    -- 按天预聚合表：grain = 天 × agent × peer × session × model × billing_fn。
+    -- 由 writer.ts 写时增量 UPSERT 维护，rebuildDailyRollup() 全量重建纠偏。
+    -- 保留 model+billing_fn 维度以便查询时仍按 calcCost 现算成本。
+    -- 日级行很小，永留主库、不参与年度归档。
+    CREATE TABLE IF NOT EXISTS usage_daily (
+      day          TEXT NOT NULL,           -- 'YYYY-MM-DD' localtime
+      agent_aid    TEXT NOT NULL,
+      peer_key     TEXT NOT NULL,
+      peer_type    TEXT NOT NULL DEFAULT '',-- 'private' | 'group'，由 peer_key 唯一决定
+      session_id   TEXT NOT NULL DEFAULT '',
+      model        TEXT NOT NULL,
+      billing_fn   TEXT NOT NULL,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      cache_hit_tokens      INTEGER NOT NULL DEFAULT 0,
+      cache_miss_tokens     INTEGER NOT NULL DEFAULT 0,
+      image_tokens          INTEGER NOT NULL DEFAULT 0,
+      total_context_tokens  INTEGER NOT NULL DEFAULT 0,
+      turns        INTEGER NOT NULL DEFAULT 0,
+      calls        INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (day, agent_aid, peer_key, session_id, model, billing_fn)
+    );
+    CREATE INDEX IF NOT EXISTS idx_ud_day     ON usage_daily(day);
+    CREATE INDEX IF NOT EXISTS idx_ud_session ON usage_daily(session_id);
+
+    -- 大模型调用明细：每次大模型调用一行（尽力而为；非 Claude 拿不到逐次时降级为单行累计）。
+    -- 关联三个 ID：task_id（一次 runQuery）、session_id（evolclaw 会话）、agent_session_id（SDK 会话）。
+    CREATE TABLE IF NOT EXISTS model_calls (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts            INTEGER NOT NULL,
+      task_id       TEXT    NOT NULL,
+      session_id    TEXT,
+      agent_session_id TEXT,
+      agent_aid     TEXT    NOT NULL,
+      peer_key      TEXT    NOT NULL,
+      call_index    INTEGER NOT NULL,
+      model         TEXT    NOT NULL,
+      request_id    TEXT,
+      message_id    TEXT,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      degraded      INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_mc_task        ON model_calls(task_id);
+    CREATE INDEX IF NOT EXISTS idx_mc_session     ON model_calls(session_id, ts);
+    CREATE INDEX IF NOT EXISTS idx_mc_agentsession ON model_calls(agent_session_id);
+    CREATE INDEX IF NOT EXISTS idx_mc_ts          ON model_calls(ts);
+  `);
+    // 轻量迁移：旧库的 usage_daily 可能缺 peer_type 列（无 migration 机制，CREATE IF NOT EXISTS
+    // 不会补列）。检测后 ALTER 补上；补列后旧行 peer_type 为空，需跑一次 rebuildDailyRollup 回填。
+    try {
+        const cols = db.prepare(`PRAGMA table_info(usage_daily)`).all();
+        if (!cols.some(c => c.name === 'peer_type')) {
+            db.exec(`ALTER TABLE usage_daily ADD COLUMN peer_type TEXT NOT NULL DEFAULT ''`);
+        }
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] usage_daily peer_type 迁移检测失败: ${e}`);
+    }
+}
+/**
+ * 全量重建 usage_daily：从 usage_events 明细按天聚合重算。
+ * 用途：首次回填历史数据、每日自愈纠正写时漂移、手动 `ec stats --rebuild`。
+ * 单事务内 DELETE + INSERT...SELECT，失败回滚不破坏现有 rollup。
+ * 仅扫主库明细（往年明细已归档，但其 rollup 行已在归档前写入并永留主库）。
+ * @returns 重建后的行数，DB 不可用时返回 -1。
+ */
+export function rebuildDailyRollup(evolclawHome) {
+    const db = getDb(evolclawHome);
+    if (!db)
+        return -1;
+    try {
+        db.exec('BEGIN');
+        db.exec('DELETE FROM usage_daily');
+        db.exec(`
+      INSERT INTO usage_daily
+        (day, agent_aid, peer_key, peer_type, session_id, model, billing_fn,
+         input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens,
+         cache_hit_tokens, cache_miss_tokens, image_tokens, total_context_tokens,
+         turns, calls)
+      SELECT
+        strftime('%Y-%m-%d', ts/1000, 'unixepoch', 'localtime') AS day,
+        agent_aid, peer_key, MAX(COALESCE(peer_type, '')),
+        COALESCE(session_id, ''), model, billing_fn,
+        SUM(input_tokens), SUM(output_tokens),
+        SUM(cache_creation_tokens), SUM(cache_read_tokens),
+        SUM(COALESCE(cache_hit_tokens, 0)), SUM(COALESCE(cache_miss_tokens, 0)),
+        SUM(COALESCE(image_tokens, 0)), SUM(COALESCE(total_context_tokens, 0)),
+        SUM(turns), COUNT(*)
+      FROM usage_events
+      GROUP BY day, agent_aid, peer_key, COALESCE(session_id, ''), model, billing_fn
+    `);
+        db.exec('COMMIT');
+        const row = db.prepare('SELECT COUNT(*) AS n FROM usage_daily').get();
+        logger.info(`[StatsDB] Rebuilt usage_daily: ${row.n} rows`);
+        return row.n;
+    }
+    catch (e) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { }
+        logger.error(`[StatsDB] rebuildDailyRollup failed: ${e}`);
+        return -1;
+    }
+}
+// ── 归档 ────────────────────────────────────────────────────────────────────
+/**
+ * 归档超过一整个自然年的数据到 usage-{year}.db，然后从主库删除。
+ * 例：当前 2026-05 → 归档所有 ts < 2025-01-01 00:00:00 的数据（即 2024 年及更早）。
+ * 安全：归档失败不删除主库数据。
+ */
+export function archiveOldData(evolclawHome) {
+    const db = getDb(evolclawHome);
+    if (!db)
+        return;
+    const now = new Date();
+    // 归档截止：当前年份第一天 00:00:00
+    const cutoffYear = now.getFullYear(); // e.g. 2026
+    const cutoffTs = Date.UTC(cutoffYear, 0, 1); // 2026-01-01 00:00:00 UTC
+    // 找出主库中所有早于 cutoff 的年份
+    const years = db.prepare(`SELECT DISTINCT CAST(strftime('%Y', ts/1000, 'unixepoch') AS INTEGER) AS y
+     FROM usage_events WHERE ts < ? ORDER BY y`).all(cutoffTs).map((r) => r.y);
+    if (years.length === 0)
+        return;
+    const statsDir = getStatsDir(evolclawHome);
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return;
+    for (const year of years) {
+        const archivePath = path.join(statsDir, `usage-${year}.db`);
+        const yearStart = Date.UTC(year, 0, 1);
+        const yearEnd = Date.UTC(year + 1, 0, 1);
+        try {
+            // 打开/创建归档库，建同结构表
+            const archDb = new sqlite.DatabaseSync(archivePath);
+            archDb.exec('PRAGMA journal_mode=WAL');
+            _initTables(archDb);
+            archDb.close();
+            // ATTACH 方式批量迁移（同进程内最简洁）
+            db.exec(`ATTACH DATABASE '${archivePath.replace(/'/g, "''")}' AS arch`);
+            db.exec('BEGIN');
+            db.exec(`INSERT OR IGNORE INTO arch.usage_events SELECT * FROM main.usage_events WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`INSERT OR IGNORE INTO arch.context_breakdown SELECT * FROM main.context_breakdown WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`DELETE FROM main.usage_events WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`DELETE FROM main.context_breakdown WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec('COMMIT');
+            db.exec('DETACH DATABASE arch');
+            logger.info(`[StatsDB] Archived year ${year} → ${archivePath}`);
+        }
+        catch (e) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            try {
+                db.exec('DETACH DATABASE arch');
+            }
+            catch { }
+            logger.error(`[StatsDB] Archive failed for year ${year}: ${e}`);
+        }
+    }
+    // VACUUM 回收空间（WAL 模式下安全）
+    try {
+        db.exec('VACUUM');
+    }
+    catch { }
+}
+/** 列出所有可用的归档库路径（按年份排序）。 */
+export function listArchivePaths(evolclawHome) {
+    const dir = getStatsDir(evolclawHome);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .map(f => { const m = f.match(/^usage-(\d{4})\.db$/); return m ? { year: +m[1], path: path.join(dir, f) } : null; })
+        .filter(Boolean);
+}

package/dist/core/stats/eck-vars.js

@@ -0,0 +1,84 @@
+/**
+ * eck-vars.ts — 组装 $STATS_* ECK 注入变量。
+ *
+ * 分层原则（保护 prompt cache）：
+ *   - system prompt 层：今日累计、预算状态（变化慢，稳定可缓存）
+ *   - 消息提示词层：会话级动态数据（每轮变，不注入 system）
+ */
+import { openReadonlyDb, getDbPath } from './db.js';
+import { calcCost } from './billing.js';
+import { getBudgetStatus } from './budget.js';
+function _todayRange() {
+    const now = new Date();
+    return { from_ts: Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()) };
+}
+function _calcTodayCosts(evolclawHome, agentAid, peerKey) {
+    const db = openReadonlyDb(getDbPath(evolclawHome));
+    if (!db)
+        return { usd: 0, cny: 0, input: 0, output: 0, cacheRead: 0, calls: 0 };
+    const { from_ts } = _todayRange();
+    const conds = ['ts >= ?'];
+    const params = [from_ts];
+    if (agentAid) {
+        conds.push('agent_aid = ?');
+        params.push(agentAid);
+    }
+    if (peerKey) {
+        conds.push('peer_key = ?');
+        params.push(peerKey);
+    }
+    let usd = 0, cny = 0, input = 0, output = 0, cacheRead = 0, calls = 0;
+    try {
+        const rows = db.prepare(`SELECT * FROM usage_events WHERE ${conds.join(' AND ')}`).all(...params);
+        for (const r of rows) {
+            const cost = calcCost(evolclawHome, r);
+            usd += cost.usd ?? 0;
+            cny += cost.cny ?? 0;
+            input += r.input_tokens ?? 0;
+            output += r.output_tokens ?? 0;
+            cacheRead += r.cache_read_tokens ?? 0;
+            calls++;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return { usd, cny, input, output, cacheRead, calls };
+}
+/** 注入 system prompt 的变量（变化慢，可缓存）。 */
+export function buildSystemVars(evolclawHome, agentAid, peerKey) {
+    const agent = _calcTodayCosts(evolclawHome, agentAid);
+    const peer = peerKey ? _calcTodayCosts(evolclawHome, agentAid, peerKey) : { usd: 0, cny: 0 };
+    const totalIn = agent.input + agent.cacheRead;
+    const hitRate = totalIn > 0 ? ((agent.cacheRead / totalIn) * 100).toFixed(1) + '%' : '0%';
+    const budget = getBudgetStatus(evolclawHome, agentAid, peerKey);
+    return {
+        STATS_TODAY_INPUT_TOKENS: String(agent.input),
+        STATS_TODAY_OUTPUT_TOKENS: String(agent.output),
+        STATS_TODAY_CACHE_READ_TOKENS: String(agent.cacheRead),
+        STATS_TODAY_CACHE_HIT_RATE: hitRate,
+        STATS_TODAY_COST_USD: agent.usd.toFixed(4),
+        STATS_TODAY_COST_CNY: agent.cny.toFixed(4),
+        STATS_TODAY_CALL_COUNT: String(agent.calls),
+        STATS_PEER_TODAY_COST_USD: peer.usd?.toFixed(4) ?? '0',
+        STATS_PEER_TODAY_COST_CNY: peer.cny?.toFixed(4) ?? '0',
+        STATS_BUDGET_DAILY_LIMIT_USD: budget.daily_limit_usd >= 0 ? budget.daily_limit_usd.toFixed(2) : 'unlimited',
+        STATS_BUDGET_DAILY_USED_USD: budget.daily_used_usd.toFixed(4),
+        STATS_BUDGET_DAILY_REMAINING_USD: budget.daily_remaining_usd >= 0 ? budget.daily_remaining_usd.toFixed(2) : 'unlimited',
+        STATS_BUDGET_PCT_USED: budget.pct_used.toFixed(1),
+        STATS_BUDGET_WARN: String(budget.soft_warn),
+    };
+}
+/** 注入消息提示词的变量（每轮变，不进 system prompt）。 */
+export function buildTurnVars(opts) {
+    return {
+        SESSION_TURN_COUNT: String(opts.sessionTurnCount),
+        SESSION_LLM_CALL_COUNT: String(opts.sessionLlmCallCount),
+        STATS_CTX_TOTAL_TOKENS: String(opts.ctxTotalTokens ?? 0),
+        STATS_CTX_PCT: opts.ctxPct != null ? opts.ctxPct.toFixed(1) : '0',
+        STATS_CTX_SYSTEM_TOKENS: String(opts.ctxSystemTokens ?? 0),
+        STATS_CTX_MESSAGES_TOKENS: String(opts.ctxMessagesTokens ?? 0),
+        STATS_CTX_TOOLS_TOKENS: String(opts.ctxToolsTokens ?? 0),
+        STATS_BUDGET_AUTO_WARN: String(opts.autoBudgetWarn),
+    };
+}

package/dist/core/stats/index.js

@@ -0,0 +1,10 @@
+/**
+ * src/core/stats/index.ts — Stats 模块公开 API。
+ */
+export { getDb, openReadonlyDb, getStatsDir, getDbPath, archiveOldData, listArchivePaths, rebuildDailyRollup } from './db.js';
+export { normalizeUsage } from './normalizer.js';
+export { insertUsageEvent, insertContextBreakdown, insertMessageEvent, insertModelCalls } from './writer.js';
+export { calcCost, resolvePriceRow, resolveCanonicalModel, registerBillingFn } from './billing.js';
+export { queryAggregated, queryTodaySummary, querySessionTurns, queryContextBreakdown, queryTopPeers, queryTopModels, queryMessageAggregated, queryMessageTodaySummary, queryPeerList, querySummary, queryPeerDaily, queryTaskModelCalls, querySessionModelCalls } from './query.js';
+export { getBudgetStatus } from './budget.js';
+export { buildSystemVars, buildTurnVars } from './eck-vars.js';

package/dist/core/stats/normalizer.js

@@ -0,0 +1,78 @@
+/**
+ * normalizer.ts — 各模型 raw usage 字段 → 归一化 UsageEvent，同时推断 billing_fn。
+ * 按实际有什么字段智能探测，不假设接入方式。
+ */
+export function normalizeUsage(raw, meta) {
+    let billing_fn;
+    let input_tokens = 0;
+    let output_tokens = 0;
+    let cache_creation_tokens = 0;
+    let cache_read_tokens = 0;
+    let cache_hit_tokens;
+    let cache_miss_tokens;
+    let image_tokens;
+    let total_context_tokens;
+    if (raw.cache_hit_tokens != null || raw.cache_miss_tokens != null) {
+        // DeepSeek 口径
+        billing_fn = 'per_token_deepseek_v1';
+        output_tokens = raw.output_tokens ?? raw.completion_tokens ?? 0;
+        cache_hit_tokens = raw.cache_hit_tokens ?? 0;
+        cache_miss_tokens = raw.cache_miss_tokens ?? 0;
+        input_tokens = cache_miss_tokens; // 未命中部分才算 input（计费口径）
+        // 实际上下文长度 = 命中 + 未命中（total KV cache input）
+        total_context_tokens = cache_hit_tokens + cache_miss_tokens;
+    }
+    else if (raw.promptTokenCount != null || raw.candidatesTokenCount != null) {
+        // Gemini 原生
+        billing_fn = 'per_token_tiered_v1';
+        input_tokens = raw.promptTokenCount ?? 0;
+        output_tokens = raw.candidatesTokenCount ?? 0;
+        cache_read_tokens = raw.cachedContentTokenCount ?? 0;
+        total_context_tokens = raw.totalTokenCount ?? (input_tokens + output_tokens);
+    }
+    else if (raw.image_tokens != null) {
+        // 视觉模型（Qwen-VL 等）
+        billing_fn = 'per_token_image_v1';
+        input_tokens = raw.input_tokens ?? raw.prompt_tokens ?? 0;
+        output_tokens = raw.output_tokens ?? raw.completion_tokens ?? 0;
+        image_tokens = raw.image_tokens;
+    }
+    else if (raw.cache_creation_input_tokens != null || raw.cache_read_input_tokens != null) {
+        // Anthropic / Claude 原生
+        billing_fn = 'per_token_v1';
+        input_tokens = raw.input_tokens ?? 0;
+        output_tokens = raw.output_tokens ?? 0;
+        cache_creation_tokens = raw.cache_creation_input_tokens ?? 0;
+        cache_read_tokens = raw.cache_read_input_tokens ?? 0;
+    }
+    else {
+        // OpenAI 兼容降级（Kimi / MiniMax / 截断网关等）
+        billing_fn = 'per_token_v1';
+        input_tokens = raw.input_tokens ?? raw.prompt_tokens ?? 0;
+        output_tokens = raw.output_tokens ?? raw.completion_tokens ?? 0;
+        cache_read_tokens = raw.prompt_tokens_details?.cached_tokens ?? 0;
+    }
+    if (total_context_tokens == null) {
+        total_context_tokens = input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens || undefined;
+    }
+    return {
+        ts: meta.ts,
+        agent_aid: meta.agent_aid,
+        peer_key: meta.peer_key,
+        peer_type: meta.peer_type,
+        session_id: meta.session_id,
+        model: meta.model,
+        billing_fn,
+        input_tokens,
+        output_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+        cache_hit_tokens,
+        cache_miss_tokens,
+        image_tokens,
+        total_context_tokens,
+        turns: meta.turns ?? 1,
+        duration_ms: meta.duration_ms,
+        context_window_pct: meta.context_window_pct,
+    };
+}