tokentrace 0.1.0

package/src/lib/analytics.ts

@@ -0,0 +1,592 @@
+import { sqlite } from "@/src/db/client";
+
+export type TrendPoint = {
+  date: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
+  reasoningTokens: number;
+  cost: number;
+};
+
+export type SummaryMetrics = {
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
+  reasoningTokens: number;
+  totalCost: number;
+  exactCost: number;
+  estimatedCost: number;
+  unknownCostInteractions: number;
+  sessions: number;
+  interactions: number;
+  mostUsedTool: string;
+  mostUsedModel: string;
+};
+
+export type ToolComparisonRow = {
+  tool: string;
+  provider: string;
+  totalTokens: number;
+  cost: number;
+  sessions: number;
+  interactions: number;
+  averageTokensPerSession: number;
+  averageTokensPerInteraction: number;
+  outputInputRatio: number;
+  cacheEfficiency: number;
+  mostExpensiveModel: string;
+};
+
+export type ModelAnalyticsRow = {
+  model: string;
+  provider: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+  interactions: number;
+  averageOutputTokens: number;
+  tokenEfficiency: number;
+  suggestedAlternative: string | null;
+  overuseFlag: string | null;
+};
+
+export type ProjectAnalyticsRow = {
+  id: string;
+  project: string;
+  path: string;
+  totalTokens: number;
+  cost: number;
+  sessions: number;
+  interactions: number;
+  outputInputRatio: number;
+  lastUsedAt: number | null;
+};
+
+export type SessionRow = {
+  id: string;
+  startedAt: number | null;
+  endedAt: number | null;
+  title: string | null;
+  sourceFile: string;
+  tool: string;
+  provider: string;
+  project: string;
+  projectPath: string;
+  models: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
+  reasoningTokens: number;
+  cost: number | null;
+  costEstimated: boolean;
+  estimatedTokens: boolean;
+  tokenConfidence: string;
+  interactionCount: number;
+  durationMs: number | null;
+};
+
+export type Insight = {
+  id: string;
+  severity: "high" | "medium" | "low";
+  problem: string;
+  evidence: string;
+  savingOpportunity: string;
+  recommendation: string;
+};
+
+export type DebugScanFile = {
+  id: string;
+  scanRunId: string;
+  path: string;
+  modifiedTime: number | null;
+  sizeBytes: number;
+  fileHash: string | null;
+  parser: string | null;
+  status: string;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+  rawMetadata: Record<string, unknown>;
+  scanStartedAt: number;
+};
+
+export type DebugScanRun = {
+  id: string;
+  startedAt: number;
+  completedAt: number | null;
+  filesScanned: number;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+};
+
+export type AnalyticsData = {
+  summary: SummaryMetrics;
+  trends: TrendPoint[];
+  tools: ToolComparisonRow[];
+  models: ModelAnalyticsRow[];
+  projects: ProjectAnalyticsRow[];
+  sessions: SessionRow[];
+  insights: Insight[];
+};
+
+function number(value: unknown) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (Array.isArray(value) || (value && typeof value === "object")) return value as T;
+  if (typeof value !== "string") return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function rows<T>(sql: string, ...params: unknown[]) {
+  return sqlite.prepare(sql).all(...params) as T[];
+}
+
+function getSummary(): SummaryMetrics {
+  const aggregate = sqlite
+    .prepare(
+      `SELECT
+        COALESCE(SUM(total_tokens), 0) AS totalTokens,
+        COALESCE(SUM(input_tokens), 0) AS inputTokens,
+        COALESCE(SUM(output_tokens), 0) AS outputTokens,
+        COALESCE(SUM(cache_read_tokens + cache_write_tokens), 0) AS cachedTokens,
+        COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+        COALESCE(SUM(cost), 0) AS totalCost,
+        COALESCE(SUM(CASE WHEN cost_estimated = 0 AND cost IS NOT NULL THEN cost ELSE 0 END), 0) AS exactCost,
+        COALESCE(SUM(CASE WHEN cost_estimated = 1 AND cost IS NOT NULL THEN cost ELSE 0 END), 0) AS estimatedCost,
+        COALESCE(SUM(CASE WHEN cost IS NULL THEN 1 ELSE 0 END), 0) AS unknownCostInteractions,
+        COUNT(*) AS interactions,
+        COUNT(DISTINCT session_id) AS sessions
+       FROM interactions`
+    )
+    .get() as Omit<SummaryMetrics, "mostUsedTool" | "mostUsedModel">;
+
+  const tool = sqlite
+    .prepare(
+      `SELECT t.name
+       FROM interactions i
+       JOIN sessions s ON s.id = i.session_id
+       JOIN tools t ON t.id = s.tool_id
+       GROUP BY t.id
+       ORDER BY SUM(i.total_tokens) DESC
+       LIMIT 1`
+    )
+    .get() as { name: string } | undefined;
+
+  const model = sqlite
+    .prepare(
+      `SELECT m.name
+       FROM interactions i
+       LEFT JOIN models m ON m.id = i.model_id
+       GROUP BY m.id
+       ORDER BY SUM(i.total_tokens) DESC
+       LIMIT 1`
+    )
+    .get() as { name: string } | undefined;
+
+  return {
+    totalTokens: number(aggregate.totalTokens),
+    inputTokens: number(aggregate.inputTokens),
+    outputTokens: number(aggregate.outputTokens),
+    cachedTokens: number(aggregate.cachedTokens),
+    reasoningTokens: number(aggregate.reasoningTokens),
+    totalCost: number(aggregate.totalCost),
+    exactCost: number(aggregate.exactCost),
+    estimatedCost: number(aggregate.estimatedCost),
+    unknownCostInteractions: number(aggregate.unknownCostInteractions),
+    sessions: number(aggregate.sessions),
+    interactions: number(aggregate.interactions),
+    mostUsedTool: tool?.name ?? "No data",
+    mostUsedModel: model?.name ?? "No data"
+  };
+}
+
+function getTrends(): TrendPoint[] {
+  return rows<TrendPoint>(
+    `SELECT
+      date(COALESCE(timestamp, 0) / 1000, 'unixepoch') AS date,
+      COALESCE(SUM(total_tokens), 0) AS totalTokens,
+      COALESCE(SUM(input_tokens), 0) AS inputTokens,
+      COALESCE(SUM(output_tokens), 0) AS outputTokens,
+      COALESCE(SUM(cache_read_tokens + cache_write_tokens), 0) AS cachedTokens,
+      COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+      COALESCE(SUM(cost), 0) AS cost
+     FROM interactions
+     WHERE timestamp IS NOT NULL
+     GROUP BY date
+     ORDER BY date ASC`
+  ).map((row) => ({
+    ...row,
+    totalTokens: number(row.totalTokens),
+    inputTokens: number(row.inputTokens),
+    outputTokens: number(row.outputTokens),
+    cachedTokens: number(row.cachedTokens),
+    reasoningTokens: number(row.reasoningTokens),
+    cost: number(row.cost)
+  }));
+}
+
+function getToolComparison(): ToolComparisonRow[] {
+  return rows<
+    ToolComparisonRow & {
+      inputTokens: number;
+      outputTokens: number;
+      cachedTokens: number;
+    }
+  >(
+    `SELECT
+      t.name AS tool,
+      p.name AS provider,
+      COALESCE(SUM(i.total_tokens), 0) AS totalTokens,
+      COALESCE(SUM(i.input_tokens), 0) AS inputTokens,
+      COALESCE(SUM(i.output_tokens), 0) AS outputTokens,
+      COALESCE(SUM(i.cache_read_tokens + i.cache_write_tokens), 0) AS cachedTokens,
+      COALESCE(SUM(i.cost), 0) AS cost,
+      COUNT(DISTINCT s.id) AS sessions,
+      COUNT(i.id) AS interactions,
+      COALESCE((
+        SELECT m2.name
+        FROM interactions i2
+        JOIN sessions s2 ON s2.id = i2.session_id
+        LEFT JOIN models m2 ON m2.id = i2.model_id
+        WHERE s2.tool_id = t.id
+        GROUP BY m2.id
+        ORDER BY SUM(COALESCE(i2.cost, 0)) DESC
+        LIMIT 1
+      ), 'Unknown') AS mostExpensiveModel
+     FROM interactions i
+     JOIN sessions s ON s.id = i.session_id
+     JOIN tools t ON t.id = s.tool_id
+     JOIN providers p ON p.id = t.provider_id
+     GROUP BY t.id, p.id
+     ORDER BY totalTokens DESC`
+  ).map((row) => ({
+    tool: row.tool,
+    provider: row.provider,
+    totalTokens: number(row.totalTokens),
+    cost: number(row.cost),
+    sessions: number(row.sessions),
+    interactions: number(row.interactions),
+    averageTokensPerSession: row.sessions ? number(row.totalTokens) / number(row.sessions) : 0,
+    averageTokensPerInteraction: row.interactions ? number(row.totalTokens) / number(row.interactions) : 0,
+    outputInputRatio: row.inputTokens ? number(row.outputTokens) / number(row.inputTokens) : 0,
+    cacheEfficiency:
+      row.inputTokens + row.cachedTokens
+        ? number(row.cachedTokens) / (number(row.inputTokens) + number(row.cachedTokens))
+        : 0,
+    mostExpensiveModel: row.mostExpensiveModel
+  }));
+}
+
+function getModelRows(): ModelAnalyticsRow[] {
+  const baseRows = rows<
+    ModelAnalyticsRow & {
+      providerId: string;
+      inputPrice: number | null;
+      outputPrice: number | null;
+    }
+  >(
+    `SELECT
+      COALESCE(m.name, 'unknown') AS model,
+      p.name AS provider,
+      p.id AS providerId,
+      m.input_token_price AS inputPrice,
+      m.output_token_price AS outputPrice,
+      COALESCE(SUM(i.total_tokens), 0) AS totalTokens,
+      COALESCE(SUM(i.input_tokens), 0) AS inputTokens,
+      COALESCE(SUM(i.output_tokens), 0) AS outputTokens,
+      COALESCE(SUM(i.cost), 0) AS cost,
+      COUNT(i.id) AS interactions,
+      COALESCE(AVG(i.output_tokens), 0) AS averageOutputTokens
+     FROM interactions i
+     LEFT JOIN models m ON m.id = i.model_id
+     LEFT JOIN providers p ON p.id = m.provider_id
+     GROUP BY m.id
+     ORDER BY totalTokens DESC`
+  );
+
+  const configuredPrices = rows<{
+    providerId: string;
+    name: string;
+    combinedPrice: number;
+  }>(
+    `SELECT provider_id AS providerId, name,
+      COALESCE(input_token_price, 999999) + COALESCE(output_token_price, 999999) AS combinedPrice
+     FROM models
+     WHERE input_token_price IS NOT NULL AND output_token_price IS NOT NULL`
+  );
+
+  return baseRows.map((row) => {
+    const currentPrice = number(row.inputPrice) + number(row.outputPrice);
+    const cheaper = configuredPrices
+      .filter((candidate) => candidate.providerId === row.providerId)
+      .filter((candidate) => candidate.name !== row.model)
+      .filter((candidate) => !currentPrice || candidate.combinedPrice < currentPrice)
+      .sort((a, b) => a.combinedPrice - b.combinedPrice)[0];
+    const tokenEfficiency = row.inputTokens
+      ? number(row.outputTokens) / number(row.inputTokens)
+      : number(row.outputTokens);
+
+    return {
+      model: row.model,
+      provider: row.provider ?? "Unknown",
+      totalTokens: number(row.totalTokens),
+      inputTokens: number(row.inputTokens),
+      outputTokens: number(row.outputTokens),
+      cost: number(row.cost),
+      interactions: number(row.interactions),
+      averageOutputTokens: number(row.averageOutputTokens),
+      tokenEfficiency,
+      suggestedAlternative: cheaper?.name ?? null,
+      overuseFlag:
+        number(row.cost) > 0 && cheaper && number(row.totalTokens) > 25_000
+          ? "Cheaper configured alternative exists"
+          : null
+    };
+  });
+}
+
+function getProjectRows(): ProjectAnalyticsRow[] {
+  return rows<ProjectAnalyticsRow & { inputTokens: number; outputTokens: number }>(
+    `SELECT
+      pr.id,
+      pr.name AS project,
+      pr.path,
+      COALESCE(SUM(i.total_tokens), 0) AS totalTokens,
+      COALESCE(SUM(i.input_tokens), 0) AS inputTokens,
+      COALESCE(SUM(i.output_tokens), 0) AS outputTokens,
+      COALESCE(SUM(i.cost), 0) AS cost,
+      COUNT(DISTINCT s.id) AS sessions,
+      COUNT(i.id) AS interactions,
+      MAX(i.timestamp) AS lastUsedAt
+     FROM projects pr
+     JOIN sessions s ON s.project_id = pr.id
+     LEFT JOIN interactions i ON i.session_id = s.id
+     GROUP BY pr.id
+     ORDER BY totalTokens DESC`
+  ).map((row) => ({
+    id: row.id,
+    project: row.project,
+    path: row.path,
+    totalTokens: number(row.totalTokens),
+    cost: number(row.cost),
+    sessions: number(row.sessions),
+    interactions: number(row.interactions),
+    outputInputRatio: row.inputTokens ? number(row.outputTokens) / number(row.inputTokens) : 0,
+    lastUsedAt: row.lastUsedAt
+  }));
+}
+
+function getSessions(): SessionRow[] {
+  return rows<
+    Omit<SessionRow, "costEstimated" | "estimatedTokens"> & {
+      costEstimated: 0 | 1;
+      estimatedTokens: 0 | 1;
+    }
+  >(
+    `SELECT
+      s.id,
+      s.started_at AS startedAt,
+      s.ended_at AS endedAt,
+      s.title,
+      s.source_file AS sourceFile,
+      t.name AS tool,
+      provider.name AS provider,
+      pr.name AS project,
+      pr.path AS projectPath,
+      COALESCE(group_concat(DISTINCT m.name), 'unknown') AS models,
+      COALESCE(SUM(i.total_tokens), 0) AS totalTokens,
+      COALESCE(SUM(i.input_tokens), 0) AS inputTokens,
+      COALESCE(SUM(i.output_tokens), 0) AS outputTokens,
+      COALESCE(SUM(i.cache_read_tokens + i.cache_write_tokens), 0) AS cachedTokens,
+      COALESCE(SUM(i.reasoning_tokens), 0) AS reasoningTokens,
+      SUM(i.cost) AS cost,
+      MAX(i.cost_estimated) AS costEstimated,
+      MAX(i.estimated_tokens) AS estimatedTokens,
+      CASE
+        WHEN SUM(CASE WHEN i.token_confidence = 'unknown' THEN 1 ELSE 0 END) > 0 THEN 'unknown'
+        WHEN SUM(CASE WHEN i.token_confidence = 'low-confidence estimate' THEN 1 ELSE 0 END) > 0 THEN 'low-confidence estimate'
+        WHEN SUM(CASE WHEN i.token_confidence = 'high-confidence estimate' THEN 1 ELSE 0 END) > 0 THEN 'high-confidence estimate'
+        ELSE 'exact'
+      END AS tokenConfidence,
+      COUNT(i.id) AS interactionCount,
+      CASE WHEN s.started_at IS NOT NULL AND s.ended_at IS NOT NULL THEN s.ended_at - s.started_at ELSE NULL END AS durationMs
+     FROM sessions s
+     JOIN tools t ON t.id = s.tool_id
+     JOIN providers provider ON provider.id = t.provider_id
+     LEFT JOIN projects pr ON pr.id = s.project_id
+     LEFT JOIN interactions i ON i.session_id = s.id
+     LEFT JOIN models m ON m.id = i.model_id
+     GROUP BY s.id
+     ORDER BY COALESCE(s.started_at, 0) DESC
+     LIMIT 1000`
+  ).map((row) => ({
+    ...row,
+    totalTokens: number(row.totalTokens),
+    inputTokens: number(row.inputTokens),
+    outputTokens: number(row.outputTokens),
+    cachedTokens: number(row.cachedTokens),
+    reasoningTokens: number(row.reasoningTokens),
+    cost: row.cost == null ? null : number(row.cost),
+    costEstimated: Boolean(row.costEstimated),
+    estimatedTokens: Boolean(row.estimatedTokens),
+    interactionCount: number(row.interactionCount)
+  }));
+}
+
+function buildInsights(data: {
+  summary: SummaryMetrics;
+  projects: ProjectAnalyticsRow[];
+  sessions: SessionRow[];
+  models: ModelAnalyticsRow[];
+  trends: TrendPoint[];
+}): Insight[] {
+  const insights: Insight[] = [];
+  const totalCost = data.summary.totalCost;
+  const topSessions = [...data.sessions].sort((a, b) => b.totalTokens - a.totalTokens);
+  const topTenTokens = topSessions.slice(0, Math.max(1, Math.ceil(topSessions.length * 0.1))).reduce(
+    (sum, session) => sum + session.totalTokens,
+    0
+  );
+
+  if (data.summary.totalTokens > 0 && topTenTokens / data.summary.totalTokens > 0.5) {
+    insights.push({
+      id: "concentrated-usage",
+      severity: "high",
+      problem: "A small number of sessions account for most token usage.",
+      evidence: `Top sessions represent ${Math.round((topTenTokens / data.summary.totalTokens) * 100)}% of all tokens.`,
+      savingOpportunity: totalCost ? `Reviewing these sessions targets about $${(totalCost * 0.5).toFixed(2)} of spend.` : "High token concentration even when cost is unknown.",
+      recommendation: "Split large tasks into smaller prompts and add checkpoints before long coding runs."
+    });
+  }
+
+  const highOutputProject = data.projects.find((project) => project.outputInputRatio > 2 && project.totalTokens > 5_000);
+  if (highOutputProject) {
+    insights.push({
+      id: "high-output-project",
+      severity: "medium",
+      problem: "One project uses unusually high output tokens.",
+      evidence: `${highOutputProject.project} has an output/input ratio of ${highOutputProject.outputInputRatio.toFixed(1)}x.`,
+      savingOpportunity: highOutputProject.cost ? `Potential review pool: $${highOutputProject.cost.toFixed(2)}.` : "Savings depend on configured pricing.",
+      recommendation: "Ask for concise diffs, summaries, or file-scoped edits when working in this project."
+    });
+  }
+
+  const cacheEfficiency =
+    data.summary.inputTokens + data.summary.cachedTokens
+      ? data.summary.cachedTokens / (data.summary.inputTokens + data.summary.cachedTokens)
+      : 0;
+  if (data.summary.inputTokens > 10_000 && cacheEfficiency < 0.05) {
+    insights.push({
+      id: "low-cache",
+      severity: "medium",
+      problem: "Cache usage is low.",
+      evidence: `Cached tokens are ${Math.round(cacheEfficiency * 100)}% of reusable input volume.`,
+      savingOpportunity: "Better context reuse can reduce repeated input-token spend on supported models.",
+      recommendation: "Keep stable instructions and repo context consistent across related runs where the CLI supports caching."
+    });
+  }
+
+  const costlyAlternative = data.models.find((model) => model.overuseFlag && model.suggestedAlternative);
+  if (costlyAlternative) {
+    insights.push({
+      id: "expensive-model-overuse",
+      severity: "medium",
+      problem: "Configured cheaper models may fit some low-complexity work.",
+      evidence: `${costlyAlternative.model} has ${costlyAlternative.totalTokens.toLocaleString()} tokens and ${costlyAlternative.suggestedAlternative} is cheaper in your pricing table.`,
+      savingOpportunity: costlyAlternative.cost ? `Candidate spend: $${costlyAlternative.cost.toFixed(2)}.` : "Savings require complete pricing.",
+      recommendation: "Use cheaper models for refactoring, search-heavy, or mechanical edits, and reserve expensive models for ambiguous architecture work."
+    });
+  }
+
+  if (data.trends.length >= 14) {
+    const last = data.trends.slice(-7).reduce((sum, day) => sum + day.totalTokens, 0) / 7;
+    const previous = data.trends.slice(-14, -7).reduce((sum, day) => sum + day.totalTokens, 0) / 7;
+    if (previous > 0 && last / previous > 1.25) {
+      insights.push({
+        id: "session-length-growing",
+        severity: "low",
+        problem: "Average usage is increasing.",
+        evidence: `Last 7-day average is ${Math.round((last / previous - 1) * 100)}% above the prior week.`,
+        savingOpportunity: "Reducing drift can slow recurring spend growth.",
+        recommendation: "Use planning prompts before long coding runs and prune stale context between unrelated tasks."
+      });
+    }
+  }
+
+  if (!insights.length) {
+    insights.push({
+      id: "baseline",
+      severity: "low",
+      problem: "No strong optimization pattern detected yet.",
+      evidence: "Scan more sessions or configure prices for richer recommendations.",
+      savingOpportunity: "Unknown until more local usage is imported.",
+      recommendation: "Run a scan after several CLI sessions and revisit this page."
+    });
+  }
+
+  return insights;
+}
+
+export function getAnalyticsData(): AnalyticsData {
+  const summary = getSummary();
+  const trends = getTrends();
+  const tools = getToolComparison();
+  const models = getModelRows();
+  const projects = getProjectRows();
+  const sessions = getSessions();
+  const insights = buildInsights({ summary, trends, models, projects, sessions });
+
+  return {
+    summary,
+    trends,
+    tools,
+    models,
+    projects,
+    sessions,
+    insights
+  };
+}
+
+export function getDebugData() {
+  const scanRuns = rows<DebugScanRun>(
+    `SELECT id, started_at AS startedAt, completed_at AS completedAt,
+      files_scanned AS filesScanned, records_imported AS recordsImported, warnings, errors
+     FROM scan_runs
+     ORDER BY started_at DESC
+     LIMIT 50`
+  ).map((row) => ({
+    ...row,
+    warnings: parseJson<string[]>(row.warnings, []),
+    errors: parseJson<string[]>(row.errors, [])
+  }));
+
+  const scanFiles = rows<DebugScanFile>(
+    `SELECT sf.id, sf.scan_run_id AS scanRunId, sf.path, sf.modified_time AS modifiedTime,
+      sf.size_bytes AS sizeBytes, sf.file_hash AS fileHash, sf.parser, sf.status,
+      sf.records_imported AS recordsImported, sf.warnings, sf.errors, sf.raw_metadata AS rawMetadata,
+      sr.started_at AS scanStartedAt
+     FROM scan_files sf
+     JOIN scan_runs sr ON sr.id = sf.scan_run_id
+     ORDER BY sr.started_at DESC, sf.path ASC
+     LIMIT 500`
+  ).map((row) => ({
+    ...row,
+    warnings: parseJson<string[]>(row.warnings, []),
+    errors: parseJson<string[]>(row.errors, []),
+    rawMetadata: parseJson<Record<string, unknown>>(row.rawMetadata, {})
+  }));
+
+  return { scanRuns, scanFiles };
+}

