tokentracker-cli 1.1.2 → 1.1.4

package/src/lib/trae-db.js

@@ -0,0 +1,127 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { openTraeSnapshot } = require("./trae-snapshot");
+const { withTraeSqlite } = require("./trae-sqlite");
+
+const TOKEN_FIELDS = [
+  "prompt_tokens", "prompt_tokens_total", "input_tokens",
+  "completion_tokens", "completion_tokens_total", "output_tokens",
+  "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens",
+  "reasoning_tokens", "reasoning_output_tokens",
+];
+
+function resolveTraeDbPaths(env = process.env, { platform = process.platform, home = os.homedir() } = {}) {
+  const explicit = String(env.TOKENTRACKER_TRAE_DB || "").trim();
+  if (explicit) return [path.resolve(explicit)];
+  const customHome = String(env.TOKENTRACKER_TRAE_HOME || "").trim();
+  const parent = platform === "win32"
+    ? env.APPDATA || path.join(home, "AppData", "Roaming")
+    : platform === "darwin"
+      ? path.join(home, "Library", "Application Support")
+      : env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const roots = customHome ? [customHome] : [path.join(parent, "Trae"), path.join(parent, "TRAE SOLO")];
+  const result = [];
+  for (const root of roots) {
+    // A decrypted sibling may be an old export. Only an explicit DB override
+    // opts into one; normal discovery always reads the current application DB.
+    for (const module of ["ai-agent", "ai-chat"]) {
+      const candidate = path.resolve(root, "ModularData", module, "database.db");
+      let present;
+      try { present = fs.statSync(candidate).isFile(); }
+      catch (err) {
+        // Permission failures must reach the reader's diagnostics, not masquerade
+        // as an absent installation and silently drop an entire usage history.
+        present = err.code !== "ENOENT" && err.code !== "ENOTDIR";
+      }
+      if (present) {
+        result.push(candidate);
+        break;
+      }
+    }
+  }
+  return [...new Set(result)];
+}
+
+function error(message) {
+  return new Error(`Cannot read TRAE usage: ${message}`);
+}
+
+async function projectUsage(queryRows) {
+  const tables = await queryRows("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'chat_turn'");
+  // history_v2.token_usage can be a context-size snapshot rather than billed
+  // usage. Do not synthesize input tokens from those scalar values.
+  if (!tables.length) throw error("unsupported database schema: chat_turn table is missing.");
+  const columns = new Set((await queryRows("PRAGMA table_info(chat_turn)")).map((row) => row.name));
+  if (!columns.has("context") || (!columns.has("created_at") && !columns.has("updated_at"))) {
+    throw error("unsupported chat_turn schema.");
+  }
+  const column = (name, fallback = "NULL") => columns.has(name) ? `"${name}"` : fallback;
+  const date = columns.has("created_at") && columns.has("updated_at")
+    ? 'COALESCE("created_at", "updated_at")' : column("created_at", column("updated_at"));
+  const modelPaths = [
+    "persist_user_message_context.model_info.display_model_name",
+    "persist_user_message_context.model_info.model_name",
+    "persist_user_message_context.model_info.config_name", "model_name", "model",
+    "agent_model", "selected_model.name", "selectedModel.name",
+  ];
+  const model = modelPaths.map((field) => `CASE WHEN json_type(context, '$.${field}') = 'text'
+    THEN NULLIF(NULLIF(TRIM(json_extract(context, '$.${field}')), ''), '-') END`);
+  const fields = TOKEN_FIELDS.map((field) => `CASE
+    WHEN json_type(context, '$.token_usage.${field}') IN ('integer', 'real')
+    THEN json_extract(context, '$.token_usage.${field}') END AS "${field}"`);
+  const invalidFields = TOKEN_FIELDS.map((field) =>
+    `COALESCE(json_type(context, '$.token_usage.${field}') NOT IN ('integer', 'real', 'null'), 0)`);
+  // Project inside SQLite: prompts, messages, session titles, fee/account data,
+  // and the rest of the context never cross into JS results or cursor state.
+  const query = `SELECT CAST(${column("id", "rowid")} AS TEXT) AS id,
+    ${column("session_id")} AS session_id, ${column("turn_id")} AS turn_id,
+    ${date} AS created_at, ${column("updated_at")} AS updated_at,
+    COALESCE(${model.join(", ")}, 'trae-unknown') AS model,
+    ${fields.join(", ")}, (${invalidFields.join(" OR ")}) AS invalid_usage
+    FROM chat_turn WHERE CASE WHEN json_valid(context)
+      THEN json_type(context, '$.token_usage') = 'object' ELSE 0 END`;
+  return (await queryRows(query)).map((row) => {
+    const usage = {};
+    let invalid = Boolean(row.invalid_usage);
+    for (const field of TOKEN_FIELDS) {
+      const value = row[field];
+      if (value == null) continue;
+      if (!Number.isSafeInteger(value) || value < 0) invalid = true;
+      else usage[field] = value;
+    }
+    return {
+      id: row.id, session_id: row.session_id, turn_id: row.turn_id,
+      created_at: row.created_at, updated_at: row.updated_at,
+      model: row.model, usage: invalid ? null : usage,
+    };
+  });
+}
+
+async function readTraeUsageRows(dbPath, { env = process.env } = {}) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let snapshot;
+    try { snapshot = openTraeSnapshot(dbPath, env); }
+    catch (err) {
+      // A writer can also change the files while the snapshot opens. Retry
+      // that too, and report the specific failure once attempts run out.
+      if (err?.transient && attempt < 2) continue;
+      throw err;
+    }
+    try {
+      let result;
+      try { result = await withTraeSqlite(snapshot, projectUsage); }
+      catch (err) {
+        // A writer may have changed pages while SQLite was reading. Discard
+        // every projected row and retry; never publish a mixed snapshot.
+        if (snapshot.isStable()) throw err;
+        continue;
+      }
+      if (snapshot.isStable()) return result;
+    } finally { snapshot.close(); }
+  }
+  throw error("database changed during the read; retry after TRAE finishes its current turn.");
+}
+
+module.exports = { resolveTraeDbPaths, readTraeUsageRows };

