Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

8.8 KB
Raw Blame
import { isJsonObject } from "../json.ts";
import * as Predicate from "effect/Predicate";
import type * as Schema from "effect/Schema";
/**
 * Durable per-file scan cache.
 *
 * Transcripts are append-only and a file that has not changed can never yield
 * different usage, so parsed records are keyed by `(size, mtime)` and reused.
 * Without this every server restart re-parses the whole window: roughly 3.5s
 * for a 30-day scan here, against ~11ms to reload this cache.
 *
 * Caching *per file* rather than per day is deliberate. It is timezone
 * independent, so changing the reporting zone does not invalidate anything, and
 * it keeps cross-file de-duplication exact: cached entries are de-duplicated
 * within their own file only, and the aggregator still applies the global
 * dedupe pass over the small surviving key set.
 *
 * @module usageScanCache
 */
import type { UsageProviderKind } from "@akeru/contracts";

import type { UsageRecord } from "./usageTranscripts.ts";

// v2: Codex fork-copy suppression changed what a file parses to, so v1
// entries would keep serving double-counted records forever.
export const USAGE_SCAN_CACHE_VERSION = 2;

export interface CachedFile {
  readonly size: number;
  readonly mtimeMs: number;
  readonly provider: UsageProviderKind;
  readonly records: readonly UsageRecord[];
}

export type ScanCache = Map<string, CachedFile>;

/**
 * Row layout for the serialised form. Positional and interned rather than
 * object-per-record: on a 30-day window that is the difference between a file
 * measured in tens of megabytes and one under six.
 */
type SerializedRecord = readonly [
  timestampMs: number,
  modelIndex: number,
  sessionIndex: number,
  uncachedInputTokens: number,
  cachedInputTokens: number,
  cacheCreationTokens: number,
  outputTokens: number,
  reasoningTokens: number,
  dedupeKey: string | null,
  reportedCostUsd: number | null,
];

interface SerializedFile {
  readonly s: number;
  readonly m: number;
  readonly p: UsageProviderKind;
  readonly r: readonly SerializedRecord[];
}

interface SerializedCache {
  readonly version: number;
  readonly models: readonly string[];
  readonly sessions: readonly string[];
  readonly files: Readonly<Record<string, SerializedFile>>;
}

/** Serialises the cache, interning the repeated model and session strings. */
export function encodeScanCache(cache: ScanCache): SerializedCache {
  const models: string[] = [];
  const sessions: string[] = [];
  const modelIndex = new Map<string, number>();
  const sessionIndex = new Map<string, number>();

  const intern = (table: string[], index: Map<string, number>, value: string): number => {
    const existing = index.get(value);

    if (existing !== undefined) return existing;
    const next = table.length;
    table.push(value);
    index.set(value, next);

    return next;
  };

  const files: Record<string, SerializedFile> = {};

  for (const [path, entry] of cache) {
    files[path] = {
      s: entry.size,
      m: entry.mtimeMs,
      p: entry.provider,
      r: entry.records.map((record) => [
        record.timestampMs,
        intern(models, modelIndex, record.model),
        intern(sessions, sessionIndex, record.sessionId),
        record.totals.uncachedInputTokens,
        record.totals.cachedInputTokens,
        record.totals.cacheCreationTokens,
        record.totals.outputTokens,
        record.totals.reasoningTokens,
        record.dedupeKey,
        record.reportedCostUsd,
      ]),
    };
  }

  return { version: USAGE_SCAN_CACHE_VERSION, models, sessions, files };
}

/**
 * Rebuilds the cache from a parsed document.
 *
 * Anything malformed yields an empty cache rather than an error: a corrupt
 * cache should cost one cold scan, never a broken page.
 */