package/src/lib/cost.ts

@@ -0,0 +1,62 @@
+export type PriceConfig = {
+  inputTokenPrice: number | null;
+  outputTokenPrice: number | null;
+  cachedInputTokenPrice: number | null;
+  currency: string;
+};
+
+export type TokenUsageForCost = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  reasoningTokens: number;
+  estimatedTokens: boolean;
+};
+
+export type CostResult = {
+  amount: number | null;
+  currency: string;
+  estimated: boolean;
+  status: "exact" | "estimated" | "unknown";
+  explanation: string;
+};
+
+function pricePart(tokens: number, pricePerMillion: number | null | undefined) {
+  if (!tokens || pricePerMillion == null) return 0;
+  return (tokens * pricePerMillion) / 1_000_000;
+}
+
+export function calculateInteractionCost(
+  usage: TokenUsageForCost,
+  price: PriceConfig | null | undefined
+): CostResult {
+  if (!price || price.inputTokenPrice == null || price.outputTokenPrice == null) {
+    return {
+      amount: null,
+      currency: price?.currency ?? "USD",
+      estimated: usage.estimatedTokens,
+      status: "unknown",
+      explanation: "No complete model pricing is configured."
+    };
+  }
+
+  const input = pricePart(usage.inputTokens, price.inputTokenPrice);
+  const output = pricePart(usage.outputTokens + usage.reasoningTokens, price.outputTokenPrice);
+  const cacheRead = pricePart(
+    usage.cacheReadTokens,
+    price.cachedInputTokenPrice ?? price.inputTokenPrice
+  );
+  const cacheWrite = pricePart(usage.cacheWriteTokens, price.inputTokenPrice);
+  const amount = input + output + cacheRead + cacheWrite;
+
+  return {
+    amount,
+    currency: price.currency,
+    estimated: usage.estimatedTokens,
+    status: usage.estimatedTokens ? "estimated" : "exact",
+    explanation: usage.estimatedTokens
+      ? "Token counts were estimated before applying configured prices."
+      : "Exact token counts were multiplied by configured prices."
+  };
+}

package/src/lib/csv.ts

@@ -0,0 +1,15 @@
+function escapeCsv(value: unknown) {
+  if (value == null) return "";
+  const text = String(value);
+  if (!/[",\n\r]/.test(text)) return text;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+
+export function toCsv<T extends Record<string, unknown>>(rows: T[]) {
+  if (!rows.length) return "";
+  const headers = Object.keys(rows[0]);
+  return [
+    headers.map(escapeCsv).join(","),
+    ...rows.map((row) => headers.map((header) => escapeCsv(row[header])).join(","))
+  ].join("\n");
+}