@chrysb/alphaclaw 0.4.3 → 0.4.5

package/lib/server/constants.js

@@ -1,11 +1,7 @@
 const os = require("os");
 const path = require("path");
 const kBrowseFilePolicies = require("../public/shared/browse-file-policies.json");
-
-const parsePositiveIntEnv = (value, fallbackValue) => {
-  const parsed = Number.parseInt(String(value || ""), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallbackValue;
-};
+const { parsePositiveInt } = require("./utils/number");
 
 // Portable root directory: --root-dir flag sets ALPHACLAW_ROOT_DIR before require
 const kRootDir =
@@ -38,29 +34,29 @@ const CODEX_OAUTH_SCOPE = "openid profile email offline_access";
 const CODEX_JWT_CLAIM_PATH = "https://api.openai.com/auth";
 const kCodexOauthStateTtlMs = 10 * 60 * 1000;
 
-const kTrustProxyHops = parsePositiveIntEnv(process.env.TRUST_PROXY_HOPS, 1);
-const kLoginWindowMs = parsePositiveIntEnv(
+const kTrustProxyHops = parsePositiveInt(process.env.TRUST_PROXY_HOPS, 1);
+const kLoginWindowMs = parsePositiveInt(
   process.env.LOGIN_RATE_WINDOW_MS,
   10 * 60 * 1000,
 );
-const kLoginMaxAttempts = parsePositiveIntEnv(
+const kLoginMaxAttempts = parsePositiveInt(
   process.env.LOGIN_RATE_MAX_ATTEMPTS,
   5,
 );
-const kLoginBaseLockMs = parsePositiveIntEnv(
+const kLoginBaseLockMs = parsePositiveInt(
   process.env.LOGIN_RATE_BASE_LOCK_MS,
   60 * 1000,
 );
-const kLoginMaxLockMs = parsePositiveIntEnv(
+const kLoginMaxLockMs = parsePositiveInt(
   process.env.LOGIN_RATE_MAX_LOCK_MS,
   15 * 60 * 1000,
 );
-const kLoginCleanupIntervalMs = parsePositiveIntEnv(
+const kLoginCleanupIntervalMs = parsePositiveInt(
   process.env.LOGIN_RATE_CLEANUP_INTERVAL_MS,
   60 * 1000,
 );
 const kLoginStateTtlMs = Math.max(
-  parsePositiveIntEnv(
+  parsePositiveInt(
     process.env.LOGIN_RATE_STATE_TTL_MS,
     Math.max(kLoginWindowMs, kLoginMaxLockMs) * 3,
   ),
@@ -116,31 +112,31 @@ const kLatestVersionCacheTtlMs = 10 * 60 * 1000;
 const kOpenclawRegistryUrl = "https://registry.npmjs.org/openclaw";
 const kAlphaclawRegistryUrl = "https://registry.npmjs.org/@chrysb%2falphaclaw";
 const kAppDir = kNpmPackageRoot;
-const kMaxPayloadBytes = parsePositiveIntEnv(process.env.WEBHOOK_LOG_MAX_BYTES, 50 * 1024);
-const kWebhookPruneDays = parsePositiveIntEnv(process.env.WEBHOOK_LOG_RETENTION_DAYS, 30);
+const kMaxPayloadBytes = parsePositiveInt(process.env.WEBHOOK_LOG_MAX_BYTES, 50 * 1024);
+const kWebhookPruneDays = parsePositiveInt(process.env.WEBHOOK_LOG_RETENTION_DAYS, 30);
 const kWatchdogCheckIntervalMs =
-  parsePositiveIntEnv(process.env.WATCHDOG_CHECK_INTERVAL, 120) * 1000;
+  parsePositiveInt(process.env.WATCHDOG_CHECK_INTERVAL, 120) * 1000;
 const kWatchdogDegradedCheckIntervalMs =
-  parsePositiveIntEnv(process.env.WATCHDOG_DEGRADED_CHECK_INTERVAL, 5) * 1000;
-const kWatchdogStartupFailureThreshold = parsePositiveIntEnv(
+  parsePositiveInt(process.env.WATCHDOG_DEGRADED_CHECK_INTERVAL, 5) * 1000;
+const kWatchdogStartupFailureThreshold = parsePositiveInt(
   process.env.WATCHDOG_STARTUP_FAILURE_THRESHOLD,
   3,
 );
-const kWatchdogMaxRepairAttempts = parsePositiveIntEnv(
+const kWatchdogMaxRepairAttempts = parsePositiveInt(
   process.env.WATCHDOG_MAX_REPAIR_ATTEMPTS,
   2,
 );
 const kWatchdogCrashLoopWindowMs =
-  parsePositiveIntEnv(process.env.WATCHDOG_CRASH_LOOP_WINDOW, 300) * 1000;
-const kWatchdogCrashLoopThreshold = parsePositiveIntEnv(
+  parsePositiveInt(process.env.WATCHDOG_CRASH_LOOP_WINDOW, 300) * 1000;
+const kWatchdogCrashLoopThreshold = parsePositiveInt(
   process.env.WATCHDOG_CRASH_LOOP_THRESHOLD,
   3,
 );
-const kWatchdogLogRetentionDays = parsePositiveIntEnv(
+const kWatchdogLogRetentionDays = parsePositiveInt(
   process.env.WATCHDOG_LOG_RETENTION_DAYS,
   30,
 );
-const kLogMaxBytes = parsePositiveIntEnv(
+const kLogMaxBytes = parsePositiveInt(
   process.env.LOG_MAX_BYTES,
   2 * 1024 * 1024,
 );
@@ -266,17 +262,17 @@ const GOG_CREDENTIALS_PATH = path.join(GOG_CONFIG_DIR, "credentials.json");
 const GOG_STATE_PATH = path.join(GOG_CONFIG_DIR, "state.json");
 const GOG_KEYRING_PASSWORD = process.env.GOG_KEYRING_PASSWORD || "alphaclaw";
 const kMaxGoogleAccounts = 5;
-const kGmailServeBasePort = parsePositiveIntEnv(
+const kGmailServeBasePort = parsePositiveInt(
   process.env.GMAIL_SERVE_BASE_PORT,
   18801,
 );
 const kGmailWatchRenewalIntervalMs =
-  parsePositiveIntEnv(process.env.GMAIL_WATCH_RENEWAL_INTERVAL_SECONDS, 6 * 60 * 60) *
+  parsePositiveInt(process.env.GMAIL_WATCH_RENEWAL_INTERVAL_SECONDS, 6 * 60 * 60) *
   1000;
 const kGmailWatchRenewalThresholdMs =
-  parsePositiveIntEnv(process.env.GMAIL_WATCH_RENEWAL_THRESHOLD_SECONDS, 24 * 60 * 60) *
+  parsePositiveInt(process.env.GMAIL_WATCH_RENEWAL_THRESHOLD_SECONDS, 24 * 60 * 60) *
   1000;
-const kGmailMaxBodyBytes = parsePositiveIntEnv(
+const kGmailMaxBodyBytes = parsePositiveInt(
   process.env.GMAIL_WATCH_MAX_BODY_BYTES,
   20000,
 );

package/lib/server/db/usage/index.js

@@ -0,0 +1,35 @@
+const fs = require("fs");
+const path = require("path");
+const { DatabaseSync } = require("node:sqlite");
+const { ensureSchema } = require("./schema");
+const { getDailySummary } = require("./summary");
+const { getSessionsList, getSessionDetail } = require("./sessions");
+const { getSessionTimeSeries } = require("./timeseries");
+const { kGlobalModelPricing } = require("./pricing");
+
+let db = null;
+let usageDbPath = "";
+
+const ensureDb = () => {
+  if (!db) throw new Error("Usage DB not initialized");
+  return db;
+};
+
+const initUsageDb = ({ rootDir }) => {
+  const dbDir = path.join(rootDir, "db");
+  fs.mkdirSync(dbDir, { recursive: true });
+  usageDbPath = path.join(dbDir, "usage.db");
+  db = new DatabaseSync(usageDbPath);
+  ensureSchema(db);
+  return { path: usageDbPath };
+};
+
+module.exports = {
+  initUsageDb,
+  getDailySummary: (options = {}) => getDailySummary({ database: ensureDb(), ...options }),
+  getSessionsList: (options = {}) => getSessionsList({ database: ensureDb(), ...options }),
+  getSessionDetail: (options = {}) => getSessionDetail({ database: ensureDb(), ...options }),
+  getSessionTimeSeries: (options = {}) =>
+    getSessionTimeSeries({ database: ensureDb(), ...options }),
+  kGlobalModelPricing,
+};

package/lib/server/db/usage/pricing.js

@@ -0,0 +1,82 @@
+const kTokensPerMillion = 1_000_000;
+const kLongContextThresholdTokens = 200_000;
+const kGlobalModelPricing = {
+  "claude-opus-4-6": {
+    input: (tokens) => (tokens > kLongContextThresholdTokens ? 10.0 : 5.0),
+    output: (tokens) => (tokens > kLongContextThresholdTokens ? 37.5 : 25.0),
+  },
+  "claude-sonnet-4-6": { input: 3.0, output: 15.0 },
+  "claude-haiku-4-6": { input: 0.8, output: 4.0 },
+  "gpt-5": { input: 1.25, output: 10.0 },
+  "gpt-5.1-codex": { input: 2.5, output: 10.0 },
+  "gpt-5.3-codex": { input: 2.5, output: 10.0 },
+  "gpt-4.1": { input: 2.0, output: 8.0 },
+  "gpt-4o": { input: 2.5, output: 10.0 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gemini-3-pro-preview": { input: 2.0, output: 12.0 },
+  "gemini-3-flash-preview": { input: 0.5, output: 3.0 },
+  "gemini-2.0-flash": { input: 0.1, output: 0.4 },
+};
+
+const toInt = (value, fallbackValue = 0) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) ? parsed : fallbackValue;
+};
+
+const resolvePricing = (model) => {
+  const normalized = String(model || "").toLowerCase();
+  if (!normalized) return null;
+  const exact = kGlobalModelPricing[normalized];
+  if (exact) return exact;
+  const matchKey = Object.keys(kGlobalModelPricing).find((key) =>
+    normalized.includes(key),
+  );
+  return matchKey ? kGlobalModelPricing[matchKey] : null;
+};
+
+const resolvePerMillionRate = (rate, tokens) => {
+  if (typeof rate === "function") {
+    return Number(rate(toInt(tokens)));
+  }
+  return Number(rate || 0);
+};
+
+const deriveCostBreakdown = ({
+  inputTokens = 0,
+  outputTokens = 0,
+  cacheReadTokens = 0,
+  cacheWriteTokens = 0,
+  model = "",
+}) => {
+  const pricing = resolvePricing(model);
+  if (!pricing) {
+    return {
+      inputCost: 0,
+      outputCost: 0,
+      cacheReadCost: 0,
+      cacheWriteCost: 0,
+      totalCost: 0,
+      pricingFound: false,
+    };
+  }
+  const inputRate = resolvePerMillionRate(pricing.input, inputTokens);
+  const outputRate = resolvePerMillionRate(pricing.output, outputTokens);
+  const inputCost = (inputTokens / kTokensPerMillion) * inputRate;
+  const outputCost = (outputTokens / kTokensPerMillion) * outputRate;
+  const cacheReadCost = 0;
+  const cacheWriteRate = resolvePerMillionRate(pricing.input, cacheWriteTokens);
+  const cacheWriteCost = (cacheWriteTokens / kTokensPerMillion) * cacheWriteRate;
+  return {
+    inputCost,
+    outputCost,
+    cacheReadCost,
+    cacheWriteCost,
+    totalCost: inputCost + outputCost + cacheReadCost + cacheWriteCost,
+    pricingFound: true,
+  };
+};
+
+module.exports = {
+  kGlobalModelPricing,
+  deriveCostBreakdown,
+};

package/lib/server/db/usage/schema.js

@@ -0,0 +1,87 @@
+const safeAlterTable = (database, sql) => {
+  try {
+    database.exec(sql);
+  } catch (err) {
+    const message = String(err?.message || "").toLowerCase();
+    if (!message.includes("duplicate column name")) throw err;
+  }
+};
+
+const ensureSchema = (database) => {
+  database.exec("PRAGMA journal_mode=WAL;");
+  database.exec("PRAGMA synchronous=NORMAL;");
+  database.exec("PRAGMA busy_timeout=5000;");
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      session_id TEXT,
+      session_key TEXT,
+      run_id TEXT,
+      provider TEXT NOT NULL,
+      model TEXT NOT NULL,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+      total_tokens INTEGER NOT NULL DEFAULT 0
+    );
+  `);
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_usage_events_ts
+    ON usage_events(timestamp DESC);
+  `);
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_usage_events_session
+    ON usage_events(session_id);
+  `);
+  safeAlterTable(
+    database,
+    "ALTER TABLE usage_events ADD COLUMN session_key TEXT;",
+  );
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_usage_events_session_key
+    ON usage_events(session_key);
+  `);
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS usage_daily (
+      date TEXT NOT NULL,
+      model TEXT NOT NULL,
+      provider TEXT,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+      total_tokens INTEGER NOT NULL DEFAULT 0,
+      turn_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (date, model)
+    );
+  `);
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS tool_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      session_id TEXT,
+      session_key TEXT,
+      tool_name TEXT NOT NULL,
+      success INTEGER NOT NULL DEFAULT 1,
+      duration_ms INTEGER
+    );
+  `);
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_tool_events_session
+    ON tool_events(session_id);
+  `);
+  safeAlterTable(
+    database,
+    "ALTER TABLE tool_events ADD COLUMN session_key TEXT;",
+  );
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_tool_events_session_key
+    ON tool_events(session_key);
+  `);
+};
+
+module.exports = {
+  ensureSchema,
+};

package/lib/server/db/usage/sessions.js

@@ -0,0 +1,217 @@
+const {
+  kDefaultSessionLimit,
+  kMaxSessionLimit,
+  coerceInt,
+  clampInt,
+  getUsageMetricsFromEventRow,
+} = require("./shared");
+
+const getSessionsList = ({ database, limit = kDefaultSessionLimit } = {}) => {
+  const safeLimit = clampInt(limit, 1, kMaxSessionLimit, kDefaultSessionLimit);
+  const rows = database
+    .prepare(`
+      SELECT
+        COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) AS session_ref,
+        MAX(session_key) AS session_key,
+        MAX(session_id) AS session_id,
+        MIN(timestamp) AS first_activity_ms,
+        MAX(timestamp) AS last_activity_ms,
+        COUNT(*) AS turn_count,
+        SUM(input_tokens) AS input_tokens,
+        SUM(output_tokens) AS output_tokens,
+        SUM(cache_read_tokens) AS cache_read_tokens,
+        SUM(cache_write_tokens) AS cache_write_tokens,
+        SUM(total_tokens) AS total_tokens
+      FROM usage_events
+      WHERE COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) IS NOT NULL
+      GROUP BY session_ref
+      ORDER BY last_activity_ms DESC
+      LIMIT $limit
+    `)
+    .all({ $limit: safeLimit });
+  return rows.map((row) => {
+    const eventRows = database
+      .prepare(`
+        SELECT
+          model,
+          input_tokens,
+          output_tokens,
+          cache_read_tokens,
+          cache_write_tokens,
+          total_tokens
+        FROM usage_events
+        WHERE COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) = $sessionRef
+      `)
+      .all({ $sessionRef: row.session_ref });
+    let totalCost = 0;
+    const modelTokenTotals = new Map();
+    for (const eventRow of eventRows) {
+      const metrics = getUsageMetricsFromEventRow(eventRow);
+      totalCost += metrics.totalCost;
+      const model = String(eventRow.model || "");
+      modelTokenTotals.set(model, (modelTokenTotals.get(model) || 0) + metrics.totalTokens);
+    }
+    const dominantModel = Array.from(modelTokenTotals.entries())
+      .sort((a, b) => b[1] - a[1])[0]?.[0] || "";
+    return {
+      sessionId: row.session_ref,
+      sessionKey: String(row.session_key || ""),
+      rawSessionId: String(row.session_id || ""),
+      firstActivityMs: coerceInt(row.first_activity_ms),
+      lastActivityMs: coerceInt(row.last_activity_ms),
+      durationMs: Math.max(
+        0,
+        coerceInt(row.last_activity_ms) - coerceInt(row.first_activity_ms),
+      ),
+      turnCount: coerceInt(row.turn_count),
+      inputTokens: coerceInt(row.input_tokens),
+      outputTokens: coerceInt(row.output_tokens),
+      cacheReadTokens: coerceInt(row.cache_read_tokens),
+      cacheWriteTokens: coerceInt(row.cache_write_tokens),
+      totalTokens: coerceInt(row.total_tokens),
+      totalCost,
+      dominantModel,
+    };
+  });
+};
+
+const getSessionDetail = ({ database, sessionId }) => {
+  const safeSessionRef = String(sessionId || "").trim();
+  if (!safeSessionRef) return null;
+  const summaryRow = database
+    .prepare(`
+      SELECT
+        MAX(session_key) AS session_key,
+        MAX(session_id) AS session_id,
+        MIN(timestamp) AS first_activity_ms,
+        MAX(timestamp) AS last_activity_ms,
+        COUNT(*) AS turn_count,
+        SUM(input_tokens) AS input_tokens,
+        SUM(output_tokens) AS output_tokens,
+        SUM(cache_read_tokens) AS cache_read_tokens,
+        SUM(cache_write_tokens) AS cache_write_tokens,
+        SUM(total_tokens) AS total_tokens
+      FROM usage_events
+      WHERE COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) = $sessionRef
+    `)
+    .get({ $sessionRef: safeSessionRef });
+  if (!summaryRow || !coerceInt(summaryRow.turn_count)) return null;
+
+  const modelEvents = database
+    .prepare(`
+      SELECT
+        provider,
+        model,
+        input_tokens,
+        output_tokens,
+        cache_read_tokens,
+        cache_write_tokens,
+        total_tokens
+      FROM usage_events
+      WHERE COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) = $sessionRef
+    `)
+    .all({ $sessionRef: safeSessionRef });
+  const byProviderModel = new Map();
+  for (const eventRow of modelEvents) {
+    const provider = String(eventRow.provider || "unknown");
+    const model = String(eventRow.model || "unknown");
+    const mapKey = `${provider}\u0000${model}`;
+    if (!byProviderModel.has(mapKey)) {
+      byProviderModel.set(mapKey, {
+        provider,
+        model,
+        turnCount: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalTokens: 0,
+        totalCost: 0,
+        inputCost: 0,
+        outputCost: 0,
+        cacheReadCost: 0,
+        cacheWriteCost: 0,
+        pricingFound: false,
+      });
+    }
+    const aggregate = byProviderModel.get(mapKey);
+    const metrics = getUsageMetricsFromEventRow(eventRow);
+    aggregate.turnCount += 1;
+    aggregate.inputTokens += metrics.inputTokens;
+    aggregate.outputTokens += metrics.outputTokens;
+    aggregate.cacheReadTokens += metrics.cacheReadTokens;
+    aggregate.cacheWriteTokens += metrics.cacheWriteTokens;
+    aggregate.totalTokens += metrics.totalTokens;
+    aggregate.totalCost += metrics.totalCost;
+    aggregate.inputCost += metrics.inputCost;
+    aggregate.outputCost += metrics.outputCost;
+    aggregate.cacheReadCost += metrics.cacheReadCost;
+    aggregate.cacheWriteCost += metrics.cacheWriteCost;
+    aggregate.pricingFound = aggregate.pricingFound || metrics.pricingFound;
+  }
+  const modelRows = Array.from(byProviderModel.values()).sort(
+    (a, b) => b.totalTokens - a.totalTokens,
+  );
+
+  const toolRows = database
+    .prepare(`
+      SELECT
+        tool_name,
+        COUNT(*) AS call_count,
+        SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) AS success_count,
+        SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) AS error_count,
+        AVG(duration_ms) AS avg_duration_ms,
+        MIN(duration_ms) AS min_duration_ms,
+        MAX(duration_ms) AS max_duration_ms
+      FROM tool_events
+      WHERE COALESCE(NULLIF(session_key, ''), NULLIF(session_id, '')) = $sessionRef
+      GROUP BY tool_name
+      ORDER BY call_count DESC
+    `)
+    .all({ $sessionRef: safeSessionRef })
+    .map((row) => {
+      const callCount = coerceInt(row.call_count);
+      const successCount = coerceInt(row.success_count);
+      const errorCount = coerceInt(row.error_count);
+      return {
+        toolName: row.tool_name,
+        callCount,
+        successCount,
+        errorCount,
+        errorRate: callCount > 0 ? errorCount / callCount : 0,
+        avgDurationMs: Number(row.avg_duration_ms || 0),
+        minDurationMs: coerceInt(row.min_duration_ms),
+        maxDurationMs: coerceInt(row.max_duration_ms),
+      };
+    });
+
+  const firstActivityMs = coerceInt(summaryRow.first_activity_ms);
+  const lastActivityMs = coerceInt(summaryRow.last_activity_ms);
+  const totalCost = modelRows.reduce(
+    (sum, modelRow) => sum + Number(modelRow.totalCost || 0),
+    0,
+  );
+
+  return {
+    sessionId: safeSessionRef,
+    sessionKey: String(summaryRow.session_key || ""),
+    rawSessionId: String(summaryRow.session_id || ""),
+    firstActivityMs,
+    lastActivityMs,
+    durationMs: Math.max(0, lastActivityMs - firstActivityMs),
+    turnCount: coerceInt(summaryRow.turn_count),
+    inputTokens: coerceInt(summaryRow.input_tokens),
+    outputTokens: coerceInt(summaryRow.output_tokens),
+    cacheReadTokens: coerceInt(summaryRow.cache_read_tokens),
+    cacheWriteTokens: coerceInt(summaryRow.cache_write_tokens),
+    totalTokens: coerceInt(summaryRow.total_tokens),
+    totalCost,
+    modelBreakdown: modelRows,
+    toolUsage: toolRows,
+  };
+};
+
+module.exports = {
+  getSessionsList,
+  getSessionDetail,
+};

package/lib/server/db/usage/shared.js

@@ -0,0 +1,139 @@
+const { deriveCostBreakdown } = require("./pricing");
+
+const kDefaultSessionLimit = 50;
+const kMaxSessionLimit = 200;
+const kDefaultDays = 30;
+const kDefaultMaxPoints = 100;
+const kMaxMaxPoints = 1000;
+const kDayMs = 24 * 60 * 60 * 1000;
+const kUtcTimeZone = "UTC";
+const kDayKeyFormatterCache = new Map();
+
+const coerceInt = (value, fallbackValue = 0) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) ? parsed : fallbackValue;
+};
+
+const clampInt = (value, minValue, maxValue, fallbackValue) =>
+  Math.min(maxValue, Math.max(minValue, coerceInt(value, fallbackValue)));
+
+const normalizeTimeZone = (value) => {
+  const raw = String(value || "").trim();
+  if (!raw) return kUtcTimeZone;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: raw });
+    return raw;
+  } catch {
+    return kUtcTimeZone;
+  }
+};
+
+const getDayKeyFormatter = (timeZone) => {
+  if (kDayKeyFormatterCache.has(timeZone)) {
+    return kDayKeyFormatterCache.get(timeZone);
+  }
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+  kDayKeyFormatterCache.set(timeZone, formatter);
+  return formatter;
+};
+
+const toTimeZoneDayKey = (timestampMs, timeZone) => {
+  const parts = getDayKeyFormatter(timeZone).formatToParts(new Date(timestampMs));
+  const year = parts.find((part) => part.type === "year")?.value || "0000";
+  const month = parts.find((part) => part.type === "month")?.value || "01";
+  const day = parts.find((part) => part.type === "day")?.value || "01";
+  return `${year}-${month}-${day}`;
+};
+
+const toDayKey = (timestampMs) => new Date(timestampMs).toISOString().slice(0, 10);
+
+const getPeriodRange = (days, timeZone = kUtcTimeZone) => {
+  const now = Date.now();
+  const safeDays = clampInt(days, 1, 3650, kDefaultDays);
+  const startMs = now - safeDays * kDayMs;
+  const normalizedTimeZone = normalizeTimeZone(timeZone);
+  const startDay = normalizedTimeZone === kUtcTimeZone
+    ? toDayKey(startMs)
+    : toTimeZoneDayKey(startMs, normalizedTimeZone);
+  return { now, safeDays, startDay, timeZone: normalizedTimeZone };
+};
+
+const getUsageMetricsFromEventRow = (row) => {
+  const inputTokens = coerceInt(row.input_tokens);
+  const outputTokens = coerceInt(row.output_tokens);
+  const cacheReadTokens = coerceInt(row.cache_read_tokens);
+  const cacheWriteTokens = coerceInt(row.cache_write_tokens);
+  const totalTokens =
+    coerceInt(row.total_tokens) ||
+    inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens;
+  const cost = deriveCostBreakdown({
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    model: row.model,
+  });
+  return {
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    totalTokens,
+    ...cost,
+  };
+};
+
+const parseAgentAndSourceFromSessionRef = (sessionRef) => {
+  const raw = String(sessionRef || "").trim();
+  if (!raw) {
+    return { agent: "unknown", source: "chat" };
+  }
+  const parts = raw.split(":");
+  const agent =
+    parts[0] === "agent" && String(parts[1] || "").trim()
+      ? String(parts[1] || "").trim()
+      : "unknown";
+  const source = parts.includes("hook")
+    ? "hooks"
+    : parts.includes("cron")
+      ? "cron"
+      : "chat";
+  return { agent, source };
+};
+
+const downsamplePoints = (points, maxPoints) => {
+  if (points.length <= maxPoints) return points;
+  const stride = Math.ceil(points.length / maxPoints);
+  const sampled = [];
+  for (let index = 0; index < points.length; index += stride) {
+    sampled.push(points[index]);
+  }
+  const lastPoint = points[points.length - 1];
+  if (sampled[sampled.length - 1]?.timestamp !== lastPoint.timestamp) {
+    sampled.push(lastPoint);
+  }
+  return sampled;
+};
+
+module.exports = {
+  kDefaultSessionLimit,
+  kMaxSessionLimit,
+  kDefaultDays,
+  kDefaultMaxPoints,
+  kMaxMaxPoints,
+  kDayMs,
+  kUtcTimeZone,
+  coerceInt,
+  clampInt,
+  toTimeZoneDayKey,
+  toDayKey,
+  getPeriodRange,
+  getUsageMetricsFromEventRow,
+  parseAgentAndSourceFromSessionRef,
+  downsamplePoints,
+};