aigetwey 1.0.1

package/src/core/keypool.ts

@@ -0,0 +1,152 @@
+/**
+ * Per-provider key pool with round-robin selection and exponential-backoff
+ * cooldown. In-memory only (personal use — state need not survive restart).
+ *
+ * A key that hits a retryable failure is penalized: it goes on cooldown for
+ * `base * 2^(failCount-1)` ms (capped), so a flaky/rate-limited key is skipped
+ * for progressively longer while healthy keys keep serving.
+ */
+import type { Provider } from "../config.js";
+import { maskKey } from "../config.js";
+
+const COOLDOWN_CAP_MS = 5 * 60_000; // 5 minutes
+
+export interface KeyError {
+  message: string;
+  status?: number;
+  at: number;
+}
+
+interface KeyState {
+  key: string;
+  cooldownUntil: number;
+  failCount: number;
+  lastError?: KeyError;
+}
+
+interface ProviderPool {
+  baseMs: number;
+  cursor: number;
+  states: KeyState[];
+}
+
+/**
+ * Keys a provider routes through. A free/keyless provider (OpenCode Free, local
+ * Ollama) gets one empty slot so it still routes — the upstream client omits the
+ * auth header when the key is empty.
+ */
+function keysOf(provider: Provider): string[] {
+  if (provider.api_keys && provider.api_keys.length > 0) return provider.api_keys;
+  if (provider.api_key) return [provider.api_key];
+  return [""];
+}
+
+export class KeyPool {
+  private readonly pools = new Map<string, ProviderPool>();
+  private readonly now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.now = now;
+  }
+
+  private poolFor(provider: Provider): ProviderPool {
+    let pool = this.pools.get(provider.id);
+    if (!pool) {
+      pool = {
+        baseMs: provider.cooldown_base_ms,
+        cursor: 0,
+        states: keysOf(provider).map((key) => ({ key, cooldownUntil: 0, failCount: 0 })),
+      };
+      this.pools.set(provider.id, pool);
+    }
+    return pool;
+  }
+
+  /**
+   * Pick the next available (not-in-cooldown) key, round-robin.
+   * Returns null when every key for this provider is cooling down.
+   */
+  pick(provider: Provider): string | null {
+    const pool = this.poolFor(provider);
+    const n = pool.states.length;
+    const t = this.now();
+    const disabled = new Set(provider.disabled_keys ?? []);
+    for (let i = 0; i < n; i++) {
+      const idx = (pool.cursor + i) % n;
+      if (disabled.has(idx)) continue;
+      const state = pool.states[idx]!;
+      if (state.cooldownUntil <= t) {
+        pool.cursor = (idx + 1) % n;
+        return state.key;
+      }
+    }
+    return null;
+  }
+
+  /** Mark a retryable failure: bump failCount, apply backoff cooldown, and persist the error. */
+  penalize(provider: Provider, key: string, error?: { message: string; status?: number }): void {
+    const pool = this.poolFor(provider);
+    const state = pool.states.find((s) => s.key === key);
+    if (!state) return;
+    state.failCount += 1;
+    const backoff = pool.baseMs * 2 ** (state.failCount - 1);
+    state.cooldownUntil = this.now() + Math.min(backoff, COOLDOWN_CAP_MS);
+    if (error) {
+      state.lastError = { message: error.message, status: error.status, at: this.now() };
+    }
+  }
+
+  /** Mark success: clear failure state so the key is healthy again. */
+  success(provider: Provider, key: string): void {
+    const state = this.poolFor(provider).states.find((s) => s.key === key);
+    if (!state) return;
+    state.failCount = 0;
+    state.cooldownUntil = 0;
+  }
+
+  /** True if at least one key is currently usable. */
+  hasAvailable(provider: Provider): boolean {
+    const pool = this.poolFor(provider);
+    const t = this.now();
+    const disabled = new Set(provider.disabled_keys ?? []);
+    return pool.states.some((s, i) => !disabled.has(i) && s.cooldownUntil <= t);
+  }
+
+  /**
+   * Read-only view of key health for the dashboard. Keys are MASKED — raw
+   * secrets never leave the gateway. `cooldown_ms` is the remaining cooldown
+   * (0 = healthy).
+   */
+  snapshot(providers: Provider[]): ProviderSnapshot[] {
+    const t = this.now();
+    return providers.map((provider) => {
+      const pool = this.poolFor(provider);
+      return {
+        id: provider.id,
+        format: provider.format,
+        keys: pool.states.map((s) => ({
+          key: maskKey(s.key),
+          healthy: s.cooldownUntil <= t,
+          cooldown_ms: Math.max(0, s.cooldownUntil - t),
+          fail_count: s.failCount,
+          last_error: s.lastError ?? null,
+        })),
+      };
+    });
+  }
+}
+
+export interface KeySnapshot {
+  /** masked key, e.g. "sk-…cd12" */
+  key: string;
+  healthy: boolean;
+  cooldown_ms: number;
+  fail_count: number;
+  last_error: KeyError | null;
+}
+
+export interface ProviderSnapshot {
+  id: string;
+  format: Provider["format"];
+  keys: KeySnapshot[];
+}

