rol-websocket-channel 1.0.0

package/src/admin/methods/usage.ts

@@ -0,0 +1,1491 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+
+import { getPluginRuntime } from '../../../index.js';
+import { pathExists, readJsonFile } from '../lib/fs.ts';
+import { resolveSessionFile } from './sessions.ts';
+import type { JsonValue, MethodHandler, MethodContext } from '../types.ts';
+
+interface SessionsIndexEntry {
+  sessionId?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  estimatedCostUsd?: number;
+  runtimeMs?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  origin?: {
+    label?: string;
+    provider?: string;
+    chatType?: string;
+  };
+}
+
+type SessionsIndex = Record<string, SessionsIndexEntry>;
+
+interface OpenClawGatewayConfig {
+  gateway?: {
+    port?: number;
+    bind?: string;
+    auth?: {
+      token?: string;
+      mode?: string;
+    };
+  };
+}
+
+interface UsageAccumulator {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  totalCostUsd: number;
+  toolCalls: number;
+  errors: number;
+  messages: number;
+  sessions: number;
+}
+
+interface UsageQuery {
+  from?: string;
+  to?: string;
+  timezone?: string;
+  basis?: string;
+  agent?: string[];
+  channel?: string[];
+  provider?: string[];
+  model?: string[];
+  tool?: string[];
+  sessionIds?: string[];
+}
+
+interface SessionUsageEvent {
+  ts: number;
+  sessionId: string;
+  agent: string;
+  channel: string;
+  provider: string;
+  model: string;
+  toolName: string | null;
+  messageRole: string | null;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  totalCostUsd: number;
+  isError: boolean;
+  isToolCall: boolean;
+  toolCallsCount: number;
+  messageCount: number;
+  usageMessageCount: number;
+}
+
+interface UsageBucketState {
+  usage: UsageSummaryBucket;
+  sessionIds: Set<string>;
+}
+
+interface SessionSummaryRecord {
+  sessionId: string;
+  totals: UsageSummaryBucket;
+  timestampMs: number | null;
+  runtimeMs: number | null;
+  provider: string;
+  model: string;
+  agent: string;
+  channel: string;
+}
+
+interface UsageSummaryBucket extends UsageAccumulator {
+  cachedTokens: number;
+  promptTokens: number;
+  completionTokens: number;
+}
+
+interface UsageSourceMeta {
+  source: 'gateway' | 'local_fallback';
+  usedLiveSnapshot: boolean;
+  usedTranscriptFallback: boolean;
+  usedDiagnostics: boolean;
+}
+
+interface UsageSourceResult {
+  events: SessionUsageEvent[];
+  summaryRecords: SessionSummaryRecord[];
+  meta: UsageSourceMeta;
+}
+
+interface GatewayUsageClient {
+  call(method: string, params: Record<string, JsonValue>): Promise<unknown>;
+}
+
+interface GatewayUsageMethodSet {
+  summary: string;
+  timeseries: string;
+  logs: string;
+}
+
+const GATEWAY_USAGE_METHODS: GatewayUsageMethodSet = {
+  summary: 'sessions.usage',
+  timeseries: 'sessions.usage.timeseries',
+  logs: 'sessions.usage.logs'
+};
+
+function blankUsage(): UsageSummaryBucket {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    totalCostUsd: 0,
+    toolCalls: 0,
+    errors: 0,
+    messages: 0,
+    sessions: 0,
+    cachedTokens: 0,
+    promptTokens: 0,
+    completionTokens: 0
+  };
+}
+
+export const getUsageSummary: MethodHandler = async (_params, context): Promise<JsonValue> => {
+  const repo = await buildUsageRepo(context);
+  return repo.getPageSummary({});
+};
+
+export const getUsagePageSummary: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const repo = await buildUsageRepo(context);
+  return repo.getPageSummary(readUsageQuery(params));
+};
+
+export const getUsageTimeseries: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const repo = await buildUsageRepo(context);
+  const query = readUsageQuery(params);
+  const granularity = isObject(params) && typeof params.granularity === 'string' ? params.granularity : 'day';
+  return repo.getTimeseries(query, granularity);
+};
+
+export const getUsageBreakdown: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const repo = await buildUsageRepo(context);
+  const query = readUsageQuery(params);
+  const objectParams = isObject(params) ? params : {};
+  const dimension = typeof objectParams.dimension === 'string' ? objectParams.dimension : 'model';
+  const limit = typeof objectParams.limit === 'number' ? objectParams.limit : 20;
+  const sortBy = typeof objectParams.sortBy === 'string' ? objectParams.sortBy : 'totalTokens';
+  const order = objectParams.order === 'asc' ? 'asc' : 'desc';
+  return repo.getBreakdown(query, dimension, limit, sortBy, order);
+};
+
+async function buildUsageRepo(context: MethodContext) {
+  const selectedSource = await getUsageSource(context);
+  const events = dedupeEvents(selectedSource.events);
+  const summaryRecords = selectedSource.summaryRecords;
+
+  return {
+    getPageSummary(query: UsageQuery) {
+      const filtered = filterEvents(events, query);
+      const filteredSummaries = filterSessionSummaries(summaryRecords, query);
+      const totals = aggregateSummary(filteredSummaries);
+      return {
+        window: buildWindow(query),
+        totals: buildSummaryMetrics(totals, filteredSummaries),
+        topModels: buildSummaryRankedList(filteredSummaries, 'model', 10),
+        topProviders: buildSummaryRankedList(filteredSummaries, 'provider', 10),
+        topTools: buildToolRankedList(filtered, 10),
+        topAgents: buildSummaryRankedList(filteredSummaries, 'agent', 10),
+        topChannels: buildSummaryRankedList(filteredSummaries, 'channel', 10),
+        sessions: buildSessionRows(filteredSummaries),
+        meta: {
+          sessionsScanned: new Set([
+            ...filtered.map((event) => event.sessionId),
+            ...filteredSummaries.map((record) => record.sessionId)
+          ]).size,
+          source: selectedSource.meta.source,
+          usedLiveSnapshot: selectedSource.meta.usedLiveSnapshot,
+          usedTranscriptFallback: selectedSource.meta.usedTranscriptFallback,
+          usedDiagnostics: selectedSource.meta.usedDiagnostics,
+          generatedAt: new Date().toISOString()
+        }
+      };
+    },
+
+    getTimeseries(query: UsageQuery, granularity: string) {
+      const filtered = filterEvents(events, query);
+      const filteredSummaries = filterSessionSummaries(summaryRecords, query);
+      const series = aggregateTimeseries(filtered, filteredSummaries, granularity);
+      return {
+        window: {
+          ...buildWindow(query),
+          granularity
+        },
+        series,
+        meta: {
+          sessionsScanned: new Set([
+            ...filtered.map((event) => event.sessionId),
+            ...filteredSummaries.map((record) => record.sessionId)
+          ]).size,
+          source: selectedSource.meta.source,
+          bucketCount: series.length,
+          usedTranscriptFallback: selectedSource.meta.usedTranscriptFallback,
+          generatedAt: new Date().toISOString()
+        }
+      };
+    },
+
+    getBreakdown(query: UsageQuery, dimension: string, limit: number, sortBy: string, order: 'asc' | 'desc') {
+      const filtered = filterEvents(events, query);
+      const filteredSummaries = filterSessionSummaries(summaryRecords, query);
+      const total = aggregateSummary(filteredSummaries);
+      const rows = aggregateBreakdown(filtered, filteredSummaries, dimension, total.totalTokens, limit, sortBy, order);
+
+      return {
+        window: {
+          ...buildWindow(query),
+          dimension
+        },
+        rows,
+        meta: {
+          limit,
+          sortBy,
+          order,
+          sessionsScanned: new Set([
+            ...filtered.map((event) => event.sessionId),
+            ...filteredSummaries.map((record) => record.sessionId)
+          ]).size,
+          source: selectedSource.meta.source,
+          generatedAt: new Date().toISOString()
+        }
+      };
+    }
+  };
+}
+
+async function getUsageSource(context: MethodContext): Promise<UsageSourceResult> {
+  return await readLocalUsageSource(context);
+}
+
+async function readGatewayUsageSource(context: MethodContext): Promise<UsageSourceResult | null> {
+  const client = await createGatewayUsageClient(context);
+  if (!client) {
+    return null;
+  }
+
+  try {
+    const [summaryPayload, logsPayload] = await Promise.all([
+      safeGatewayCall(client, GATEWAY_USAGE_METHODS.summary, {}),
+      safeGatewayCall(client, GATEWAY_USAGE_METHODS.logs, {})
+    ]);
+
+    const summaryRecords = normalizeGatewaySummaryPayload(summaryPayload);
+    const events = dedupeEvents(normalizeGatewayUsageLogs(logsPayload));
+
+    if (summaryRecords.length === 0 && events.length === 0) {
+      return null;
+    }
+
+    return {
+      events,
+      summaryRecords,
+      meta: {
+        source: 'gateway',
+        usedLiveSnapshot: true,
+        usedTranscriptFallback: false,
+        usedDiagnostics: false
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function createGatewayUsageClient(_context: MethodContext): Promise<GatewayUsageClient | null> {
+  const runtime = getPluginRuntime();
+  console.log('[usage][gateway] runtime keys:', Object.keys(runtime ?? {}));
+  console.log('[usage][gateway] runtime adapter probing unavailable, using ws client');
+
+  const configPath = path.join(_context.openclawRoot, 'openclaw.json');
+  if (!(await pathExists(configPath))) {
+    console.log('[usage][gateway] openclaw.json not found');
+    return null;
+  }
+
+  const config = await readJsonFile<OpenClawGatewayConfig>(configPath);
+  const port = typeof config.gateway?.port === 'number' ? config.gateway.port : 18789;
+  const token = typeof config.gateway?.auth?.token === 'string' ? config.gateway.auth.token : null;
+  if (!token) {
+    console.log('[usage][gateway] gateway auth token missing');
+    return null;
+  }
+
+  if (typeof globalThis.WebSocket !== 'function') {
+    console.log('[usage][gateway] global WebSocket unavailable');
+    return null;
+  }
+
+  const url = `ws://127.0.0.1:${port}`;
+  try {
+    return await createWebSocketGatewayUsageClient(url, token);
+  } catch (error) {
+    console.log('[usage][gateway] ws client init failed:', error);
+    return null;
+  }
+}
+
+async function safeGatewayCall(
+  client: GatewayUsageClient,
+  method: string,
+  params: Record<string, JsonValue>
+): Promise<unknown | null> {
+  try {
+    return await client.call(method, params);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGatewaySummaryPayload(payload: unknown): SessionSummaryRecord[] {
+  if (!isObjectRecord(payload)) {
+    return [];
+  }
+
+  const rows = Array.isArray(payload.rows)
+    ? payload.rows
+    : Array.isArray(payload.sessions)
+      ? payload.sessions
+      : [];
+
+  const records: SessionSummaryRecord[] = [];
+  for (const row of rows) {
+    if (!isObjectRecord(row)) {
+      continue;
+    }
+
+    const sessionId = asString(row.sessionId) ?? asString(row.id);
+    if (!sessionId) {
+      continue;
+    }
+
+    const totals = blankUsage();
+    totals.input = asNumber(row.inputTokens) ?? asNumber(row.input) ?? 0;
+    totals.output = asNumber(row.outputTokens) ?? asNumber(row.output) ?? 0;
+    totals.cacheRead = asNumber(row.cacheReadTokens) ?? asNumber(row.cacheRead) ?? 0;
+    totals.cacheWrite = asNumber(row.cacheWriteTokens) ?? asNumber(row.cacheWrite) ?? 0;
+    totals.cachedTokens = totals.cacheRead;
+    totals.promptTokens = totals.input;
+    totals.completionTokens = totals.output;
+    totals.totalTokens =
+      asNumber(row.totalTokens)
+      ?? asNumber(row.tokens)
+      ?? totals.input + totals.output + totals.cacheRead + totals.cacheWrite;
+    totals.totalCostUsd = asNumber(row.totalCostUsd) ?? asNumber(row.costUsd) ?? 0;
+    totals.toolCalls = asNumber(row.toolCalls) ?? 0;
+    totals.errors = asNumber(row.errors) ?? 0;
+    totals.messages = asNumber(row.messages) ?? 0;
+    totals.sessions = 1;
+
+    records.push({
+      sessionId,
+      totals,
+      timestampMs: parseTimestamp(row.timestamp ?? row.updatedAt),
+      runtimeMs: asNumber(row.runtimeMs) ?? null,
+      provider: asString(row.provider) ?? 'unknown',
+      model: asString(row.model) ?? 'unknown',
+      agent: asString(row.agent) ?? 'main',
+      channel: asString(row.channel) ?? 'unknown'
+    });
+  }
+
+  return records;
+}
+
+function unwrapGatewayResult(result: unknown): unknown {
+  if (!isObjectRecord(result)) {
+    return result;
+  }
+
+  if ('payload' in result) {
+    return result.payload;
+  }
+
+  if ('result' in result) {
+    return result.result;
+  }
+
+  if ('ok' in result && result.ok === true && 'data' in result) {
+    return result.data;
+  }
+
+  return result;
+}
+
+async function createWebSocketGatewayUsageClient(
+  url: string,
+  token: string
+): Promise<GatewayUsageClient> {
+  const ws = new WebSocket(url);
+  const pending = new Map<string, { resolve: (value: unknown) => void; reject: (reason?: unknown) => void }>();
+  let requestCounter = 0;
+  let connectNonce: string | null = null;
+  let handshakeResolved = false;
+  let handshakeRejected = false;
+
+  const connectPromise = new Promise<void>((resolve, reject) => {
+    const rejectOnce = (reason: unknown) => {
+      if (handshakeResolved || handshakeRejected) {
+        return;
+      }
+      handshakeRejected = true;
+      reject(reason);
+    };
+
+    const resolveOnce = () => {
+      if (handshakeResolved || handshakeRejected) {
+        return;
+      }
+      handshakeResolved = true;
+      resolve();
+    };
+
+    ws.onopen = () => {
+      console.log('[usage][gateway] ws connected:', url);
+    };
+
+    ws.onerror = (event) => {
+      rejectOnce(new Error(`Gateway websocket error: ${String(event.type ?? 'unknown')}`));
+    };
+
+    ws.onclose = (event) => {
+      const reason = event.reason || 'gateway websocket closed';
+      const error = new Error(`Gateway websocket closed (${event.code}): ${reason}`);
+      rejectOnce(error);
+      for (const entry of pending.values()) {
+        entry.reject(error);
+      }
+      pending.clear();
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(String(event.data ?? '')) as Record<string, any>;
+        if (message.type === 'event' && message.event === 'connect.challenge') {
+          const payload = isObjectRecord(message.payload) ? message.payload : {};
+          connectNonce = typeof payload.nonce === 'string' ? payload.nonce : null;
+          if (!connectNonce) {
+            rejectOnce(new Error('gateway connect challenge missing nonce'));
+            return;
+          }
+
+          ws.send(JSON.stringify(buildGatewayConnectFrame(token)));
+          return;
+        }
+
+        if (message.type === 'res') {
+          const id = typeof message.id === 'string' ? message.id : null;
+          if (id === '__connect__') {
+            if (message.ok === true) {
+              resolveOnce();
+            } else {
+              rejectOnce(new Error(`Gateway connect failed: ${message.error?.message ?? 'unknown error'}`));
+            }
+            return;
+          }
+
+          if (!id) {
+            return;
+          }
+
+          const entry = pending.get(id);
+          if (!entry) {
+            return;
+          }
+          pending.delete(id);
+
+          if (message.ok === true) {
+            entry.resolve(message.payload);
+          } else {
+            entry.reject(new Error(message.error?.message ?? 'Gateway request failed'));
+          }
+        }
+      } catch (error) {
+        rejectOnce(error);
+      }
+    };
+  });
+
+  await withTimeout(connectPromise, 5000, 'Gateway connect timeout');
+
+  return {
+    async call(method: string, params: Record<string, JsonValue>): Promise<unknown> {
+      const id = `usage-${++requestCounter}`;
+      const promise = new Promise<unknown>((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+      });
+
+      ws.send(JSON.stringify({
+        type: 'req',
+        id,
+        method,
+        params
+      }));
+
+      const result = await withTimeout(promise, 10000, `Gateway request timeout for ${method}`);
+      console.log('[usage][gateway] ws call succeeded for method:', method);
+      return unwrapGatewayResult(result);
+    }
+  };
+}
+
+function buildGatewayConnectFrame(token: string) {
+  return {
+    type: 'req',
+    id: '__connect__',
+    method: 'connect',
+    params: {
+      minProtocol: 3,
+      maxProtocol: 3,
+      client: {
+        id: 'openclaw-control-ui',
+        version: 'rol-websocket-channel',
+        platform: 'node',
+        mode: 'webchat',
+        instanceId: 'rol-websocket-channel-usage'
+      },
+      role: 'operator',
+      scopes: [
+        'operator.admin',
+        'operator.read',
+        'operator.write',
+        'operator.approvals',
+        'operator.pairing'
+      ],
+      caps: ['tool-events'],
+      auth: {
+        token
+      },
+      userAgent: 'rol-websocket-channel',
+      locale: 'en-US'
+    }
+  };
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(message)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
+function normalizeGatewayUsageLogs(payload: unknown): SessionUsageEvent[] {
+  if (!isObjectRecord(payload)) {
+    return [];
+  }
+
+  const rows = Array.isArray(payload.rows)
+    ? payload.rows
+    : Array.isArray(payload.logs)
+      ? payload.logs
+      : Array.isArray(payload.events)
+        ? payload.events
+        : [];
+
+  const events: SessionUsageEvent[] = [];
+  for (const row of rows) {
+    if (!isObjectRecord(row)) {
+      continue;
+    }
+
+    const ts = parseTimestamp(row.ts ?? row.timestamp ?? row.createdAt);
+    const sessionId = asString(row.sessionId) ?? asString(row.id);
+    if (!sessionId || ts === null) {
+      continue;
+    }
+
+    const input = asNumber(row.inputTokens) ?? asNumber(row.input) ?? 0;
+    const output = asNumber(row.outputTokens) ?? asNumber(row.output) ?? 0;
+    const cacheRead = asNumber(row.cacheReadTokens) ?? asNumber(row.cacheRead) ?? 0;
+    const cacheWrite = asNumber(row.cacheWriteTokens) ?? asNumber(row.cacheWrite) ?? 0;
+
+    events.push({
+      ts,
+      sessionId,
+      agent: asString(row.agent) ?? 'main',
+      channel: asString(row.channel) ?? 'unknown',
+      provider: asString(row.provider) ?? 'unknown',
+      model: asString(row.model) ?? 'unknown',
+      toolName: asString(row.toolName) ?? null,
+      messageRole: asString(row.role) ?? null,
+      input,
+      output,
+      cacheRead,
+      cacheWrite,
+      totalTokens:
+        asNumber(row.totalTokens)
+        ?? asNumber(row.tokens)
+        ?? input + output + cacheRead + cacheWrite,
+      totalCostUsd: asNumber(row.totalCostUsd) ?? asNumber(row.costUsd) ?? 0,
+      isError: Boolean(row.isError ?? row.errorCount ?? row.error),
+      isToolCall: Boolean(row.isToolCall ?? row.toolCalls),
+      toolCallsCount: asNumber(row.toolCalls) ?? 0,
+      messageCount: asNumber(row.messages) ?? 1,
+      usageMessageCount: asNumber(row.usageMessages) ?? 1
+    });
+  }
+
+  return events;
+}
+
+async function readLocalUsageSource(context: MethodContext): Promise<UsageSourceResult> {
+  const sessionMetadataById = new Map<string, { sessionKey: string; entry: SessionsIndexEntry }>();
+  const summaryRecordById = new Map<string, SessionSummaryRecord>();
+  await loadSessionMetadata(context.openclawRoot, sessionMetadataById);
+
+  const events: SessionUsageEvent[] = [];
+  const sessionFiles = await discoverSessionFiles(context.openclawRoot);
+
+  for (const sessionFile of sessionFiles) {
+    const sessionId = path.basename(sessionFile, '.jsonl');
+    const metadata = sessionMetadataById.get(sessionId);
+    const agentName = extractAgentNameFromPath(sessionFile);
+    const sessionKey = metadata?.sessionKey ?? `agent:${agentName}:${agentName}`;
+    const entry = metadata?.entry ?? {};
+    const sessionEvents = await readSessionEvents(sessionFile, sessionKey, {
+      ...entry,
+      sessionId
+    });
+    events.push(...sessionEvents);
+    summaryRecordById.set(sessionId, buildSessionSummaryFromEvents(sessionEvents, sessionKey, {
+      ...entry,
+      sessionId
+    }));
+  }
+
+  for (const [sessionId, metadata] of sessionMetadataById.entries()) {
+    if (summaryRecordById.has(sessionId)) {
+      continue;
+    }
+    summaryRecordById.set(sessionId, buildSessionSummaryRecord(metadata.sessionKey, metadata.entry));
+  }
+
+  return {
+    events,
+    summaryRecords: [...summaryRecordById.values()],
+    meta: {
+      source: 'local_fallback',
+      usedLiveSnapshot: false,
+      usedTranscriptFallback: true,
+      usedDiagnostics: false
+    }
+  };
+}
+
+async function loadSessionMetadata(
+  openclawRoot: string,
+  target: Map<string, { sessionKey: string; entry: SessionsIndexEntry }>
+): Promise<void> {
+  const agentsRoot = path.join(openclawRoot, 'agents');
+  if (!(await pathExists(agentsRoot))) {
+    return;
+  }
+
+  const agentEntries = await fs.readdir(agentsRoot, { withFileTypes: true });
+  for (const agentEntry of agentEntries) {
+    if (!agentEntry.isDirectory()) {
+      continue;
+    }
+
+    const sessionsPath = path.join(agentsRoot, agentEntry.name, 'sessions', 'sessions.json');
+    if (!(await pathExists(sessionsPath))) {
+      continue;
+    }
+
+    const sessions = await readJsonFile<SessionsIndex>(sessionsPath);
+    for (const [sessionKey, entry] of Object.entries(sessions)) {
+      if (entry.sessionId) {
+        target.set(entry.sessionId, { sessionKey, entry });
+      }
+    }
+  }
+}
+
+function dedupeEvents(events: SessionUsageEvent[]): SessionUsageEvent[] {
+  const seen = new Set<string>();
+  const deduped: SessionUsageEvent[] = [];
+
+  for (const event of events) {
+    const key = [
+      event.sessionId,
+      event.ts,
+      event.provider,
+      event.model,
+      event.messageRole ?? 'none',
+      event.toolName ?? 'none',
+      event.input,
+      event.output,
+      event.cacheRead,
+      event.cacheWrite,
+      event.totalTokens,
+      event.totalCostUsd
+    ].join(':');
+
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    deduped.push(event);
+  }
+
+  return deduped;
+}
+
+function aggregateSummary(records: SessionSummaryRecord[]): UsageSummaryBucket {
+  return summarizeSessionRecords(records);
+}
+
+function aggregateTimeseries(
+  events: SessionUsageEvent[],
+  records: SessionSummaryRecord[],
+  granularity: string
+) {
+  const buckets = new Map<string, UsageBucketState>();
+  const sessionsWithEvents = new Set<string>();
+
+  for (const event of events) {
+    const bucketTs = bucketTimestamp(event.ts, granularity);
+    const key = new Date(bucketTs).toISOString();
+    const bucket = buckets.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    applyEvent(bucket.usage, event);
+    bucket.sessionIds.add(event.sessionId);
+    sessionsWithEvents.add(event.sessionId);
+    buckets.set(key, bucket);
+  }
+
+  for (const record of records) {
+    if (sessionsWithEvents.has(record.sessionId)) {
+      continue;
+    }
+    if (record.timestampMs === null) {
+      continue;
+    }
+    const bucketTs = bucketTimestamp(record.timestampMs, granularity);
+    const key = new Date(bucketTs).toISOString();
+    const bucket = buckets.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    mergeUsageWindows(bucket.usage, record.totals);
+    bucket.sessionIds.add(record.sessionId);
+    buckets.set(key, bucket);
+  }
+
+  return [...buckets.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([ts, bucket]) => ({
+      ts,
+      messages: bucket.usage.messages,
+      sessions: bucket.sessionIds.size,
+      inputTokens: bucket.usage.input,
+      outputTokens: bucket.usage.output,
+      cacheReadTokens: bucket.usage.cacheRead,
+      cacheWriteTokens: bucket.usage.cacheWrite,
+      totalTokens: bucket.usage.totalTokens,
+      totalCostUsd: bucket.usage.totalCostUsd,
+      toolCalls: bucket.usage.toolCalls,
+      errors: bucket.usage.errors,
+      cachedTokens: bucket.usage.cachedTokens,
+      avgTokensPerMessage: bucket.usage.messages > 0 ? bucket.usage.totalTokens / bucket.usage.messages : 0,
+      throughputTokPerMin: computeThroughput(bucket.usage.totalTokens, granularity)
+    }));
+}
+
+function aggregateBreakdown(
+  events: SessionUsageEvent[],
+  records: SessionSummaryRecord[],
+  dimension: string,
+  totalTokens: number,
+  limit: number,
+  sortBy: string,
+  order: 'asc' | 'desc'
+) {
+  return dimension === 'tool'
+    ? buildToolBreakdown(events, totalTokens, limit, sortBy, order)
+    : buildSummaryBreakdown(records, dimension, totalTokens, limit, sortBy, order);
+}
+
+async function readSessionEvents(
+  filePath: string,
+  sessionKey: string,
+  entry: SessionsIndexEntry
+): Promise<SessionUsageEvent[]> {
+  const events: SessionUsageEvent[] = [];
+  const stream = await fs.open(filePath, 'r');
+  let currentProvider = '';
+  let currentModel = '';
+  const agent = extractAgentName(sessionKey);
+  const channel = entry.origin?.label ?? entry.origin?.provider ?? 'unknown';
+
+  try {
+    const rl = readline.createInterface({
+      input: stream.createReadStream(),
+      crlfDelay: Infinity
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const parsed = JSON.parse(line) as Record<string, any>;
+        const normalized = normalizeUsageRecord(parsed, {
+          sessionId: entry.sessionId ?? 'unknown',
+          sessionKey,
+          agent,
+          channel,
+          currentProvider,
+          currentModel
+        });
+
+        currentProvider = normalized.currentProvider;
+        currentModel = normalized.currentModel;
+
+        if (normalized.event) {
+          events.push(normalized.event);
+        }
+      } catch {
+        continue;
+      }
+    }
+  } finally {
+    await stream.close();
+  }
+
+  return events;
+}
+
+function normalizeUsageRecord(
+  parsed: Record<string, any>,
+  context: {
+    sessionId: string;
+    sessionKey: string;
+    agent: string;
+    channel: string;
+    currentProvider: string;
+    currentModel: string;
+  }
+): {
+  event: SessionUsageEvent | null;
+  currentProvider: string;
+  currentModel: string;
+} {
+  let currentProvider = context.currentProvider;
+  let currentModel = context.currentModel;
+
+  if (parsed.type === 'model_change') {
+    currentProvider = typeof parsed.provider === 'string' ? parsed.provider : currentProvider;
+    currentModel = typeof parsed.modelId === 'string' ? parsed.modelId : currentModel;
+  }
+
+  const message = parsed.message as Record<string, any> | undefined;
+  const usage = message?.usage as Record<string, any> | undefined;
+
+  if (typeof message?.provider === 'string') {
+    currentProvider = message.provider;
+  }
+
+  if (typeof message?.model === 'string') {
+    currentModel = message.model;
+  }
+
+  const timestamp = typeof parsed.timestamp === 'string' ? Date.parse(parsed.timestamp) : Number.NaN;
+  if (!Number.isFinite(timestamp)) {
+    return { event: null, currentProvider, currentModel };
+  }
+
+  const content = Array.isArray(message?.content) ? message.content : [];
+  const toolCalls = content.filter((item: any) => item?.type === 'toolCall');
+  const cost = isObject(usage?.cost) ? usage.cost : {};
+  const role = typeof message?.role === 'string' ? message.role : null;
+  const messageCount = role === 'user' || role === 'assistant' ? 1 : 0;
+  const usageMessageCount = role === 'assistant' && usage ? 1 : 0;
+  const toolCallsCount = toolCalls.length;
+
+  if (!usage && messageCount === 0 && toolCallsCount === 0) {
+    return { event: null, currentProvider, currentModel };
+  }
+
+  return {
+    currentProvider,
+    currentModel,
+    event: {
+      ts: timestamp,
+      sessionId: context.sessionId,
+      agent: context.agent,
+      channel: context.channel,
+      provider: currentProvider || 'unknown',
+      model: currentModel || 'unknown',
+      toolName: toolCallsCount > 0 ? String(toolCalls[0].name ?? 'unknown') : null,
+      messageRole: role,
+      input: numeric(usage?.input),
+      output: numeric(usage?.output),
+      cacheRead: numeric(usage?.cacheRead),
+      cacheWrite: numeric(usage?.cacheWrite),
+      totalTokens: numeric(usage?.totalTokens),
+      totalCostUsd: numeric(cost.total),
+      isError: typeof message?.errorMessage === 'string' || parsed.stopReason === 'error',
+      isToolCall: toolCallsCount > 0,
+      toolCallsCount,
+      messageCount,
+      usageMessageCount
+    }
+  };
+}
+
+async function discoverSessionFiles(openclawRoot: string): Promise<string[]> {
+  const agentsRoot = path.join(openclawRoot, 'agents');
+  if (!(await pathExists(agentsRoot))) {
+    return [];
+  }
+
+  const sessionFiles: string[] = [];
+  const agentEntries = await fs.readdir(agentsRoot, { withFileTypes: true });
+
+  for (const agentEntry of agentEntries) {
+    if (!agentEntry.isDirectory()) {
+      continue;
+    }
+
+    const sessionsDir = path.join(agentsRoot, agentEntry.name, 'sessions');
+    if (!(await pathExists(sessionsDir))) {
+      continue;
+    }
+
+    const entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!(entry.name.endsWith('.jsonl') || entry.name.includes('.jsonl.reset.'))) {
+        continue;
+      }
+      sessionFiles.push(path.join(sessionsDir, entry.name));
+    }
+  }
+
+  return sessionFiles;
+}
+
+function filterSessionSummaries(records: SessionSummaryRecord[], query: UsageQuery): SessionSummaryRecord[] {
+  const from = query.from ? Date.parse(query.from) : Number.NEGATIVE_INFINITY;
+  const to = query.to ? Date.parse(query.to) : Number.POSITIVE_INFINITY;
+
+  return records.filter((record) => {
+    if (record.timestampMs !== null && (record.timestampMs < from || record.timestampMs > to)) return false;
+    if (query.sessionIds?.length && !query.sessionIds.includes(record.sessionId)) return false;
+    if (query.agent?.length && !query.agent.includes(record.agent)) return false;
+    if (query.channel?.length && !query.channel.includes(record.channel)) return false;
+    if (query.provider?.length && !query.provider.includes(record.provider)) return false;
+    if (query.model?.length && !query.model.includes(record.model)) return false;
+    return true;
+  });
+}
+
+function filterEvents(events: SessionUsageEvent[], query: UsageQuery): SessionUsageEvent[] {
+  const from = query.from ? Date.parse(query.from) : Number.NEGATIVE_INFINITY;
+  const to = query.to ? Date.parse(query.to) : Number.POSITIVE_INFINITY;
+
+  return events.filter((event) => {
+    if (event.ts < from || event.ts > to) return false;
+    if (query.sessionIds?.length && !query.sessionIds.includes(event.sessionId)) return false;
+    if (query.agent?.length && !query.agent.includes(event.agent)) return false;
+    if (query.channel?.length && !query.channel.includes(event.channel)) return false;
+    if (query.provider?.length && !query.provider.includes(event.provider)) return false;
+    if (query.model?.length && !query.model.includes(event.model)) return false;
+    if (query.tool?.length) {
+      if (!event.toolName || !query.tool.includes(event.toolName)) return false;
+    }
+    return true;
+  });
+}
+
+function summarizeEvents(events: SessionUsageEvent[]): UsageSummaryBucket {
+  const usage = blankUsage();
+  const seenSessions = new Set<string>();
+
+  for (const event of events) {
+    applyEvent(usage, event);
+    seenSessions.add(event.sessionId);
+  }
+
+  usage.sessions = seenSessions.size;
+  return usage;
+}
+
+function summarizeSessionRecords(records: SessionSummaryRecord[]): UsageSummaryBucket {
+  const usage = blankUsage();
+  const seenSessions = new Set<string>();
+
+  for (const record of records) {
+    mergeUsageWindows(usage, record.totals);
+    seenSessions.add(record.sessionId);
+  }
+
+  usage.sessions = seenSessions.size;
+  return usage;
+}
+
+function buildSessionSummaryRecord(sessionKey: string, entry: SessionsIndexEntry): SessionSummaryRecord {
+  const agent = extractAgentName(sessionKey);
+  const channel = entry.origin?.label ?? entry.origin?.provider ?? 'unknown';
+  const totals = blankUsage();
+  totals.promptTokens = numeric(entry.inputTokens);
+  totals.completionTokens = numeric(entry.outputTokens);
+  totals.totalTokens = numeric(entry.totalTokens);
+  totals.totalCostUsd = numeric(entry.estimatedCostUsd);
+  totals.input = totals.promptTokens;
+  totals.output = totals.completionTokens;
+  totals.cacheRead = numeric(entry.cacheRead);
+  totals.cacheWrite = numeric(entry.cacheWrite);
+  totals.cachedTokens = totals.cacheRead;
+
+  return {
+    sessionId: entry.sessionId ?? 'unknown',
+    totals,
+    timestampMs: typeof entry.updatedAt === 'number' ? entry.updatedAt : null,
+    runtimeMs: typeof entry.runtimeMs === 'number' ? entry.runtimeMs : null,
+    provider: 'unknown',
+    model: 'unknown',
+    agent,
+    channel
+  };
+}
+
+function buildSessionSummaryFromEvents(
+  events: SessionUsageEvent[],
+  sessionKey: string,
+  entry: SessionsIndexEntry
+): SessionSummaryRecord {
+  if (events.length === 0) {
+    return buildSessionSummaryRecord(sessionKey, entry);
+  }
+
+  const totals = summarizeEvents(events);
+  const timestamps = events.map((event) => event.ts).sort((a, b) => a - b);
+  const lastEvent = [...events].reverse().find((event) => event.model !== 'unknown' || event.provider !== 'unknown') ?? events[events.length - 1];
+  const spanMs = timestamps.length > 1 ? timestamps[timestamps.length - 1] - timestamps[0] : 0;
+
+  return {
+    sessionId: entry.sessionId ?? 'unknown',
+    totals,
+    timestampMs: timestamps[timestamps.length - 1] ?? null,
+    runtimeMs: Math.max(typeof entry.runtimeMs === 'number' ? entry.runtimeMs : 0, spanMs) || null,
+    provider: lastEvent.provider,
+    model: lastEvent.model,
+    agent: extractAgentName(sessionKey),
+    channel: entry.origin?.label ?? entry.origin?.provider ?? 'unknown'
+  };
+}
+
+function applyEvent(target: UsageSummaryBucket, event: SessionUsageEvent) {
+  target.input += event.input;
+  target.output += event.output;
+  target.cacheRead += event.cacheRead;
+  target.cacheWrite += event.cacheWrite;
+  target.totalTokens += event.totalTokens;
+  target.totalCostUsd += event.totalCostUsd;
+  target.cachedTokens += event.cacheRead;
+  target.promptTokens += event.input;
+  target.completionTokens += event.output;
+  target.messages += event.messageCount;
+  if (event.isError) {
+    target.errors += 1;
+  }
+  target.toolCalls += event.toolCallsCount;
+}
+
+function buildSummaryMetrics(usage: UsageSummaryBucket, summaries: SessionSummaryRecord[]) {
+  const minutes = computeRuntimeMinutes(summaries);
+
+  return {
+    messages: usage.messages,
+    sessions: usage.sessions,
+    totalTokens: usage.totalTokens,
+    totalCostUsd: usage.totalCostUsd,
+    toolCalls: usage.toolCalls,
+    errors: usage.errors,
+    cachedTokens: usage.cachedTokens,
+    promptTokens: usage.promptTokens,
+    completionTokens: usage.completionTokens,
+    avgTokensPerMessage: usage.messages > 0 ? usage.totalTokens / usage.messages : 0,
+    avgCostPerMessageUsd: usage.messages > 0 ? usage.totalCostUsd / usage.messages : 0,
+    cacheHitRate: usage.promptTokens > 0 ? usage.cachedTokens / usage.promptTokens : 0,
+    errorRate: usage.messages > 0 ? usage.errors / usage.messages : 0,
+    throughputTokPerMin: minutes > 0 ? usage.totalTokens / minutes : 0
+  };
+}
+
+function buildSessionRows(records: SessionSummaryRecord[]) {
+  return [...records]
+    .sort((a, b) => (b.timestampMs ?? 0) - (a.timestampMs ?? 0))
+    .map((record) => ({
+      sessionId: record.sessionId,
+      agent: record.agent,
+      provider: record.provider,
+      model: record.model,
+      channel: record.channel,
+      updatedAt: record.timestampMs ? new Date(record.timestampMs).toISOString() : null,
+      runtimeMs: record.runtimeMs,
+      messages: record.totals.messages,
+      totalTokens: record.totals.totalTokens,
+      totalCostUsd: record.totals.totalCostUsd,
+      toolCalls: record.totals.toolCalls,
+      errors: record.totals.errors,
+      cachedTokens: record.totals.cachedTokens,
+      promptTokens: record.totals.promptTokens,
+      completionTokens: record.totals.completionTokens
+    }));
+}
+
+function buildSummaryRankedList(records: SessionSummaryRecord[], dimension: string, limit: number) {
+  const breakdown = new Map<string, UsageBucketState>();
+
+  for (const record of records) {
+    const key = dimensionValueFromSummary(record, dimension);
+    if (shouldHideRankingKey(dimension, key, record.totals.totalTokens)) {
+      continue;
+    }
+    const bucket = breakdown.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    mergeUsageWindows(bucket.usage, record.totals);
+    bucket.sessionIds.add(record.sessionId);
+    breakdown.set(key, bucket);
+  }
+
+  return [...breakdown.entries()]
+    .map(([key, bucket]) => ({
+      key,
+      label: key,
+      messages: bucket.usage.messages,
+      sessions: bucket.sessionIds.size,
+      totalTokens: bucket.usage.totalTokens,
+      totalCostUsd: bucket.usage.totalCostUsd,
+      toolCalls: bucket.usage.toolCalls,
+      errors: bucket.usage.errors,
+      cachedTokens: bucket.usage.cachedTokens,
+      cacheHitRate: bucket.usage.promptTokens > 0 ? bucket.usage.cachedTokens / bucket.usage.promptTokens : 0,
+      avgTokensPerMessage: bucket.usage.messages > 0 ? bucket.usage.totalTokens / bucket.usage.messages : 0
+    }))
+    .sort((a, b) => b.totalTokens - a.totalTokens)
+    .slice(0, limit);
+}
+
+function buildToolRankedList(events: SessionUsageEvent[], limit: number) {
+  const breakdown = new Map<string, UsageBucketState>();
+
+  for (const event of events) {
+    if (event.toolCallsCount === 0) {
+      continue;
+    }
+    const key = dimensionValue(event, 'tool');
+    if (shouldHideRankingKey('tool', key, event.totalTokens)) {
+      continue;
+    }
+    const bucket = breakdown.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    applyEvent(bucket.usage, event);
+    bucket.sessionIds.add(event.sessionId);
+    breakdown.set(key, bucket);
+  }
+
+  return [...breakdown.entries()]
+    .map(([key, bucket]) => ({
+      key,
+      label: key,
+      messages: bucket.usage.messages,
+      sessions: bucket.sessionIds.size,
+      totalTokens: bucket.usage.totalTokens,
+      totalCostUsd: bucket.usage.totalCostUsd,
+      toolCalls: bucket.usage.toolCalls,
+      errors: bucket.usage.errors,
+      cachedTokens: bucket.usage.cachedTokens,
+      cacheHitRate: bucket.usage.promptTokens > 0 ? bucket.usage.cachedTokens / bucket.usage.promptTokens : 0,
+      avgTokensPerMessage: bucket.usage.messages > 0 ? bucket.usage.totalTokens / bucket.usage.messages : 0
+    }))
+    .sort((a, b) => b.toolCalls - a.toolCalls)
+    .slice(0, limit);
+}
+
+function buildSummaryBreakdown(
+  records: SessionSummaryRecord[],
+  dimension: string,
+  totalTokens: number,
+  limit: number,
+  sortBy: string,
+  order: 'asc' | 'desc'
+) {
+  const buckets = new Map<string, UsageBucketState>();
+
+  for (const record of records) {
+    const key = dimensionValueFromSummary(record, dimension);
+    if (shouldHideRankingKey(dimension, key, record.totals.totalTokens)) {
+      continue;
+    }
+    const bucket = buckets.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    mergeUsageWindows(bucket.usage, record.totals);
+    bucket.sessionIds.add(record.sessionId);
+    buckets.set(key, bucket);
+  }
+
+  return [...buckets.entries()]
+    .map(([key, bucket]) => ({
+      key,
+      label: key,
+      messages: bucket.usage.messages,
+      sessions: bucket.sessionIds.size,
+      totalTokens: bucket.usage.totalTokens,
+      totalCostUsd: bucket.usage.totalCostUsd,
+      toolCalls: bucket.usage.toolCalls,
+      errors: bucket.usage.errors,
+      cachedTokens: bucket.usage.cachedTokens,
+      cacheHitRate: bucket.usage.promptTokens > 0 ? bucket.usage.cachedTokens / bucket.usage.promptTokens : 0,
+      avgTokensPerMessage: bucket.usage.messages > 0 ? bucket.usage.totalTokens / bucket.usage.messages : 0,
+      avgCostPerMessageUsd: bucket.usage.messages > 0 ? bucket.usage.totalCostUsd / bucket.usage.messages : 0,
+      throughputTokPerMin: computeThroughput(bucket.usage.totalTokens, 'day'),
+      share: totalTokens > 0 ? bucket.usage.totalTokens / totalTokens : 0
+    }))
+    .sort((a, b) => compareRows(a, b, sortBy, order))
+    .slice(0, limit);
+}
+
+function buildToolBreakdown(
+  events: SessionUsageEvent[],
+  totalTokens: number,
+  limit: number,
+  sortBy: string,
+  order: 'asc' | 'desc'
+) {
+  const buckets = new Map<string, UsageBucketState>();
+
+  for (const event of events) {
+    if (event.toolCallsCount === 0) {
+      continue;
+    }
+    const key = dimensionValue(event, 'tool');
+    if (shouldHideRankingKey('tool', key, event.totalTokens)) {
+      continue;
+    }
+    const bucket = buckets.get(key) ?? { usage: blankUsage(), sessionIds: new Set<string>() };
+    applyEvent(bucket.usage, event);
+    bucket.sessionIds.add(event.sessionId);
+    buckets.set(key, bucket);
+  }
+
+  return [...buckets.entries()]
+    .map(([key, bucket]) => ({
+      key,
+      label: key,
+      messages: bucket.usage.messages,
+      sessions: bucket.sessionIds.size,
+      totalTokens: bucket.usage.totalTokens,
+      totalCostUsd: bucket.usage.totalCostUsd,
+      toolCalls: bucket.usage.toolCalls,
+      errors: bucket.usage.errors,
+      cachedTokens: bucket.usage.cachedTokens,
+      cacheHitRate: bucket.usage.promptTokens > 0 ? bucket.usage.cachedTokens / bucket.usage.promptTokens : 0,
+      avgTokensPerMessage: bucket.usage.messages > 0 ? bucket.usage.totalTokens / bucket.usage.messages : 0,
+      avgCostPerMessageUsd: bucket.usage.messages > 0 ? bucket.usage.totalCostUsd / bucket.usage.messages : 0,
+      throughputTokPerMin: computeThroughput(bucket.usage.totalTokens, 'day'),
+      share: totalTokens > 0 ? bucket.usage.totalTokens / totalTokens : 0
+    }))
+    .sort((a, b) => compareRows(a, b, sortBy, order))
+    .slice(0, limit);
+}
+
+function dimensionValueFromSummary(record: SessionSummaryRecord, dimension: string): string {
+  switch (dimension) {
+    case 'provider':
+      return record.provider;
+    case 'agent':
+      return record.agent;
+    case 'channel':
+      return record.channel;
+    case 'model':
+    default:
+      return record.model;
+  }
+}
+
+function dimensionValue(event: SessionUsageEvent, dimension: string): string {
+  switch (dimension) {
+    case 'provider':
+      return event.provider;
+    case 'tool':
+      return event.toolName ?? 'none';
+    case 'agent':
+      return event.agent;
+    case 'channel':
+      return event.channel;
+    case 'model':
+    default:
+      return event.model;
+  }
+}
+
+function buildWindow(query: UsageQuery) {
+  const now = new Date();
+  const from = query.from ?? new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+  const to = query.to ?? now.toISOString();
+
+  return {
+    from,
+    to,
+    timezone: query.timezone ?? 'UTC',
+    basis: query.basis === 'cost' ? 'cost' : 'token'
+  };
+}
+
+function readUsageQuery(params: JsonValue | undefined): UsageQuery {
+  if (!isObject(params)) {
+    return {};
+  }
+
+  return {
+    from: typeof params.from === 'string' ? params.from : undefined,
+    to: typeof params.to === 'string' ? params.to : undefined,
+    timezone: typeof params.timezone === 'string' ? params.timezone : undefined,
+    basis: typeof params.basis === 'string' ? params.basis : undefined,
+    agent: stringArray(params.agent),
+    channel: stringArray(params.channel),
+    provider: stringArray(params.provider),
+    model: stringArray(params.model),
+    tool: stringArray(params.tool),
+    sessionIds: stringArray(params.sessionIds)
+  };
+}
+
+function stringArray(value: JsonValue | undefined): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((item): item is string => typeof item === 'string');
+}
+
+function isObject(value: JsonValue | undefined): value is Record<string, JsonValue> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isObjectRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function numeric(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseTimestamp(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function extractAgentName(sessionKey: string): string {
+  const parts = sessionKey.split(':');
+  return parts.length >= 2 ? parts[1] : 'main';
+}
+
+function extractAgentNameFromPath(filePath: string): string {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\/agents\/([^/]+)\/sessions\//);
+  return match?.[1] ?? 'main';
+}
+
+function bucketTimestamp(timestamp: number, granularity: string): number {
+  const date = new Date(timestamp);
+  if (granularity === 'minute') {
+    date.setSeconds(0, 0);
+    return date.getTime();
+  }
+  if (granularity === 'hour') {
+    date.setMinutes(0, 0, 0);
+    return date.getTime();
+  }
+  date.setHours(0, 0, 0, 0);
+  return date.getTime();
+}
+
+function computeThroughput(totalTokens: number, granularity: string): number {
+  if (granularity === 'minute') return totalTokens;
+  if (granularity === 'hour') return totalTokens / 60;
+  return totalTokens / (24 * 60);
+}
+
+function compareRows(
+  left: Record<string, number | string>,
+  right: Record<string, number | string>,
+  sortBy: string,
+  order: 'asc' | 'desc'
+) {
+  const leftValue = typeof left[sortBy] === 'number' ? (left[sortBy] as number) : 0;
+  const rightValue = typeof right[sortBy] === 'number' ? (right[sortBy] as number) : 0;
+  return order === 'asc' ? leftValue - rightValue : rightValue - leftValue;
+}
+
+function computeRuntimeMinutes(records: SessionSummaryRecord[]): number {
+  const runtimeMs = records.reduce((sum, record) => sum + (record.runtimeMs ?? 0), 0);
+  return runtimeMs > 0 ? runtimeMs / 60000 : 0;
+}
+
+function shouldHideRankingKey(dimension: string, key: string, totalTokens: number): boolean {
+  if (dimension === 'tool') {
+    return key === 'none' || totalTokens <= 0;
+  }
+
+  if (dimension === 'model') {
+    return key === 'unknown' || key === 'gateway-injected' || totalTokens <= 0;
+  }
+
+  if (dimension === 'provider') {
+    return key === 'unknown' || key === 'openclaw' || totalTokens <= 0;
+  }
+
+  if (dimension === 'channel') {
+    return key === 'unknown' || totalTokens <= 0;
+  }
+
+  return totalTokens <= 0;
+}
+
+function mergeUsageWindows(target: UsageSummaryBucket, source: UsageSummaryBucket) {
+  target.input += source.input;
+  target.output += source.output;
+  target.cacheRead += source.cacheRead;
+  target.cacheWrite += source.cacheWrite;
+  target.totalTokens += source.totalTokens;
+  target.totalCostUsd += source.totalCostUsd;
+  target.toolCalls += source.toolCalls;
+  target.errors += source.errors;
+  target.messages += source.messages;
+  target.cachedTokens += source.cachedTokens;
+  target.promptTokens += source.promptTokens;
+  target.completionTokens += source.completionTokens;
+}