@praeviso/code-env-switch 0.1.5 → 0.1.7

package/bin/usage/index.js

@@ -16,6 +16,7 @@ exports.syncUsageFromStatuslineInput = syncUsageFromStatuslineInput;
 exports.logProfileUse = logProfileUse;
 exports.logSessionBinding = logSessionBinding;
 exports.readSessionBindingIndex = readSessionBindingIndex;
+exports.clearUsageHistory = clearUsageHistory;
 exports.readUsageRecords = readUsageRecords;
 exports.syncUsageFromSessions = syncUsageFromSessions;
 /**
@@ -26,6 +27,7 @@ const path = require("path");
 const os = require("os");
 const utils_1 = require("../shell/utils");
 const type_1 = require("../profile/type");
+const debug_1 = require("../statusline/debug");
 const pricing_1 = require("./pricing");
 function resolveProfileForRecord(config, type, record) {
     if (record.profileKey && config.profiles && config.profiles[record.profileKey]) {
@@ -393,17 +395,32 @@ function syncUsageFromStatuslineInput(config, configPath, type, profileKey, prof
         let deltaCacheRead = cacheReadTokens - prevCacheRead;
         let deltaCacheWrite = cacheWriteTokens - prevCacheWrite;
         let deltaTotal = totalTokens - prevTotal;
-        if (deltaTotal < 0 ||
-            deltaInput < 0 ||
-            deltaOutput < 0 ||
-            deltaCacheRead < 0 ||
-            deltaCacheWrite < 0) {
+        if (deltaTotal < 0) {
+            // Session reset: treat current totals as fresh usage.
             deltaInput = inputTokens;
             deltaOutput = outputTokens;
             deltaCacheRead = cacheReadTokens;
             deltaCacheWrite = cacheWriteTokens;
             deltaTotal = totalTokens;
         }
+        else {
+            // Clamp negatives caused by reclassification (e.g. cache splits).
+            if (deltaInput < 0)
+                deltaInput = 0;
+            if (deltaOutput < 0)
+                deltaOutput = 0;
+            if (deltaCacheRead < 0)
+                deltaCacheRead = 0;
+            if (deltaCacheWrite < 0)
+                deltaCacheWrite = 0;
+            const breakdownTotal = deltaInput + deltaOutput + deltaCacheRead + deltaCacheWrite;
+            if (deltaTotal === 0 && breakdownTotal === 0) {
+                deltaTotal = 0;
+            }
+            else if (breakdownTotal > deltaTotal) {
+                deltaTotal = breakdownTotal;
+            }
+        }
         if (deltaTotal > 0) {
             const record = {
                 ts: new Date().toISOString(),
@@ -432,8 +449,11 @@ function syncUsageFromStatuslineInput(config, configPath, type, profileKey, prof
             endTs: now,
             cwd: cwd || (prev ? prev.cwd : null),
             model: resolvedModel,
+            profileKey: profileKey || null,
+            profileName: profileName || null,
         };
         state.sessions = sessions;
+        updateUsageStateMetadata(state, usagePath);
         writeUsageState(statePath, state);
     }
     finally {
@@ -588,7 +608,15 @@ function readUsageState(statePath) {
         }
         const files = parsed.files && typeof parsed.files === "object" ? parsed.files : {};
         const sessions = parsed.sessions && typeof parsed.sessions === "object" ? parsed.sessions : {};
-        return { version: 1, files, sessions };
+        const usageMtimeMs = Number(parsed.usageMtimeMs);
+        const usageSize = Number(parsed.usageSize);
+        return {
+            version: 1,
+            files,
+            sessions,
+            usageMtimeMs: Number.isFinite(usageMtimeMs) ? usageMtimeMs : undefined,
+            usageSize: Number.isFinite(usageSize) ? usageSize : undefined,
+        };
     }
     catch {
         return { version: 1, files: {}, sessions: {} };
@@ -599,7 +627,93 @@ function writeUsageState(statePath, state) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    const payload = `${JSON.stringify(state, null, 2)}\n`;
+    const tmpPath = `${statePath}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, payload, "utf8");
+        fs.renameSync(tmpPath, statePath);
+    }
+    catch {
+        try {
+            if (fs.existsSync(tmpPath))
+                fs.unlinkSync(tmpPath);
+        }
+        catch {
+            // ignore cleanup failures
+        }
+        fs.writeFileSync(statePath, payload, "utf8");
+    }
+}
+function addSiblingBackupPaths(targets, filePath) {
+    if (!filePath)
+        return;
+    const dir = path.dirname(filePath);
+    let entries = [];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const base = path.basename(filePath);
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (entry.name === base)
+            continue;
+        if (entry.name.startsWith(`${base}.`)) {
+            targets.add(path.join(dir, entry.name));
+        }
+    }
+}
+function clearUsageHistory(config, configPath) {
+    const targets = new Set();
+    const usagePath = getUsagePath(config, configPath);
+    if (usagePath) {
+        targets.add(usagePath);
+        addSiblingBackupPaths(targets, usagePath);
+    }
+    const statePath = usagePath ? getUsageStatePath(usagePath, config) : null;
+    if (statePath) {
+        targets.add(statePath);
+        targets.add(`${statePath}.lock`);
+        addSiblingBackupPaths(targets, statePath);
+    }
+    const profileLogPath = getProfileLogPath(config, configPath);
+    if (profileLogPath) {
+        targets.add(profileLogPath);
+        addSiblingBackupPaths(targets, profileLogPath);
+    }
+    const debugPath = (0, debug_1.getStatuslineDebugPath)(configPath);
+    if (debugPath) {
+        targets.add(debugPath);
+        addSiblingBackupPaths(targets, debugPath);
+    }
+    const removed = [];
+    const missing = [];
+    const failed = [];
+    for (const target of targets) {
+        if (!target)
+            continue;
+        if (!fs.existsSync(target)) {
+            missing.push(target);
+            continue;
+        }
+        try {
+            const stat = fs.statSync(target);
+            if (!stat.isFile())
+                continue;
+            fs.unlinkSync(target);
+            removed.push(target);
+        }
+        catch (err) {
+            failed.push({
+                path: target,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { removed, missing, failed };
 }
 function collectSessionFiles(root) {
     if (!root || !fs.existsSync(root))
@@ -708,10 +822,12 @@ function parseCodexSessionFile(filePath) {
     let maxTotal = 0;
     let maxInput = 0;
     let maxOutput = 0;
+    let maxCachedInput = 0;
     let hasTotal = false;
     let sumLast = 0;
     let sumLastInput = 0;
     let sumLastOutput = 0;
+    let sumLastCachedInput = 0;
     const tsRange = { start: null, end: null };
     let cwd = null;
     let sessionId = null;
@@ -759,12 +875,16 @@ function parseCodexSessionFile(filePath) {
                     maxTotal = totalTokens;
                 const totalInput = Number(totalUsage.input_tokens);
                 const totalOutput = Number(totalUsage.output_tokens);
+                const totalCached = Number(totalUsage.cached_input_tokens);
                 if (Number.isFinite(totalInput) && totalInput > maxInput) {
                     maxInput = totalInput;
                 }
                 if (Number.isFinite(totalOutput) && totalOutput > maxOutput) {
                     maxOutput = totalOutput;
                 }
+                if (Number.isFinite(totalCached) && totalCached > maxCachedInput) {
+                    maxCachedInput = totalCached;
+                }
             }
             else {
                 const lastTokens = Number(lastUsage.total_tokens);
@@ -772,10 +892,13 @@ function parseCodexSessionFile(filePath) {
                     sumLast += lastTokens;
                 const lastInput = Number(lastUsage.input_tokens);
                 const lastOutput = Number(lastUsage.output_tokens);
+                const lastCached = Number(lastUsage.cached_input_tokens);
                 if (Number.isFinite(lastInput))
                     sumLastInput += lastInput;
                 if (Number.isFinite(lastOutput))
                     sumLastOutput += lastOutput;
+                if (Number.isFinite(lastCached))
+                    sumLastCachedInput += lastCached;
             }
         }
         catch {
@@ -786,13 +909,18 @@ function parseCodexSessionFile(filePath) {
         maxTotal = sumLast;
         maxInput = sumLastInput;
         maxOutput = sumLastOutput;
+        maxCachedInput = sumLastCachedInput;
     }
+    const cacheReadTokens = Math.max(0, maxCachedInput);
+    const inputTokens = cacheReadTokens > 0 ? Math.max(0, maxInput - cacheReadTokens) : maxInput;
+    const computedTotal = inputTokens + maxOutput + cacheReadTokens;
+    const totalTokens = Math.max(maxTotal, computedTotal);
     return {
-        inputTokens: maxInput,
+        inputTokens,
         outputTokens: maxOutput,
-        cacheReadTokens: 0,
+        cacheReadTokens,
         cacheWriteTokens: 0,
-        totalTokens: maxTotal,
+        totalTokens,
         startTs: tsRange.start,
         endTs: tsRange.end,
         cwd,
@@ -955,6 +1083,92 @@ function releaseLock(lockPath, fd) {
         // ignore
     }
 }
+function readUsageFileStat(usagePath) {
+    if (!usagePath || !fs.existsSync(usagePath))
+        return null;
+    try {
+        return fs.statSync(usagePath);
+    }
+    catch {
+        return null;
+    }
+}
+function buildUsageRecordKey(record) {
+    var _a, _b, _c, _d;
+    return JSON.stringify([
+        record.ts,
+        record.type,
+        (_a = record.profileKey) !== null && _a !== void 0 ? _a : null,
+        (_b = record.profileName) !== null && _b !== void 0 ? _b : null,
+        (_c = record.model) !== null && _c !== void 0 ? _c : null,
+        (_d = record.sessionId) !== null && _d !== void 0 ? _d : null,
+        toUsageNumber(record.inputTokens),
+        toUsageNumber(record.outputTokens),
+        toUsageNumber(record.cacheReadTokens),
+        toUsageNumber(record.cacheWriteTokens),
+        toUsageNumber(record.totalTokens),
+    ]);
+}
+function buildUsageSessionsFromRecords(records) {
+    const sessions = {};
+    const seen = new Set();
+    for (const record of records) {
+        if (!record.sessionId)
+            continue;
+        const normalizedType = normalizeUsageType(record.type);
+        if (!normalizedType)
+            continue;
+        const recordKey = buildUsageRecordKey(record);
+        if (seen.has(recordKey))
+            continue;
+        seen.add(recordKey);
+        const sessionKey = buildSessionKey(normalizedType, record.sessionId);
+        let entry = sessions[sessionKey];
+        if (!entry) {
+            entry = {
+                type: normalizedType,
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheWriteTokens: 0,
+                totalTokens: 0,
+                startTs: null,
+                endTs: null,
+                cwd: null,
+                model: record.model || null,
+            };
+            sessions[sessionKey] = entry;
+        }
+        entry.inputTokens += toUsageNumber(record.inputTokens);
+        entry.outputTokens += toUsageNumber(record.outputTokens);
+        entry.cacheReadTokens += toUsageNumber(record.cacheReadTokens);
+        entry.cacheWriteTokens += toUsageNumber(record.cacheWriteTokens);
+        entry.totalTokens += toUsageNumber(record.totalTokens);
+        if (record.profileKey)
+            entry.profileKey = record.profileKey;
+        if (record.profileName)
+            entry.profileName = record.profileName;
+        if (!entry.model && record.model)
+            entry.model = record.model;
+        if (record.ts) {
+            const range = { start: entry.startTs, end: entry.endTs };
+            updateMinMaxTs(range, record.ts);
+            entry.startTs = range.start;
+            entry.endTs = range.end;
+        }
+    }
+    return sessions;
+}
+function updateUsageStateMetadata(state, usagePath) {
+    const stat = readUsageFileStat(usagePath);
+    if (!stat || !stat.isFile()) {
+        state.usageMtimeMs = undefined;
+        state.usageSize = undefined;
+        return;
+    }
+    state.usageMtimeMs = stat.mtimeMs;
+    state.usageSize = stat.size;
+}
 function appendUsageRecord(usagePath, record) {
     const dir = path.dirname(usagePath);
     if (!fs.existsSync(dir)) {
@@ -969,6 +1183,7 @@ function readUsageRecords(usagePath) {
     const raw = fs.readFileSync(usagePath, "utf8");
     const lines = raw.split(/\r?\n/);
     const records = [];
+    const seen = new Set();
     for (const line of lines) {
         const trimmed = line.trim();
         if (!trimmed)
@@ -977,19 +1192,29 @@ function readUsageRecords(usagePath) {
             const parsed = JSON.parse(trimmed);
             if (!parsed || typeof parsed !== "object")
                 continue;
-            const input = Number((_a = parsed.inputTokens) !== null && _a !== void 0 ? _a : 0);
-            const output = Number((_b = parsed.outputTokens) !== null && _b !== void 0 ? _b : 0);
-            const cacheRead = Number((_e = (_d = (_c = parsed.cacheReadTokens) !== null && _c !== void 0 ? _c : parsed.cache_read_input_tokens) !== null && _d !== void 0 ? _d : parsed.cacheReadInputTokens) !== null && _e !== void 0 ? _e : 0);
-            const cacheWrite = Number((_j = (_h = (_g = (_f = parsed.cacheWriteTokens) !== null && _f !== void 0 ? _f : parsed.cache_creation_input_tokens) !== null && _g !== void 0 ? _g : parsed.cache_write_input_tokens) !== null && _h !== void 0 ? _h : parsed.cacheWriteInputTokens) !== null && _j !== void 0 ? _j : 0);
+            const type = (0, type_1.normalizeType)(parsed.type) || String((_a = parsed.type) !== null && _a !== void 0 ? _a : "unknown");
+            let input = Number((_b = parsed.inputTokens) !== null && _b !== void 0 ? _b : 0);
+            const output = Number((_c = parsed.outputTokens) !== null && _c !== void 0 ? _c : 0);
+            const cacheRead = Number((_f = (_e = (_d = parsed.cacheReadTokens) !== null && _d !== void 0 ? _d : parsed.cache_read_input_tokens) !== null && _e !== void 0 ? _e : parsed.cacheReadInputTokens) !== null && _f !== void 0 ? _f : 0);
+            const cacheWrite = Number((_k = (_j = (_h = (_g = parsed.cacheWriteTokens) !== null && _g !== void 0 ? _g : parsed.cache_creation_input_tokens) !== null && _h !== void 0 ? _h : parsed.cache_write_input_tokens) !== null && _j !== void 0 ? _j : parsed.cacheWriteInputTokens) !== null && _k !== void 0 ? _k : 0);
+            if (type === "codex" &&
+                Number.isFinite(cacheRead) &&
+                cacheRead > 0 &&
+                Number.isFinite(input) &&
+                Number.isFinite(output)) {
+                const rawTotal = Number(parsed.totalTokens);
+                if (Number.isFinite(rawTotal) && rawTotal <= input + output) {
+                    input = Math.max(0, input - cacheRead);
+                }
+            }
             const computedTotal = (Number.isFinite(input) ? input : 0) +
                 (Number.isFinite(output) ? output : 0) +
                 (Number.isFinite(cacheRead) ? cacheRead : 0) +
                 (Number.isFinite(cacheWrite) ? cacheWrite : 0);
-            const total = Number((_k = parsed.totalTokens) !== null && _k !== void 0 ? _k : computedTotal);
+            const total = Number((_l = parsed.totalTokens) !== null && _l !== void 0 ? _l : computedTotal);
             const finalTotal = Number.isFinite(total)
                 ? Math.max(total, computedTotal)
                 : computedTotal;
-            const type = (0, type_1.normalizeType)(parsed.type) || String((_l = parsed.type) !== null && _l !== void 0 ? _l : "unknown");
             const model = normalizeModelValue(parsed.model) ||
                 normalizeModelValue(parsed.model_name) ||
                 normalizeModelValue(parsed.modelName) ||
@@ -1001,7 +1226,7 @@ function readUsageRecords(usagePath) {
                 parsed.sessionID ||
                 parsed.session ||
                 null;
-            records.push({
+            const record = {
                 ts: String((_m = parsed.ts) !== null && _m !== void 0 ? _m : ""),
                 type,
                 profileKey: parsed.profileKey ? String(parsed.profileKey) : null,
@@ -1013,7 +1238,12 @@ function readUsageRecords(usagePath) {
                 cacheReadTokens: Number.isFinite(cacheRead) ? cacheRead : 0,
                 cacheWriteTokens: Number.isFinite(cacheWrite) ? cacheWrite : 0,
                 totalTokens: Number.isFinite(finalTotal) ? finalTotal : 0,
-            });
+            };
+            const key = buildUsageRecordKey(record);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            records.push(record);
         }
         catch {
             // ignore invalid lines
@@ -1022,6 +1252,7 @@ function readUsageRecords(usagePath) {
     return records;
 }
 function syncUsageFromSessions(config, configPath, usagePath) {
+    var _a, _b;
     const statePath = getUsageStatePath(usagePath, config);
     const lockPath = `${statePath}.lock`;
     const lockFd = acquireLock(lockPath);
@@ -1032,7 +1263,23 @@ function syncUsageFromSessions(config, configPath, usagePath) {
         const logEntries = readProfileLogEntries([profileLogPath]);
         const state = readUsageState(statePath);
         const files = state.files || {};
-        const sessions = state.sessions || {};
+        let sessions = state.sessions || {};
+        const usageStat = readUsageFileStat(usagePath);
+        const hasUsageData = !!usageStat && usageStat.isFile() && usageStat.size > 0;
+        const sessionsEmpty = Object.keys(sessions).length === 0;
+        const hasUsageMeta = Number.isFinite((_a = state.usageMtimeMs) !== null && _a !== void 0 ? _a : Number.NaN) &&
+            Number.isFinite((_b = state.usageSize) !== null && _b !== void 0 ? _b : Number.NaN);
+        const usageOutOfSync = hasUsageData &&
+            (!hasUsageMeta ||
+                state.usageMtimeMs !== usageStat.mtimeMs ||
+                state.usageSize !== usageStat.size);
+        if (hasUsageData && (sessionsEmpty || usageOutOfSync)) {
+            const records = readUsageRecords(usagePath);
+            if (records.length > 0) {
+                sessions = buildUsageSessionsFromRecords(records);
+            }
+        }
+        state.sessions = sessions;
         const codexFiles = collectSessionFiles(getCodexSessionsPath(config));
         const claudeFiles = collectSessionFiles(getClaudeSessionsPath(config));
         const processFile = (filePath, type) => {
@@ -1059,11 +1306,19 @@ function syncUsageFromSessions(config, configPath, usagePath) {
             catch {
                 return;
             }
-            const resolved = resolveProfileForSession(config, logEntries, type, filePath, stats.sessionId);
-            if (!resolved.match)
-                return;
             const sessionKey = stats.sessionId ? buildSessionKey(type, stats.sessionId) : null;
             const sessionPrev = sessionKey ? sessions[sessionKey] : null;
+            const sessionProfile = sessionPrev && (sessionPrev.profileKey || sessionPrev.profileName)
+                ? {
+                    profileKey: sessionPrev.profileKey || null,
+                    profileName: sessionPrev.profileName || null,
+                }
+                : null;
+            const resolved = sessionProfile
+                ? { match: sessionProfile, ambiguous: false }
+                : resolveProfileForSession(config, logEntries, type, filePath, stats.sessionId);
+            if (!resolved.match)
+                return;
             const resolvedModel = (sessionPrev && sessionPrev.model) ||
                 stats.model ||
                 (prev && prev.model) ||
@@ -1156,6 +1411,8 @@ function syncUsageFromSessions(config, configPath, usagePath) {
                     endTs: stats.endTs || (sessionPrev ? sessionPrev.endTs : null),
                     cwd: stats.cwd || (sessionPrev ? sessionPrev.cwd : null),
                     model: resolvedModel,
+                    profileKey: resolved.match.profileKey,
+                    profileName: resolved.match.profileName,
                 };
             }
             files[filePath] = {
@@ -1179,6 +1436,7 @@ function syncUsageFromSessions(config, configPath, usagePath) {
             processFile(filePath, "claude");
         state.files = files;
         state.sessions = sessions;
+        updateUsageStateMetadata(state, usagePath);
         writeUsageState(statePath, state);
     }
     finally {

package/docs/README.md

@@ -0,0 +1,3 @@
+# Docs Index
+
+- [usage.md](usage.md): Usage tracking and statusline input details (Codex/Claude).

package/docs/README_zh.md

@@ -0,0 +1,3 @@
+# 文档索引
+
+- [usage_zh.md](usage_zh.md)：用量统计逻辑与状态栏输入说明。

package/docs/usage.md

@@ -0,0 +1,126 @@
+# Usage tracking
+
+Usage stats are derived from two sources (statusline input + session logs) and appended to `usage.jsonl`.
+
+## Files and paths
+
+- `usage.jsonl`: JSONL records with `ts`, `type`, `profileKey`/`profileName`, `model`, `sessionId`, and token breakdowns.
+- `usage.jsonl.state.json`: per-session totals + per-session-file metadata (mtime/size) used to compute deltas and avoid double counting.
+- `profile-log.jsonl`: profile usage + session binding log (`use` and `session` events).
+- `statusline-debug.jsonl`: optional debug capture when `CODE_ENV_STATUSLINE_DEBUG` is enabled.
+- Paths can be overridden via `usagePath`, `usageStatePath`, `profileLogPath`, `codexSessionsPath`, `claudeSessionsPath`.
+
+## Session binding (profile -> session)
+
+- `codenv init` installs a shell wrapper so `codex`/`claude` run via `codenv launch`.
+- `codenv launch` logs profile usage and then finds the latest unbound session file (prefers matching `cwd`, within a small grace window) and records the binding in `profile-log.jsonl`.
+- Sync uses these bindings to attribute session usage to a profile.
+
+## Statusline sync (`codenv statusline --sync-usage`)
+
+- Requires `sessionId`, model, and a profile (`profileKey` or `profileName`) to write usage.
+- Reads stdin JSON for totals and computes a delta against the last stored totals in the state file.
+- If totals decrease (session reset), the current totals are treated as fresh usage; otherwise negative sub-deltas are clamped to zero.
+- If the token breakdown exceeds the reported total, the breakdown sum wins.
+- Appends a delta record to `usage.jsonl` and updates the per-session totals in the state file.
+
+## Session log sync (`--sync-usage` and `codenv list`)
+
+- Scans Codex sessions under `CODEX_HOME/sessions` (or `~/.codex/sessions`) and Claude sessions under `CLAUDE_HOME/projects` (or `~/.claude/projects`).
+- Codex: parses `event_msg` token_count records and uses max totals; cached input is recorded as cache read and subtracted from input when possible.
+- Claude: sums `message.usage` input/output/cache tokens across the file.
+- Deltas are computed against prior file metadata and per-session maxima in the state file; files without a resolved binding are skipped.
+
+## Daily totals
+
+- "Today" is computed in local time between 00:00 and the next 00:00.
+
+## Cost calculation
+
+- Uses pricing from the profile (or `pricing.models`, plus defaults) and requires token splits; if splits are missing, cost is omitted.
+
+## Examples
+
+### `usage.jsonl` record
+
+Each line is a JSON object (fields may be null/omitted depending on the source):
+
+```json
+{"ts":"2026-01-25T12:34:56.789Z","type":"codex","profileKey":"p_a1b2c3","profileName":"primary","model":"gpt-5.1-codex","sessionId":"a6f9c4d8-1234-5678-9abc-def012345678","inputTokens":1200,"outputTokens":300,"cacheReadTokens":200,"cacheWriteTokens":0,"totalTokens":1700}
+```
+
+`totalTokens` is the max of the reported total and the breakdown sum, so it can be >= input + output + cache.
+
+## Statusline input examples (Codex/Claude)
+
+To see real payloads, set `CODE_ENV_STATUSLINE_DEBUG=1` and read the JSONL entries in
+`statusline-debug.jsonl` (or the path from `CODE_ENV_STATUSLINE_DEBUG_PATH`).
+
+### Codex (token_usage totals)
+
+```json
+{
+  "type": "codex",
+  "session_id": "a6f9c4d8-1234-5678-9abc-def012345678",
+  "profile": { "key": "p_a1b2c3", "name": "primary", "type": "codex" },
+  "model": "gpt-5.1-codex",
+  "token_usage": {
+    "total_token_usage": {
+      "input_tokens": 1200,
+      "output_tokens": 300,
+      "cached_input_tokens": 200,
+      "cache_creation_input_tokens": 50,
+      "total_tokens": 1750
+    },
+    "last_token_usage": {
+      "input_tokens": 100,
+      "output_tokens": 20,
+      "cached_input_tokens": 10,
+      "cache_creation_input_tokens": 0,
+      "total_tokens": 130
+    }
+  }
+}
+```
+
+Accepted aliases (non-exhaustive):
+- `token_usage.total_token_usage` or `token_usage.totalTokenUsage`
+- `last_token_usage` or `lastTokenUsage`
+- `input_tokens` / `inputTokens` / `input`
+- `output_tokens` / `outputTokens` / `output` / `reasoning_output_tokens`
+- `cached_input_tokens` / `cache_read_input_tokens`
+- `cache_creation_input_tokens` / `cache_write_input_tokens`
+- `total_tokens` / `totalTokens` / `total`
+
+`token_usage` can also be a number, or the payload can provide `usage` directly.
+
+### Claude (context_window totals)
+
+```json
+{
+  "type": "claude",
+  "session_id": "1f2e3d4c-5678-90ab-cdef-1234567890ab",
+  "profile": { "key": "p_c3d4e5", "name": "default", "type": "claude" },
+  "model": { "display_name": "Claude Sonnet 4.5" },
+  "context_window": {
+    "total_input_tokens": 800,
+    "total_output_tokens": 250,
+    "current_usage": {
+      "cache_read_input_tokens": 100,
+      "cache_creation_input_tokens": 40
+    },
+    "context_window_size": 200000
+  }
+}
+```
+
+Accepted aliases (non-exhaustive):
+- `context_window` or `contextWindow`
+- `current_usage` or `currentUsage`
+- `total_input_tokens` / `totalInputTokens`
+- `total_output_tokens` / `totalOutputTokens`
+- `cache_read_input_tokens` / `cacheReadInputTokens`
+- `cache_creation_input_tokens` / `cacheWriteInputTokens`
+
+`usage` can also be provided directly with `todayTokens` / `totalTokens` / `inputTokens` /
+`outputTokens` / `cacheReadTokens` / `cacheWriteTokens`.