package/src/core/quota.ts

@@ -0,0 +1,214 @@
+/**
+ * Per-provider token quota tracking with scheduled window resets.
+ *
+ * Distinct from the key-pool cooldown: a cooldown is a transient penalty after a
+ * 429; a quota is a budget that refills on a schedule (a 5-hour rolling window, a
+ * daily/weekly/monthly calendar boundary). When a provider's `limit_tokens` is
+ * reached before its window resets, routing skips it — like a key that's cooling
+ * down, but for the whole provider.
+ *
+ * State is in-memory, optionally persisted so counts survive a restart within
+ * the same window. Calendar boundaries are computed in the provider's timezone.
+ */
+import type { Provider, Quota } from "../config.js";
+
+const HOUR_MS = 3600_000;
+const DAY_MS = 24 * HOUR_MS;
+
+const WEEKDAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+
+/** Optional persistence hook so counts survive a restart within a window. */
+export interface QuotaStore {
+  load(): Array<{ provider_id: string; window_start: number; consumed: number }>;
+  save(providerId: string, windowStart: number, consumed: number): void;
+}
+
+interface QuotaState {
+  windowStart: number;
+  consumed: number;
+}
+
+export interface QuotaSnapshot {
+  provider: string;
+  window: Quota["window"];
+  consumed: number;
+  limit_tokens?: number;
+  /** ms until the next scheduled reset */
+  reset_in_ms: number;
+  /** 0..1 fraction of the limit used, if a limit is set */
+  pct?: number;
+  exhausted: boolean;
+}
+
+// ---- timezone-aware calendar math -----------------------------------------
+
+/** Wall-clock offset (ms) of `tz` at instant `date`: tzWallAsUTC - actualUTC. */
+function tzOffsetMs(date: Date, tz: string): number {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+  const parts = Object.fromEntries(dtf.formatToParts(date).map((p) => [p.type, p.value]));
+  const asUTC = Date.UTC(
+    Number(parts.year),
+    Number(parts.month) - 1,
+    Number(parts.day),
+    Number(parts.hour),
+    Number(parts.minute),
+    Number(parts.second),
+  );
+  return asUTC - date.getTime();
+}
+
+/** Convert a desired wall-clock time in `tz` to an epoch ms. DST-corrected once. */
+function zonedWallToEpoch(y: number, mo: number, d: number, h: number, mi: number, tz: string): number {
+  const guessUTC = Date.UTC(y, mo, d, h, mi);
+  const offset = tzOffsetMs(new Date(guessUTC), tz);
+  let epoch = guessUTC - offset;
+  // re-check once: the offset can differ across a DST boundary
+  const offset2 = tzOffsetMs(new Date(epoch), tz);
+  if (offset2 !== offset) epoch = guessUTC - offset2;
+  return epoch;
+}
+
+/** Wall-clock parts of `nowMs` in `tz`. */
+function zonedParts(nowMs: number, tz: string) {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hourCycle: "h23",
+    weekday: "long",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+  const p = Object.fromEntries(dtf.formatToParts(nowMs).map((x) => [x.type, x.value]));
+  return {
+    year: Number(p.year),
+    month: Number(p.month) - 1,
+    day: Number(p.day),
+    hour: Number(p.hour),
+    minute: Number(p.minute),
+    weekday: String(p.weekday).toLowerCase(),
+  };
+}
+
+function parseHHMM(reset_at: string | undefined): { h: number; m: number } {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(reset_at ?? "");
+  if (!m) return { h: 0, m: 0 };
+  return { h: Math.min(23, Number(m[1])), m: Math.min(59, Number(m[2])) };
+}
+
+/**
+ * Next reset instant (epoch ms) strictly after `now` for a quota schedule.
+ *   - 5h:      rolling — windowStart + 5h.
+ *   - daily:   next `reset_at` (HH:MM, default 00:00) wall-clock in tz.
+ *   - weekly:  next `reset_at` weekday (default monday) at 00:00 in tz.
+ *   - monthly: next 1st of month at 00:00 in tz.
+ */
+export function nextResetAt(quota: Quota, windowStart: number, now: number): number {
+  const tz = quota.timezone || "UTC";
+  if (quota.window === "5h") return windowStart + 5 * HOUR_MS;
+
+  const p = zonedParts(now, tz);
+
+  if (quota.window === "daily") {
+    const { h, m } = parseHHMM(quota.reset_at);
+    let candidate = zonedWallToEpoch(p.year, p.month, p.day, h, m, tz);
+    if (candidate <= now) candidate = zonedWallToEpoch(p.year, p.month, p.day + 1, h, m, tz);
+    return candidate;
+  }
+
+  if (quota.window === "weekly") {
+    const target = WEEKDAYS.indexOf((quota.reset_at ?? "monday").toLowerCase());
+    const targetIdx = target === -1 ? 1 : target;
+    const curIdx = WEEKDAYS.indexOf(p.weekday);
+    let daysAhead = (targetIdx - curIdx + 7) % 7;
+    let candidate = zonedWallToEpoch(p.year, p.month, p.day + daysAhead, 0, 0, tz);
+    if (candidate <= now) candidate = zonedWallToEpoch(p.year, p.month, p.day + daysAhead + 7, 0, 0, tz);
+    return candidate;
+  }
+
+  // monthly: first of next month at 00:00
+  return zonedWallToEpoch(p.year, p.month + 1, 1, 0, 0, tz);
+}
+
+export class QuotaTracker {
+  private readonly states = new Map<string, QuotaState>();
+
+  constructor(
+    private readonly now: () => number = Date.now,
+    private readonly store?: QuotaStore,
+  ) {
+    if (store) {
+      for (const row of store.load()) {
+        this.states.set(row.provider_id, { windowStart: row.window_start, consumed: row.consumed });
+      }
+    }
+  }
+
+  /**
+   * Return the live state for a provider, rolling the window over (resetting
+   * consumed to 0) if `now` has crossed the scheduled reset boundary.
+   */
+  private current(provider: Provider): QuotaState | null {
+    if (!provider.quota) return null;
+    const t = this.now();
+    const state = this.states.get(provider.id) ?? { windowStart: t, consumed: 0 };
+    if (!this.states.has(provider.id)) this.states.set(provider.id, state);
+    // boundary is the first reset AFTER this window opened — computed from
+    // windowStart, not `now`. Computing it from `now` would always return the
+    // NEXT future boundary and so never detect that we've crossed one.
+    const reset = nextResetAt(provider.quota, state.windowStart, state.windowStart);
+    if (t >= reset) {
+      state.windowStart = t;
+      state.consumed = 0;
+      this.store?.save(provider.id, state.windowStart, state.consumed);
+    }
+    return state;
+  }
+
+  /** Add consumed tokens for a provider (no-op if it has no quota config). */
+  consume(provider: Provider, tokens: number): void {
+    const state = this.current(provider);
+    if (!state) return;
+    state.consumed += Math.max(0, tokens);
+    this.store?.save(provider.id, state.windowStart, state.consumed);
+  }
+
+  /** True when a token limit is set AND it's been reached in the current window. */
+  isExhausted(provider: Provider): boolean {
+    const state = this.current(provider);
+    if (!state || !provider.quota?.limit_tokens) return false;
+    return state.consumed >= provider.quota.limit_tokens;
+  }
+
+  /** Dashboard view: window, consumed, countdown, and progress for each provider. */
+  snapshot(providers: Provider[]): QuotaSnapshot[] {
+    const t = this.now();
+    return providers.flatMap((provider) => {
+      if (!provider.quota) return [];
+      const state = this.current(provider)!;
+      const reset = nextResetAt(provider.quota, state.windowStart, t);
+      const limit = provider.quota.limit_tokens;
+      return [
+        {
+          provider: provider.id,
+          window: provider.quota.window,
+          consumed: state.consumed,
+          limit_tokens: limit,
+          reset_in_ms: Math.max(0, reset - t),
+          pct: limit ? Math.min(1, state.consumed / limit) : undefined,
+          exhausted: limit ? state.consumed >= limit : false,
+        },
+      ];
+    });
+  }
+}