package/src/lib/trae-snapshot.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+
+const SQLITE_HEADER = Buffer.from("SQLite format 3\0");
+const PAGE_SIZE = 4096;
+const RESERVED = 80;
+// TRAE's shared application key
+const DEFAULT_SQLCIPHER_KEY = "3605f6691095a993f03d5009c918352ef5be31ae31e8f000212b81ff058da773";
+const CACHE_PAGES = 64;
+const MAX_WAL_INDEX_PAGES = 1024 * 1024;
+
+function error(message) { return new Error(`Cannot read TRAE usage: ${message}`); }
+// A writer race rather than a bad store: the caller may retry immediately.
+function transientError(message) { return Object.assign(error(message), { transient: true }); }
+
+function statOptional(file) {
+  try { return fs.statSync(file, { bigint: true }); }
+  catch (err) { if (err.code === "ENOENT" || err.code === "ENOTDIR") return null; throw err; }
+}
+
+function sameStat(a, b) {
+  if (!a || !b) return a === b;
+  return a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && a.ino === b.ino;
+}
+
+function readExact(fd, target, offset) {
+  let read = 0;
+  while (read < target.length) {
+    const count = fs.readSync(fd, target, read, target.length - read, offset + read);
+    if (!count) throw transientError("database or WAL was truncated during the read; retry when TRAE is idle.");
+    read += count;
+  }
+  return target;
+}
+
+function pageDecryptor(firstPage, env) {
+  const hex = String(env.TOKENTRACKER_TRAE_SQLCIPHER_KEY || "").trim() || DEFAULT_SQLCIPHER_KEY;
+  if (!/^[0-9a-f]{64}$/i.test(hex)) throw error("TOKENTRACKER_TRAE_SQLCIPHER_KEY must contain 64 hex characters.");
+  const key = Buffer.from(hex, "hex");
+  const salt = Buffer.from(firstPage.subarray(0, 16).map((byte) => byte ^ 0x3a));
+  // SQLCipher 4 raw-key format: AES-256-CBC, 4096-byte pages, SHA-512 HMAC.
+  // https://github.com/sqlcipher/sqlcipher/blob/master/src/sqlcipher.c
+  const hmacKey = crypto.pbkdf2Sync(key, salt, 2, 32, "sha512");
+  salt.fill(0);
+  return {
+    decrypt(page, number) {
+      const start = number === 1 ? 16 : 0;
+      const ivOffset = PAGE_SIZE - RESERVED;
+      const pageId = Buffer.alloc(4);
+      pageId.writeUInt32LE(number);
+      const expected = crypto.createHmac("sha512", hmacKey)
+        .update(page.subarray(start, ivOffset + 16)).update(pageId).digest();
+      if (!crypto.timingSafeEqual(expected, page.subarray(ivOffset + 16))) {
+        throw error("SQLCipher authentication failed (incorrect key, unsupported format, or damaged database); set TOKENTRACKER_TRAE_SQLCIPHER_KEY to override the shared application key.");
+      }
+      const decipher = crypto.createDecipheriv("aes-256-cbc", key, page.subarray(ivOffset, ivOffset + 16));
+      decipher.setAutoPadding(false);
+      const decoded = decipher.update(page.subarray(start, ivOffset));
+      decipher.final();
+      page.fill(0);
+      if (number === 1) SQLITE_HEADER.copy(page);
+      decoded.copy(page, start);
+      decoded.fill(0);
+      if (number === 1 && (page.readUInt16BE(16) !== PAGE_SIZE || page[20] !== RESERVED)) {
+        throw error("unsupported SQLCipher page format.");
+      }
+      return page;
+    },
+    dispose() { key.fill(0); hmacKey.fill(0); },
+  };
+}
+
+function checksum(data, bigEndian, state = [0, 0]) {
+  let [a, b] = state;
+  for (let i = 0; i < data.length; i += 8) {
+    const x = bigEndian ? data.readUInt32BE(i) : data.readUInt32LE(i);
+    const y = bigEndian ? data.readUInt32BE(i + 4) : data.readUInt32LE(i + 4);
+    a = (a + x + b) >>> 0;
+    b = (b + y + a) >>> 0;
+  }
+  return [a, b];
+}
+
+function indexWal(fd, size, pageSize) {
+  const pages = new Map();
+  if (fd == null || size === 0) return { pages, pageCount: null };
+  if (size < 32) throw transientError("incomplete WAL header; retry when TRAE is idle.");
+  const header = readExact(fd, Buffer.alloc(32), 0);
+  const magic = header.readUInt32BE(0);
+  if ((magic !== 0x377f0682 && magic !== 0x377f0683) ||
+      header.readUInt32BE(4) !== 3007000 || header.readUInt32BE(8) !== pageSize) {
+    throw error("unsupported WAL format.");
+  }
+  const bigEndian = magic === 0x377f0683;
+  let sum = checksum(header.subarray(0, 24), bigEndian);
+  if (sum[0] !== header.readUInt32BE(24) || sum[1] !== header.readUInt32BE(28)) throw error("WAL header checksum failed.");
+  let pageCount = null;
+  let pending = new Map();
+  const frame = Buffer.alloc(24 + pageSize);
+  // Index offsets instead of buffering/decrypting an entire WAL. Uncommitted
+  // frames never enter the visible page map. SQLite checksums cover ciphertext.
+  // https://www.sqlite.org/fileformat2.html#walformat
+  for (let offset = 32; offset + frame.length <= size; offset += frame.length) {
+    readExact(fd, frame, offset);
+    if (!frame.subarray(8, 16).equals(header.subarray(16, 24))) break;
+    // Like a salt mismatch, the first checksum mismatch ends the valid log (a
+    // torn append or crash leftover); only committed frames before it count.
+    sum = checksum(frame.subarray(24), bigEndian, checksum(frame.subarray(0, 8), bigEndian, sum));
+    if (sum[0] !== frame.readUInt32BE(16) || sum[1] !== frame.readUInt32BE(20)) break;
+    const number = frame.readUInt32BE(0);
+    const commit = frame.readUInt32BE(4);
+    if (!number || number === 0xffffffff || commit === 0xffffffff) throw error("invalid WAL page number or database size.");
+    pending.set(number, offset + 24);
+    if (pending.size + pages.size > MAX_WAL_INDEX_PAGES) throw error("WAL index exceeds the bounded-memory limit; let TRAE checkpoint its WAL and retry.");
+    if (commit) {
+      for (const [page, position] of pending) pages.set(page, position);
+      pending = new Map();
+      pageCount = commit;
+      for (const page of pages.keys()) if (page > commit) pages.delete(page);
+    }
+  }
+  frame.fill(0);
+  return { pages, pageCount };
+}
+
+// A read-only, optimistic snapshot. SQLite reads authenticated pages on demand;
+// no decrypted database is ever written to disk or materialized in memory.
+// The caller must discard results if isStable() fails after the SQL query.
+function openTraeSnapshot(dbPath, env = process.env) {
+  const paths = [dbPath, `${dbPath}-wal`, `${dbPath}-journal`];
+  const before = paths.map(statOptional);
+  if (!before[0]) throw error("database no longer exists.");
+  if (before.some((stat) => stat && (!stat.isFile() || stat.size > BigInt(Number.MAX_SAFE_INTEGER)))) {
+    throw error("unsupported database file or size.");
+  }
+  const handles = [];
+  const cache = new Map();
+  let decryptor;
+  const close = () => {
+    for (const page of cache.values()) page.fill(0);
+    cache.clear();
+    if (decryptor) { decryptor.dispose(); decryptor = null; }
+    let failure;
+    while (handles.length) {
+      try { fs.closeSync(handles.pop()); }
+      catch (err) { failure ||= err; }
+    }
+    if (failure) throw failure;
+  };
+  try {
+    const dbFd = fs.openSync(dbPath, "r");
+    handles.push(dbFd);
+    if (!sameStat(before[0], fs.fstatSync(dbFd, { bigint: true }))) throw transientError("database changed while opening; retry when TRAE is idle.");
+    let walFd = null;
+    if (before[1]) {
+      walFd = fs.openSync(paths[1], "r");
+      handles.push(walFd);
+      if (!sameStat(before[1], fs.fstatSync(walFd, { bigint: true }))) throw transientError("WAL changed while opening; retry when TRAE is idle.");
+    }
+    if (before[2] && before[2].size >= 8n) {
+      const journalFd = fs.openSync(paths[2], "r");
+      handles.push(journalFd);
+      if (readExact(journalFd, Buffer.alloc(8), 0).some((byte) => byte !== 0)) throw error("a rollback transaction is active; retry when TRAE is idle.");
+    }
+    const size = Number(before[0].size);
+    if (size < 100) throw error("database is truncated.");
+    const header = readExact(dbFd, Buffer.alloc(100), 0);
+    const encrypted = !header.subarray(0, 16).equals(SQLITE_HEADER);
+    const encodedSize = encrypted ? PAGE_SIZE : header.readUInt16BE(16);
+    const pageSize = encodedSize === 1 ? 65536 : encodedSize;
+    if (pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) || size % pageSize) throw error("invalid database page size or truncated database.");
+    if (encrypted) decryptor = pageDecryptor(header, env);
+    const { pages, pageCount } = indexWal(walFd, Number(before[1]?.size || 0n), pageSize);
+    const finalPageCount = pageCount == null ? size / pageSize : pageCount;
+    if (!finalPageCount || finalPageCount > 0xfffffffe) throw error("invalid database size.");
+    const byteLength = finalPageCount * pageSize;
+    const getPage = (number) => {
+      if (cache.has(number)) {
+        const page = cache.get(number);
+        cache.delete(number);
+        cache.set(number, page);
+        return page;
+      }
+      const page = Buffer.alloc(pageSize);
+      try {
+        if (pages.has(number)) readExact(walFd, page, pages.get(number));
+        else readExact(dbFd, page, (number - 1) * pageSize);
+        if (decryptor) decryptor.decrypt(page, number);
+        if (number === 1) {
+          // Present the committed view as a standalone rollback-mode database.
+          page[18] = 1;
+          page[19] = 1;
+          page.writeUInt32BE(finalPageCount, 28);
+          page.writeUInt32BE(page.readUInt32BE(24), 92);
+        }
+      } catch (err) { page.fill(0); throw err; }
+      cache.set(number, page);
+      if (cache.size > CACHE_PAGES) {
+        const oldest = cache.keys().next().value;
+        cache.get(oldest).fill(0);
+        cache.delete(oldest);
+      }
+      return page;
+    };
+    return {
+      byteLength,
+      read(target, offset) {
+        if (!Number.isSafeInteger(offset) || offset < 0) throw error("invalid read offset.");
+        target.fill(0);
+        const count = Math.min(target.length, Math.max(0, byteLength - offset));
+        let copied = 0;
+        while (copied < count) {
+          const position = offset + copied;
+          const pageOffset = position % pageSize;
+          const length = Math.min(count - copied, pageSize - pageOffset);
+          const page = getPage(Math.floor(position / pageSize) + 1);
+          target.set(page.subarray(pageOffset, pageOffset + length), copied);
+          copied += length;
+        }
+        return count;
+      },
+      isStable() { return paths.map(statOptional).every((stat, i) => sameStat(before[i], stat)); },
+      close,
+    };
+  } catch (err) { close(); throw err; }
+}
+
+module.exports = { openTraeSnapshot };