export function decodeScanCache(document: Schema.Json): ScanCache {
  const cache: ScanCache = new Map();

  if (!isJsonObject(document)) return cache;

  const root = document;

  if (root.version !== USAGE_SCAN_CACHE_VERSION) return cache;

  if (!Array.isArray(root.models) || !Array.isArray(root.sessions)) return cache;

  if (!isJsonObject(root.files)) return cache;

  // The intern tables must be all strings: a numeric entry would pass the
  // undefined guard below, land in a record's model, and crash the aggregate
  // at lookupRate. A corrupt table rejects the whole cache.
  if (!root.models.every((value) => Predicate.isString(value))) return cache;

  if (!root.sessions.every((value) => Predicate.isString(value))) return cache;
  const models = root.models;
  const sessions = root.sessions;

  for (const [path, raw] of Object.entries(root.files)) {
    if (!isJsonObject(raw)) continue;
    const entry = raw;

    if (!Predicate.isNumber(entry.s) || !Predicate.isNumber(entry.m)) continue;

    if (entry.p !== "claude" && entry.p !== "codex") continue;

    if (!Array.isArray(entry.r)) continue;

    const provider = entry.p;
    const records: UsageRecord[] = [];
    // Any corrupt row disqualifies the whole entry. Keeping the survivors
    // under the original (size, mtime) would read as a valid warm hit and the
    // file would never be re-parsed, silently losing the dropped rows' usage.
    let corrupt = false;

    for (const row of entry.r) {
      if (!Array.isArray(row) || row.length < 10) {
        corrupt = true;
        break;
      }

      const [
        timestampMs,
        modelIndex,
        sessionIndex,
        uncached,
        cached,
        cacheCreation,
        output,
        reasoning,
        dedupeKey,
        reportedCostUsd,
      ] = row;

      const model = Predicate.isNumber(modelIndex) ? models[modelIndex] : undefined;

      if (
        !Predicate.isNumber(timestampMs) ||
        !Number.isFinite(timestampMs) ||
        model === undefined ||
        !Predicate.isNumber(uncached) ||
        !Number.isFinite(uncached) ||
        !Predicate.isNumber(cached) ||
        !Number.isFinite(cached) ||
        !Predicate.isNumber(cacheCreation) ||
        !Number.isFinite(cacheCreation) ||
        !Predicate.isNumber(output) ||
        !Number.isFinite(output) ||
        !Predicate.isNumber(reasoning) ||
        !Number.isFinite(reasoning)
      ) {
        corrupt = true;
        break;
      }

      records.push({
        provider,
        timestampMs,
        model,
        sessionId: (Predicate.isNumber(sessionIndex) ? sessions[sessionIndex] : undefined) ?? "",
        totals: {
          uncachedInputTokens: uncached,
          cachedInputTokens: cached,
          cacheCreationTokens: cacheCreation,
          outputTokens: output,
          reasoningTokens: reasoning,
        },
        reportedCostUsd: Predicate.isNumber(reportedCostUsd) ? reportedCostUsd : null,
        dedupeKey: Predicate.isString(dedupeKey) ? dedupeKey : null,
      });
    }

    if (corrupt) continue;
    cache.set(path, { size: entry.s, mtimeMs: entry.m, provider, records });
  }

  return cache;
}

export interface PruneOptions {
  /** Files the walk just saw. Only meaningful inside the walked window. */
  readonly livePaths: ReadonlySet<string>;
  /**
   * Roots the walk actually completed. Absence from `livePaths` only proves a
   * file is gone when its root was walked: a provider whose directory failed to
   * resolve this pass must not have its warm entries purged.
   */
  readonly walkedRoots: readonly string[];
  /** Start of the walked window; entries older than this were not looked for. */
  readonly windowStartMs: number;
  /** Entries older than this are dropped regardless. */
  readonly retentionCutoffMs: number;
}

/**
 * Drops aged-out entries, and entries for files that have disappeared.
 *
 * The walk only covers the requested window, so absence from `livePaths` only
 * proves deletion for entries *inside* that window. Pruning everything the walk
 * missed would evict the 30-day entries every time someone looked at 7 days.
 *
 * Replaces an earlier record cap that cleared the whole cache once exceeded,
 * which meant a large enough window never warmed up at all.
 */
export function pruneScanCache(cache: ScanCache, options: PruneOptions): number {
  let removed = 0;

  for (const [path, entry] of cache) {
    const agedOut = entry.mtimeMs < options.retentionCutoffMs;
    const underWalkedRoot = options.walkedRoots.some((root) => path.startsWith(root));

    const deleted =
      underWalkedRoot && entry.mtimeMs >= options.windowStartMs && !options.livePaths.has(path);

    if (agedOut || deleted) {
      cache.delete(path);
      removed += 1;
    }
  }

  return removed;
}

/** Within-file de-duplication, applied before an entry is cached. */
export function dedupeWithinFile(records: readonly UsageRecord[]): readonly UsageRecord[] {
  const seen = new Set<string>();
  const kept: UsageRecord[] = [];

  for (const record of records) {
    if (record.dedupeKey !== null) {
      if (seen.has(record.dedupeKey)) continue;
      seen.add(record.dedupeKey);
    }

    kept.push(record);
  }

  return kept;
}