package/src/core/state.ts

@@ -0,0 +1,65 @@
+/**
+ * Mutable holder for the live gateway config, key pool, and quota tracker.
+ *
+ * Config loads once at boot, but the dashboard edits it at runtime. Routes read
+ * `state.config` / `state.pool` / `state.quota` fresh per request (never close
+ * over them), so a successful reload swaps in the new config + pool atomically —
+ * no restart.
+ *
+ * reload() validates and persists BEFORE swapping: an invalid edit throws and
+ * the old config keeps serving. The pool is rebuilt (cooldown is transient), but
+ * the quota tracker is KEPT across reloads — a budget consumed this window must
+ * survive a config edit, else editing config would silently reset every quota.
+ */
+import {
+  GatewayConfig,
+  parseConfigText,
+  validateConfig,
+  unmaskSecrets,
+  writeConfigFile,
+} from "../config.js";
+import { KeyPool } from "./keypool.js";
+import { QuotaTracker } from "./quota.js";
+
+export class GatewayState {
+  private _config: GatewayConfig;
+  private _pool: KeyPool;
+  private readonly _quota: QuotaTracker;
+
+  constructor(
+    private readonly configPath: string,
+    initial: GatewayConfig,
+    quota?: QuotaTracker,
+  ) {
+    this._config = initial;
+    this._pool = new KeyPool();
+    this._quota = quota ?? new QuotaTracker();
+  }
+
+  get config(): GatewayConfig {
+    return this._config;
+  }
+
+  get pool(): KeyPool {
+    return this._pool;
+  }
+
+  get quota(): QuotaTracker {
+    return this._quota;
+  }
+
+  /**
+   * Validate edited config text, restore masked secrets from the live config,
+   * persist atomically, then swap in a fresh config + pool. Throws without
+   * changing anything if validation fails or a masked key can't be resolved —
+   * the old config keeps serving. The quota tracker is intentionally preserved.
+   */
+  reload(text: string): void {
+    const parsed = parseConfigText(text);
+    const merged = unmaskSecrets(parsed.raw, this._config.raw);
+    const next = validateConfig(merged);
+    writeConfigFile(this.configPath, next.raw);
+    this._config = next;
+    this._pool = new KeyPool();
+  }
+}