package/src/lib/trae-sqlite.js

@@ -0,0 +1,143 @@
+const fs = require("node:fs");
+
+let enginePromise;
+let queryQueue = Promise.resolve();
+
+async function createEngine() {
+  const [{ default: initialize }, sqlite, { FacadeVFS }] = await Promise.all([
+    import("@journeyapps/wa-sqlite/dist/wa-sqlite.mjs"),
+    import("@journeyapps/wa-sqlite"),
+    import("@journeyapps/wa-sqlite/src/FacadeVFS.js"),
+  ]);
+  const module = await initialize({
+    wasmBinary: fs.readFileSync(require.resolve("@journeyapps/wa-sqlite/dist/wa-sqlite.wasm")),
+  });
+  const api = sqlite.Factory(module);
+  const snapshots = new Map();
+  const handles = new Map();
+
+  // Register one VFS for the lifetime of the engine. Each query gets a distinct
+  // virtual filename, without accumulating WASM callbacks or touching disk.
+  class TraeVFS extends FacadeVFS {
+    constructor() {
+      super("tokentracker-trae", module);
+    }
+
+    jOpen(name, fileId, flags, outputFlags) {
+      const state = snapshots.get(name);
+      if (!state || !(flags & sqlite.SQLITE_OPEN_MAIN_DB)) return sqlite.SQLITE_CANTOPEN;
+      handles.set(fileId, state);
+      outputFlags.setInt32(0, sqlite.SQLITE_OPEN_READONLY, true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jRead(fileId, output, offset) {
+      const state = handles.get(fileId);
+      if (!state) return sqlite.SQLITE_IOERR_READ;
+      // FacadeVFS passes a proxy over WASM memory, not a native Uint8Array.
+      // Keep the temporary buffer small and erase it after copying its page.
+      const buffer = Buffer.alloc(output.byteLength);
+      try {
+        const count = state.snapshot.read(buffer, offset);
+        if (!Number.isSafeInteger(count) || count < 0 || count > buffer.length) {
+          throw new Error("Invalid TRAE snapshot read length.");
+        }
+        buffer.fill(0, count);
+        output.set(buffer);
+        return count === buffer.length ? sqlite.SQLITE_OK : sqlite.SQLITE_IOERR_SHORT_READ;
+      } catch (err) {
+        state.error ||= err;
+        output.fill(0);
+        return sqlite.SQLITE_IOERR_READ;
+      } finally {
+        buffer.fill(0);
+      }
+    }
+
+    jFileSize(fileId, output) {
+      const state = handles.get(fileId);
+      if (!state) return sqlite.SQLITE_IOERR_FSTAT;
+      output.setBigInt64(0, BigInt(state.snapshot.byteLength), true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jClose(fileId) {
+      handles.delete(fileId);
+      return sqlite.SQLITE_OK;
+    }
+
+    jAccess(name, flags, output) {
+      output.setInt32(0, snapshots.has(name) ? 1 : 0, true);
+      return sqlite.SQLITE_OK;
+    }
+
+    jWrite() { return sqlite.SQLITE_READONLY; }
+    jTruncate() { return sqlite.SQLITE_READONLY; }
+    jDelete() { return sqlite.SQLITE_READONLY; }
+  }
+
+  const vfs = new TraeVFS();
+  api.vfs_register(vfs, false);
+  return { api, sqlite, snapshots, handles, vfs, nextId: 0 };
+}
+
+/**
+ * Query a read-only, random-access snapshot without materializing its database.
+ * The caller owns snapshot cleanup; only the projected SQL rows leave this VFS.
+ */
+async function querySnapshot(snapshot, callback) {
+  if (!Number.isSafeInteger(snapshot.byteLength) || snapshot.byteLength < 0) {
+    throw new Error("Invalid TRAE snapshot size.");
+  }
+  enginePromise ||= createEngine().catch((err) => {
+    enginePromise = undefined;
+    throw err;
+  });
+  const engine = await enginePromise;
+  const { api, sqlite, snapshots, handles, vfs } = engine;
+  const name = `trae-${++engine.nextId}.db`;
+  const state = { snapshot, error: null };
+  snapshots.set(name, state);
+  let db;
+  let failure;
+  try {
+    db = await api.open_v2(name, sqlite.SQLITE_OPEN_READONLY, vfs.name);
+    const query = async (sql) => {
+      const rows = [];
+      try {
+        await api.exec(db, sql, (values, columns) => {
+          rows.push(Object.fromEntries(columns.map((column, index) => [column, values[index]])));
+        });
+      } catch (err) {
+        throw state.error || err;
+      }
+      return rows;
+    };
+    await query("PRAGMA query_only=ON; PRAGMA cache_size=-4096; PRAGMA temp_store=MEMORY;");
+    return await callback(query);
+  } catch (err) {
+    failure = state.error || err;
+    throw failure;
+  } finally {
+    try {
+      if (db) await api.close(db);
+    } catch (err) {
+      if (!failure) throw state.error || err;
+    } finally {
+      snapshots.delete(name);
+      for (const [fileId, opened] of handles) {
+        if (opened === state) handles.delete(fileId);
+      }
+    }
+  }
+}
+
+function withTraeSqlite(snapshot, callback) {
+  // The package's async convenience API shares temporary WASM allocations.
+  // Serialize access to the single engine even when callers read in parallel.
+  const operation = queryQueue.then(() => querySnapshot(snapshot, callback));
+  queryQueue = operation.catch(() => {});
+  return operation;
+}
+
+module.exports = { withTraeSqlite };

package/src/lib/trae-usage.js

@@ -0,0 +1,121 @@
+"use strict";
+
+// TRAE stores the last request's usage alongside optional whole-turn prompt
+// and completion counters. Reconcile the request first: its total cannot
+// validate a whole-turn count, and its cache count is not a whole-turn count.
+function normalizeTraeUsage(raw, { model } = {}) {
+  let usage = raw;
+  if (typeof usage === "string") {
+    try { usage = JSON.parse(usage); } catch { return null; }
+  }
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
+  const fields = [
+    "prompt_tokens", "prompt_tokens_total", "input_tokens",
+    "completion_tokens", "completion_tokens_total", "output_tokens",
+    "cache_read_input_tokens", "cache_creation_input_tokens",
+    "reasoning_tokens", "reasoning_output_tokens", "total_tokens",
+  ];
+  for (const field of fields) {
+    if (usage[field] != null && (!Number.isSafeInteger(usage[field]) || usage[field] < 0)) {
+      return null;
+    }
+  }
+  for (const [left, right] of [["prompt_tokens", "input_tokens"],
+    ["completion_tokens", "output_tokens"], ["reasoning_tokens", "reasoning_output_tokens"]]) {
+    if (usage[left] != null && usage[right] != null && usage[left] !== usage[right]) return null;
+  }
+  if (!["prompt_tokens", "prompt_tokens_total", "input_tokens", "completion_tokens",
+    "completion_tokens_total", "output_tokens"].some((field) => usage[field] != null)) {
+    return null;
+  }
+  const input = usage.prompt_tokens ?? usage.input_tokens ?? usage.prompt_tokens_total ?? 0;
+  const output = usage.completion_tokens ?? usage.output_tokens ?? usage.completion_tokens_total ?? 0;
+  const aggregateInput = usage.prompt_tokens_total > 0 ? usage.prompt_tokens_total : input;
+  const aggregateOutput = usage.completion_tokens_total > 0 ? usage.completion_tokens_total : output;
+  if (aggregateInput < input || aggregateOutput < output) return null;
+  const cached = usage.cache_read_input_tokens ?? 0;
+  let written = usage.cache_creation_input_tokens ?? 0;
+  let reasoning = usage.reasoning_tokens ?? usage.reasoning_output_tokens ?? 0;
+  let estimated = false;
+  const isGemini = /^gemini(?:-|$)/i.test(normalizeTraeModel(model ?? usage.name));
+  // Some TRAE Gemini rows copy the cache-read counter into the write field,
+  // even when their sum exceeds the entire prompt. Gemini's GenerateContent
+  // metadata reports cachedContentTokenCount, not an additional write count.
+  // Keep the reported read and mark this narrow compatibility repair estimated.
+  if (isGemini && cached > 0 && written === cached && cached + written > input) {
+    written = 0;
+    estimated = true;
+  }
+  // Older TRAE Gemini rows omit thoughts while retaining Gemini's total
+  // (prompt + candidates + thoughts). Infer only that documented residual,
+  // never an arbitrary provider's unexplained total.
+  if (isGemini && usage.reasoning_tokens == null && usage.reasoning_output_tokens == null &&
+    usage.total_tokens > input + output && written === 0 && cached <= input) {
+    reasoning = usage.total_tokens - input - output;
+    estimated = true;
+  }
+  // A total is necessary to distinguish inclusive/exclusive counters when
+  // cache or reasoning is present. Missing metadata must not imply $0 usage
+  // or guessed input. A zero *_total field means unset, not an empty turn.
+  if (usage.total_tokens == null && (cached || written || reasoning)) return null;
+  const total = usage.total_tokens ?? (input + output);
+  if (!Number.isSafeInteger(total)) return null;
+  const candidates = new Map();
+  for (const includedCache of new Set([cached + written, cached, 0])) {
+    for (const includedReasoning of new Set([reasoning, 0])) {
+      const noncached = input - includedCache;
+      const nonreasoning = output - includedReasoning;
+      if (noncached < 0 || nonreasoning < 0) continue;
+      if (noncached + cached + written + nonreasoning + reasoning !== total) continue;
+      const totals = {
+        input_tokens: noncached,
+        cached_input_tokens: cached,
+        cache_creation_input_tokens: written,
+        output_tokens: nonreasoning,
+        reasoning_output_tokens: reasoning,
+        total_tokens: total,
+      };
+      candidates.set(JSON.stringify(totals), totals);
+    }
+  }
+  if (candidates.size !== 1) return null;
+  const totals = candidates.values().next().value;
+  if (aggregateInput !== input || aggregateOutput !== output) {
+    // The *_total counters cover the whole turn; the cache and reasoning fields
+    // describe its final request. The difference in prompt tokens has no cache
+    // split, so it counts toward total_tokens but no priced column. Completion
+    // tokens are priced the same with or without caching and stay in output.
+    const unpriced = aggregateInput - input;
+    totals.output_tokens += aggregateOutput - output;
+    totals.total_tokens += unpriced + aggregateOutput - output;
+    if (unpriced > 0) totals.unpriced_input_tokens = unpriced;
+  }
+  if (Object.values(totals).some((value) => !Number.isSafeInteger(value))) return null;
+  if (estimated) totals.usage_precision = "estimated";
+  return totals;
+}
+
+function normalizeTraeModel(value) {
+  if (typeof value !== "string") return "trae-unknown";
+  const model = value.trim().split("__")[0].toLowerCase().replace(/\s+/g, "-");
+  // TRAE's display alias otherwise fuzzy-matches a regional Sonnet SKU and
+  // loses cache pricing. Sonnet 4 has the fixed 2025-05-14 API model id.
+  if (model === "claude-4-sonnet") return "claude-sonnet-4-20250514";
+  return model && model !== "-" && !model.includes("|") ? model : "trae-unknown";
+}
+
+function traeTimestamp(value) {
+  if (value == null || value === "") return null;
+  let millis;
+  if (typeof value === "number" || (typeof value === "string" && /^\d+(\.\d+)?$/.test(value))) {
+    const numeric = Number(value);
+    millis = numeric < 100_000_000_000 ? numeric * 1000 : numeric;
+  } else if (typeof value === "string") {
+    millis = Date.parse(value);
+  }
+  if (!Number.isFinite(millis) || millis <= 0) return null;
+  const date = new Date(millis);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+}
+
+module.exports = { normalizeTraeUsage, normalizeTraeModel, traeTimestamp };