package/src/db.ts

@@ -0,0 +1,280 @@
+/**
+ * Usage tracking store, backed by the built-in node:sqlite (no native build).
+ * One `usage` row per upstream request that produced usage; an optional `logs`
+ * table holds request/response summaries for debugging. Unified under DATA_DIR
+ * (default ./data).
+ */
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createRequire } from "node:module";
+
+// node:sqlite is a recent builtin; require it dynamically so bundlers/test
+// transformers that don't yet know the `node:sqlite` specifier don't choke.
+const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite") as {
+  DatabaseSync: typeof import("node:sqlite").DatabaseSync;
+};
+type DatabaseSync = import("node:sqlite").DatabaseSync;
+
+export interface UsageRow {
+  ts: number;
+  alias: string;
+  provider: string;
+  model: string;
+  tokens_in: number;
+  tokens_out: number;
+  cached_tokens: number;
+  cost: number;
+  status: number;
+  latency_ms: number;
+  stream: number; // 0/1
+}
+
+export interface LogRow {
+  ts: number;
+  direction: string; // "ingress" | "egress" | "error"
+  provider: string;
+  status: number;
+  request_summary: string;
+  response_summary: string;
+}
+
+export interface UsageSummary {
+  total: { requests: number; tokens_in: number; tokens_out: number; cost: number };
+  by_provider: Array<{ provider: string; requests: number; tokens_in: number; tokens_out: number; cost: number }>;
+  by_model: Array<{ alias: string; model: string; requests: number; tokens_in: number; tokens_out: number; cost: number }>;
+}
+
+export interface UsageSeriesPoint {
+  ts: number;
+  requests: number;
+  tokens_in: number;
+  tokens_out: number;
+  cost: number;
+}
+
+// node:sqlite returns loosely-typed rows; this alias documents the cast site.
+type SqlRow = Record<string, unknown>;
+const num = (v: unknown): number => Number(v ?? 0);
+
+export class UsageDB {
+  private readonly db: DatabaseSync;
+  private readonly insertUsage;
+  private readonly insertLog;
+  private readonly upsertQuota;
+  private readonly now: () => number;
+
+  constructor(path: string, now: () => number = Date.now) {
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+    this.db = new DatabaseSync(path);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS usage (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        alias TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        tokens_in INTEGER NOT NULL DEFAULT 0,
+        tokens_out INTEGER NOT NULL DEFAULT 0,
+        cached_tokens INTEGER NOT NULL DEFAULT 0,
+        cost REAL NOT NULL DEFAULT 0,
+        status INTEGER NOT NULL,
+        latency_ms INTEGER NOT NULL DEFAULT 0,
+        stream INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage(ts);
+      CREATE TABLE IF NOT EXISTS logs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        direction TEXT NOT NULL,
+        provider TEXT NOT NULL DEFAULT '',
+        status INTEGER NOT NULL DEFAULT 0,
+        request_summary TEXT NOT NULL DEFAULT '',
+        response_summary TEXT NOT NULL DEFAULT ''
+      );
+      CREATE INDEX IF NOT EXISTS idx_logs_ts ON logs(ts);
+      CREATE TABLE IF NOT EXISTS quota_state (
+        provider_id TEXT PRIMARY KEY,
+        window_start INTEGER NOT NULL,
+        consumed INTEGER NOT NULL DEFAULT 0,
+        last_reset INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+    this.now = now;
+    this.insertUsage = this.db.prepare(`
+      INSERT INTO usage (ts, alias, provider, model, tokens_in, tokens_out, cached_tokens, cost, status, latency_ms, stream)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    this.insertLog = this.db.prepare(`
+      INSERT INTO logs (ts, direction, provider, status, request_summary, response_summary)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    // upsert keyed on provider_id so each provider keeps one live window row.
+    this.upsertQuota = this.db.prepare(`
+      INSERT INTO quota_state (provider_id, window_start, consumed, last_reset)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(provider_id) DO UPDATE SET window_start = excluded.window_start,
+        consumed = excluded.consumed, last_reset = excluded.last_reset
+    `);
+  }
+
+  record(row: Omit<UsageRow, "ts"> & { ts?: number }): void {
+    this.insertUsage.run(
+      row.ts ?? this.now(),
+      row.alias,
+      row.provider,
+      row.model,
+      row.tokens_in,
+      row.tokens_out,
+      row.cached_tokens,
+      row.cost,
+      row.status,
+      row.latency_ms,
+      row.stream,
+    );
+  }
+
+  log(row: Omit<LogRow, "ts"> & { ts?: number }): void {
+    this.insertLog.run(
+      row.ts ?? this.now(),
+      row.direction,
+      row.provider,
+      row.status,
+      row.request_summary,
+      row.response_summary,
+    );
+  }
+
+  /** Summary over rows with ts >= sinceMs (default: all time). */
+  summary(sinceMs = 0): UsageSummary {
+    const total = this.db
+      .prepare(
+        `SELECT COUNT(*) requests, COALESCE(SUM(tokens_in),0) tokens_in,
+                COALESCE(SUM(tokens_out),0) tokens_out, COALESCE(SUM(cost),0) cost
+         FROM usage WHERE ts >= ?`,
+      )
+      .get(sinceMs) as SqlRow;
+
+    const by_provider = this.db
+      .prepare(
+        `SELECT provider, COUNT(*) requests, COALESCE(SUM(tokens_in),0) tokens_in,
+                COALESCE(SUM(tokens_out),0) tokens_out, COALESCE(SUM(cost),0) cost
+         FROM usage WHERE ts >= ? GROUP BY provider ORDER BY cost DESC`,
+      )
+      .all(sinceMs) as SqlRow[];
+
+    const by_model = this.db
+      .prepare(
+        `SELECT alias, model, COUNT(*) requests, COALESCE(SUM(tokens_in),0) tokens_in,
+                COALESCE(SUM(tokens_out),0) tokens_out, COALESCE(SUM(cost),0) cost
+         FROM usage WHERE ts >= ? GROUP BY alias, model ORDER BY cost DESC`,
+      )
+      .all(sinceMs) as SqlRow[];
+
+    return {
+      total: {
+        requests: num(total.requests),
+        tokens_in: num(total.tokens_in),
+        tokens_out: num(total.tokens_out),
+        cost: num(total.cost),
+      },
+      by_provider: by_provider.map((r) => ({
+        provider: String(r.provider),
+        requests: num(r.requests),
+        tokens_in: num(r.tokens_in),
+        tokens_out: num(r.tokens_out),
+        cost: num(r.cost),
+      })),
+      by_model: by_model.map((r) => ({
+        alias: String(r.alias),
+        model: String(r.model),
+        requests: num(r.requests),
+        tokens_in: num(r.tokens_in),
+        tokens_out: num(r.tokens_out),
+        cost: num(r.cost),
+      })),
+    };
+  }
+
+  /**
+   * Bucketed time-series for charts: one point per `bucketMs` interval from
+   * `sinceMs` to now, aligned to the bucket boundary, with zero-filled gaps.
+   */
+  series(sinceMs: number, bucketMs: number): UsageSeriesPoint[] {
+    const now = this.now();
+    const start = Math.floor(sinceMs / bucketMs) * bucketMs;
+    const rows = this.db
+      .prepare(
+        `SELECT CAST(ts / ? AS INTEGER) * ? AS bucket, COUNT(*) requests,
+                COALESCE(SUM(tokens_in),0) tokens_in,
+                COALESCE(SUM(tokens_out),0) tokens_out, COALESCE(SUM(cost),0) cost
+         FROM usage WHERE ts >= ? GROUP BY bucket ORDER BY bucket`,
+      )
+      .all(bucketMs, bucketMs, sinceMs) as SqlRow[];
+
+    const byBucket = new Map<number, SqlRow>();
+    for (const r of rows) byBucket.set(num(r.bucket), r);
+
+    const out: UsageSeriesPoint[] = [];
+    for (let t = start; t <= now; t += bucketMs) {
+      const r = byBucket.get(t);
+      out.push({
+        ts: t,
+        requests: r ? num(r.requests) : 0,
+        tokens_in: r ? num(r.tokens_in) : 0,
+        tokens_out: r ? num(r.tokens_out) : 0,
+        cost: r ? num(r.cost) : 0,
+      });
+    }
+    return out;
+  }
+
+  /** Most recent usage rows, newest first. For the dashboard logs page. */
+  recent(limit = 100): UsageRow[] {
+    const rows = this.db
+      .prepare(
+        `SELECT ts, alias, provider, model, tokens_in, tokens_out, cached_tokens,
+                cost, status, latency_ms, stream
+         FROM usage ORDER BY id DESC LIMIT ?`,
+      )
+      .all(Math.max(1, Math.min(limit, 1000))) as SqlRow[];
+    return rows.map((r) => ({
+      ts: num(r.ts),
+      alias: String(r.alias),
+      provider: String(r.provider),
+      model: String(r.model),
+      tokens_in: num(r.tokens_in),
+      tokens_out: num(r.tokens_out),
+      cached_tokens: num(r.cached_tokens),
+      cost: num(r.cost),
+      status: num(r.status),
+      latency_ms: num(r.latency_ms),
+      stream: num(r.stream),
+    }));
+  }
+
+  // ---- QuotaStore: one live window row per provider (survives restart) ----
+
+  loadQuota(): Array<{ provider_id: string; window_start: number; consumed: number }> {
+    const rows = this.db.prepare(`SELECT provider_id, window_start, consumed FROM quota_state`).all() as SqlRow[];
+    return rows.map((r) => ({
+      provider_id: String(r.provider_id),
+      window_start: num(r.window_start),
+      consumed: num(r.consumed),
+    }));
+  }
+
+  saveQuota(providerId: string, windowStart: number, consumed: number): void {
+    this.upsertQuota.run(providerId, windowStart, consumed, this.now());
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+/** Compute USD cost from token counts and per-1M prices. */
+export function computeCost(tokensIn: number, tokensOut: number, priceIn?: number, priceOut?: number): number {
+  const ci = priceIn ? (tokensIn / 1_000_000) * priceIn : 0;
+  const co = priceOut ? (tokensOut / 1_000_000) * priceOut : 0;
+  return ci + co;
+}