@oar-sh/oar 0.9.0

package/server/services/oar-state-migration-service.mjs

@@ -0,0 +1,243 @@
+/**
+ * One-time migration of relay state into the OAR state root (~/.oar).
+ *
+ * Global npm installs cannot keep state under the package directory — `npm i -g`
+ * replaces the tree on every update, database included. This service copies the
+ * old state (a git-checkout's server/ tree, and/or the legacy managed config
+ * dir) into the state root exactly once, guarded by a marker file.
+ *
+ * Contract (docs/plans/oar-rebrand-and-release.md §5.2):
+ *  - refuse to run while a relay holds the source lock (live pid);
+ *  - checkpoint the WAL before copying, then copy db + -wal + -shm together;
+ *  - copy, never move — the source stays untouched as the rollback path;
+ *  - verify integrity and row counts before writing the marker;
+ *  - on any mismatch remove the partial target and leave the marker unwritten.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const MIGRATION_MARKER = '.migrated';
+const DB_FILE = 'copilot.db';
+const MAX_LOGS_BYTES = 50 * 1024 * 1024;
+
+export function resolveOarRoot(env = process.env, platform = process.platform) {
+  const override = String(env.OAR_STATE_ROOT || '').trim();
+  if (override) return path.resolve(override);
+  if (platform === 'win32') {
+    const appData = String(env.APPDATA || '').trim();
+    if (appData) return path.join(appData, 'oar');
+    const profile = String(env.USERPROFILE || '').trim();
+    return path.join(profile || os.homedir(), 'AppData', 'Roaming', 'oar');
+  }
+  return path.join(os.homedir(), '.oar');
+}
+
+function defaultIsProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readLockPid(lockPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    const pid = Number.parseInt(String(parsed?.pid ?? ''), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function directorySizeBytes(dir) {
+  let total = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries = [];
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) {
+        try { total += fs.statSync(full).size; } catch {}
+      }
+    }
+  }
+  return total;
+}
+
+function copyIfExists(source, target, copied) {
+  if (!source || !fs.existsSync(source)) return false;
+  const stat = fs.statSync(source);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (stat.isDirectory()) fs.cpSync(source, target, { recursive: true });
+  else fs.copyFileSync(source, target);
+  copied.push({ from: source, to: target, bytes: stat.isDirectory() ? directorySizeBytes(source) : stat.size });
+  return true;
+}
+
+async function loadDatabase(DatabaseImpl) {
+  if (DatabaseImpl) return DatabaseImpl;
+  const mod = await import('better-sqlite3');
+  return mod.default;
+}
+
+function readDbCounts(Database, dbPath, { checkpoint = false } = {}) {
+  const db = new Database(dbPath, checkpoint ? {} : { readonly: true });
+  try {
+    if (checkpoint) db.pragma('wal_checkpoint(TRUNCATE)');
+    const integrity = String(db.pragma('integrity_check', { simple: true }) || '');
+    const tableExists = (name) => !!db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?")
+      .get(name);
+    const countOf = (table) => (tableExists(table)
+      ? Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n || 0)
+      : null);
+    return {
+      integrity,
+      conversations: countOf('conversations'),
+      messages: countOf('messages'),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Returns { status, ... } — statuses: 'already-migrated', 'blocked-live-relay',
+ * 'nothing-to-migrate', 'migrated'. Throws only on verification failure or an
+ * unexpected copy error, after removing the partial target state.
+ */
+export async function migrateStateToOarRoot({
+  targetRoot,
+  repoServerDir = null,
+  managedConfigDir = null,
+  isProcessAliveImpl = defaultIsProcessAlive,
+  DatabaseImpl = null,
+  now = () => new Date().toISOString(),
+  logger = console,
+} = {}) {
+  const root = path.resolve(String(targetRoot || ''));
+  if (!root) throw new Error('targetRoot is required');
+  const markerPath = path.join(root, MIGRATION_MARKER);
+  if (fs.existsSync(markerPath)) return { status: 'already-migrated', root };
+
+  const sourceData = repoServerDir ? path.join(repoServerDir, 'data') : null;
+  const sourceDb = sourceData ? path.join(sourceData, DB_FILE) : null;
+  const sourceRepoConfig = repoServerDir ? path.join(repoServerDir, 'config.json') : null;
+  const sourceManagedConfig = managedConfigDir ? path.join(managedConfigDir, 'config.json') : null;
+
+  const lockPath = sourceData ? path.join(sourceData, 'relay-server.lock') : null;
+  if (lockPath && fs.existsSync(lockPath)) {
+    const pid = readLockPid(lockPath);
+    if (pid && isProcessAliveImpl(pid)) {
+      return {
+        status: 'blocked-live-relay',
+        root,
+        pid,
+        error: `A relay is still running (pid=${pid}, lock at ${lockPath}). Stop it, then run the migration again.`,
+      };
+    }
+  }
+
+  const hasDb = !!(sourceDb && fs.existsSync(sourceDb));
+  const hasAnyConfig = !!((sourceRepoConfig && fs.existsSync(sourceRepoConfig))
+    || (sourceManagedConfig && fs.existsSync(sourceManagedConfig)));
+  if (!hasDb && !hasAnyConfig) {
+    fs.mkdirSync(root, { recursive: true });
+    fs.writeFileSync(markerPath, `${now()} nothing-to-migrate\n`);
+    return { status: 'nothing-to-migrate', root };
+  }
+
+  const copied = [];
+  let sourceCounts = null;
+  try {
+    fs.mkdirSync(path.join(root, 'data'), { recursive: true });
+
+    if (hasDb) {
+      const Database = await loadDatabase(DatabaseImpl);
+      // Checkpoint first so recent writes leave the WAL, then copy all three
+      // files anyway — a hot -wal must never be dropped on the floor.
+      sourceCounts = readDbCounts(Database, sourceDb, { checkpoint: true });
+      copyIfExists(sourceDb, path.join(root, 'data', DB_FILE), copied);
+      copyIfExists(`${sourceDb}-wal`, path.join(root, 'data', `${DB_FILE}-wal`), copied);
+      copyIfExists(`${sourceDb}-shm`, path.join(root, 'data', `${DB_FILE}-shm`), copied);
+      copyIfExists(path.join(sourceData, 'cursor-agents'), path.join(root, 'data', 'cursor-agents'), copied);
+    }
+
+    // Repo config wins over the legacy managed config when both exist.
+    const configSource = (sourceRepoConfig && fs.existsSync(sourceRepoConfig))
+      ? sourceRepoConfig
+      : sourceManagedConfig;
+    copyIfExists(configSource, path.join(root, 'config.json'), copied);
+
+    if (repoServerDir) {
+      copyIfExists(path.join(repoServerDir, 'uploads'), path.join(root, 'uploads'), copied);
+      const repoLogs = path.join(repoServerDir, 'logs');
+      if (fs.existsSync(repoLogs) && directorySizeBytes(repoLogs) <= MAX_LOGS_BYTES) {
+        copyIfExists(repoLogs, path.join(root, 'logs'), copied);
+      }
+    }
+    if (managedConfigDir) {
+      const managedLogs = path.join(managedConfigDir, 'logs');
+      if (fs.existsSync(managedLogs) && directorySizeBytes(managedLogs) <= MAX_LOGS_BYTES) {
+        copyIfExists(managedLogs, path.join(root, 'logs'), copied);
+      }
+    }
+
+    if (hasDb) {
+      const Database = await loadDatabase(DatabaseImpl);
+      const targetCounts = readDbCounts(Database, path.join(root, 'data', DB_FILE));
+      const mismatch = targetCounts.integrity !== 'ok'
+        || targetCounts.conversations !== sourceCounts.conversations
+        || targetCounts.messages !== sourceCounts.messages;
+      if (mismatch) {
+        throw new Error(
+          `Migrated database failed verification (integrity=${targetCounts.integrity}, `
+          + `conversations ${targetCounts.conversations} vs ${sourceCounts.conversations}, `
+          + `messages ${targetCounts.messages} vs ${sourceCounts.messages}).`,
+        );
+      }
+    }
+  } catch (error) {
+    // Leave no partial target behind: the marker was never written, so the next
+    // attempt starts clean; the source was never touched.
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch {}
+    throw error;
+  }
+
+  const backupsDir = path.join(root, 'backups');
+  fs.mkdirSync(backupsDir, { recursive: true });
+  const receipt = [
+    '# OAR state migration',
+    '',
+    `- when: ${now()}`,
+    `- repo server dir: ${repoServerDir || '(none)'}`,
+    `- managed config dir: ${managedConfigDir || '(none)'}`,
+    ...(sourceCounts
+      ? [`- verified: integrity ok, ${sourceCounts.conversations} conversations, ${sourceCounts.messages} messages`]
+      : ['- verified: no database in source']),
+    '',
+    'Copied (sources left untouched — delete them manually once satisfied):',
+    ...copied.map((c) => `- ${c.from} -> ${c.to} (${c.bytes} bytes)`),
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(backupsDir, 'MIGRATION.md'), receipt);
+  fs.writeFileSync(markerPath, `${now()} migrated\n`);
+
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(root, 0o700);
+      const configTarget = path.join(root, 'config.json');
+      if (fs.existsSync(configTarget)) fs.chmodSync(configTarget, 0o600);
+    } catch {}
+  }
+
+  logger.log?.(`[oar] Migrated relay state into ${root} (${copied.length} items; sources untouched).`);
+  return { status: 'migrated', root, copied: copied.length, counts: sourceCounts };
+}

package/server/services/plan-usage-claude.mjs

@@ -0,0 +1,387 @@
+'use strict';
+
+/**
+ * Claude subscription plan usage.
+ *
+ * Source is the Agent SDK's structured `/usage` control response
+ * (`SDKControlGetUsageResponse`), which is explicitly marked EXPERIMENTAL by
+ * the SDK. Everything here is therefore written defensively: each window is
+ * optional, the whole `rate_limits` block can be null (API-key, Bedrock and
+ * Vertex sessions have no plan limits at all), and a shape change must degrade
+ * to "fewer meters" rather than throw.
+ *
+ * When the experimental call is unavailable the worker still reports the
+ * stable `modelUsage` / `total_cost_usd` result fields, which render as session
+ * cost details with no plan meters.
+ */
+
+import {
+  SOURCE_CACHE,
+  SOURCE_WORKER,
+  STATUS_NOT_CONFIGURED,
+  STATUS_OK,
+  STATUS_PARTIAL,
+  STATUS_UNAVAILABLE,
+  buildDetailSection,
+  buildMeter,
+  buildProviderCard,
+  buildUnavailableCard,
+  clampPercent,
+  roundCurrency,
+  toFiniteNumber,
+  toIsoTimestamp,
+  toTrimmedString,
+} from './plan-usage-contract.mjs';
+
+export const CLAUDE_PROVIDER_ID = 'claude';
+export const CLAUDE_LABEL = 'Claude';
+
+const CLAUDE_USAGE_URL = 'https://claude.ai/settings/usage';
+
+// Fixed windows, in display order. Model-scoped windows are appended after
+// these from the server-supplied `model_scoped[]` array.
+const WINDOW_LABELS = [
+  ['five_hour', 'Current session (5 h)', 'primary'],
+  ['seven_day', 'Weekly limit', 'primary'],
+  ['seven_day_sonnet', 'Weekly Sonnet', 'secondary'],
+  ['seven_day_opus', 'Weekly Opus', 'secondary'],
+  ['seven_day_oauth_apps', 'Weekly (OAuth apps)', 'secondary'],
+];
+
+function normalizeWindow(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const utilization = clampPercent(raw.utilization);
+  const resetsAt = toIsoTimestamp(raw.resets_at);
+  if (utilization === null && !resetsAt) return null;
+  return { utilization, resetsAt };
+}
+
+function normalizeModelUsageMap(rawModelUsage) {
+  if (!rawModelUsage || typeof rawModelUsage !== 'object') return [];
+  return Object.entries(rawModelUsage)
+    .map(([model, usage]) => {
+      if (!usage || typeof usage !== 'object') return null;
+      return {
+        model: toTrimmedString(model),
+        inputTokens: toFiniteNumber(usage.inputTokens),
+        outputTokens: toFiniteNumber(usage.outputTokens),
+        cacheReadTokens: toFiniteNumber(usage.cacheReadInputTokens),
+        cacheWriteTokens: toFiniteNumber(usage.cacheCreationInputTokens),
+        webSearchRequests: toFiniteNumber(usage.webSearchRequests),
+        costUsd: toFiniteNumber(usage.costUSD),
+        contextWindow: toFiniteNumber(usage.contextWindow),
+      };
+    })
+    .filter((entry) => entry && entry.model);
+}
+
+function normalizeAttribution(list) {
+  return (Array.isArray(list) ? list : [])
+    .map((entry) => {
+      const name = toTrimmedString(entry?.name) || toTrimmedString(entry?.key);
+      const pct = clampPercent(entry?.pct);
+      if (!name || pct === null) return null;
+      return { name, pct, count: toFiniteNumber(entry?.count) };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.pct - a.pct);
+}
+
+function normalizeBehaviorWindow(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const window = {
+    requestCount: toFiniteNumber(raw.request_count),
+    sessionCount: toFiniteNumber(raw.session_count),
+    behaviors: normalizeAttribution(raw.behaviors),
+    agents: normalizeAttribution(raw.agents),
+    skills: normalizeAttribution(raw.skills),
+    plugins: normalizeAttribution(raw.plugins),
+    mcpServers: normalizeAttribution(raw.mcp_servers),
+  };
+  const hasSignal = window.requestCount !== null
+    || window.sessionCount !== null
+    || window.behaviors.length
+    || window.agents.length
+    || window.skills.length
+    || window.plugins.length
+    || window.mcpServers.length;
+  return hasSignal ? window : null;
+}
+
+/**
+ * Normalize the raw experimental response into the payload the relay persists.
+ * Returns null when nothing usable is present, so callers never store noise.
+ */
+export function normalizeClaudePlanUsage(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const rawSession = raw.session && typeof raw.session === 'object' ? raw.session : null;
+  const session = rawSession
+    ? {
+      totalCostUsd: toFiniteNumber(rawSession.total_cost_usd),
+      totalApiDurationMs: toFiniteNumber(rawSession.total_api_duration_ms),
+      totalDurationMs: toFiniteNumber(rawSession.total_duration_ms),
+      totalLinesAdded: toFiniteNumber(rawSession.total_lines_added),
+      totalLinesRemoved: toFiniteNumber(rawSession.total_lines_removed),
+      modelUsage: normalizeModelUsageMap(rawSession.model_usage),
+    }
+    : null;
+
+  const rawLimits = raw.rate_limits && typeof raw.rate_limits === 'object' ? raw.rate_limits : null;
+  const windows = [];
+  if (rawLimits) {
+    for (const [key, label, emphasis] of WINDOW_LABELS) {
+      const normalized = normalizeWindow(rawLimits[key]);
+      if (normalized) windows.push({ id: key, label, emphasis, ...normalized });
+    }
+    for (const entry of (Array.isArray(rawLimits.model_scoped) ? rawLimits.model_scoped : [])) {
+      const normalized = normalizeWindow(entry);
+      const displayName = toTrimmedString(entry?.display_name);
+      if (!normalized || !displayName) continue;
+      windows.push({
+        id: `model_scoped:${displayName.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+        label: `Weekly ${displayName}`,
+        emphasis: 'secondary',
+        ...normalized,
+      });
+    }
+  }
+
+  const rawExtra = rawLimits?.extra_usage && typeof rawLimits.extra_usage === 'object'
+    ? rawLimits.extra_usage
+    : null;
+  const extraUsage = rawExtra
+    ? {
+      isEnabled: rawExtra.is_enabled === true,
+      monthlyLimit: toFiniteNumber(rawExtra.monthly_limit),
+      usedCredits: toFiniteNumber(rawExtra.used_credits),
+      utilization: clampPercent(rawExtra.utilization),
+      currency: toTrimmedString(rawExtra.currency),
+    }
+    : null;
+
+  const rawBehaviors = raw.behaviors && typeof raw.behaviors === 'object' ? raw.behaviors : null;
+  const behaviors = rawBehaviors
+    ? {
+      day: normalizeBehaviorWindow(rawBehaviors.day),
+      week: normalizeBehaviorWindow(rawBehaviors.week),
+    }
+    : null;
+
+  const payload = {
+    subscriptionType: toTrimmedString(raw.subscription_type),
+    rateLimitsAvailable: raw.rate_limits_available === true,
+    windows,
+    extraUsage,
+    session,
+    behaviors: behaviors && (behaviors.day || behaviors.week) ? behaviors : null,
+  };
+  const hasSignal = payload.windows.length
+    || payload.extraUsage
+    || payload.session
+    || payload.behaviors
+    || payload.subscriptionType;
+  return hasSignal ? payload : null;
+}
+
+/** Build the fallback payload from the stable result-message fields. */
+export function claudePlanUsageFromResult({ modelUsage = null, totalCostUsd = null } = {}) {
+  const models = normalizeModelUsageMap(modelUsage);
+  const cost = toFiniteNumber(totalCostUsd);
+  if (!models.length && cost === null) return null;
+  return {
+    subscriptionType: null,
+    rateLimitsAvailable: false,
+    windows: [],
+    extraUsage: null,
+    session: {
+      totalCostUsd: cost,
+      totalApiDurationMs: null,
+      totalDurationMs: null,
+      totalLinesAdded: null,
+      totalLinesRemoved: null,
+      modelUsage: models,
+    },
+    behaviors: null,
+  };
+}
+
+function formatDuration(ms) {
+  const value = toFiniteNumber(ms);
+  if (value === null || value < 0) return null;
+  const totalSeconds = Math.round(value / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}
+
+function formatTokens(value) {
+  const numeric = toFiniteNumber(value);
+  if (numeric === null) return null;
+  const abs = Math.abs(numeric);
+  if (abs < 1000) return String(Math.round(numeric));
+  if (abs < 1_000_000) return `${(numeric / 1000).toFixed(1)}k`;
+  return `${(numeric / 1_000_000).toFixed(1)}M`;
+}
+
+function formatUsd(value) {
+  const numeric = roundCurrency(value);
+  return numeric === null ? null : `$${numeric.toFixed(2)}`;
+}
+
+function attributionRows(entries, limit = 6) {
+  return entries.slice(0, limit).map((entry) => ({
+    label: entry.name,
+    value: `${entry.pct.toFixed(1)}%`,
+    hint: entry.count === null ? null : `${entry.count} requests`,
+  }));
+}
+
+function behaviorSections(behaviors) {
+  if (!behaviors) return [];
+  const sections = [];
+  for (const [key, window, windowLabel] of [
+    ['day', behaviors.day, 'Last 24 hours'],
+    ['week', behaviors.week, 'Last 7 days'],
+  ]) {
+    if (!window) continue;
+    const rows = [];
+    if (window.requestCount !== null) rows.push({ label: 'API requests', value: String(window.requestCount) });
+    if (window.sessionCount !== null) rows.push({ label: 'Sessions', value: String(window.sessionCount) });
+    for (const entry of window.behaviors.slice(0, 6)) {
+      rows.push({ label: entry.name, value: `${entry.pct.toFixed(1)}%`, hint: entry.count === null ? null : `${entry.count} requests` });
+    }
+    sections.push(buildDetailSection({
+      id: `claude-behaviors-${key}`,
+      label: `What is driving usage — ${windowLabel}`,
+      // The SDK is explicit that this comes from a local transcript scan, so it
+      // must not be presented as an account-wide figure.
+      note: 'Approximate, from local transcripts on this machine only. Categories overlap.',
+      rows,
+    }));
+
+    for (const [attrKey, attrLabel, list] of [
+      ['agents', 'Agents', window.agents],
+      ['skills', 'Skills', window.skills],
+      ['plugins', 'Plugins', window.plugins],
+      ['mcp', 'MCP servers', window.mcpServers],
+    ]) {
+      if (!list.length) continue;
+      sections.push(buildDetailSection({
+        id: `claude-${attrKey}-${key}`,
+        label: `${attrLabel} — ${windowLabel}`,
+        rows: attributionRows(list),
+      }));
+    }
+  }
+  return sections;
+}
+
+export function buildClaudePlanCard({
+  usage = null,
+  capturedAt = null,
+  stale = false,
+  configured = true,
+  message = null,
+} = {}) {
+  if (!configured) {
+    return buildUnavailableCard({
+      provider: CLAUDE_PROVIDER_ID,
+      label: CLAUDE_LABEL,
+      status: STATUS_NOT_CONFIGURED,
+      message: 'Claude is not enabled in provider settings.',
+    });
+  }
+  if (!usage) {
+    return buildUnavailableCard({
+      provider: CLAUDE_PROVIDER_ID,
+      label: CLAUDE_LABEL,
+      status: STATUS_UNAVAILABLE,
+      message: toTrimmedString(message)
+        || 'No Claude usage captured yet. Run a Claude turn — usage is read from the live session and never from a hidden extra turn.',
+      links: [{ label: 'Claude usage settings', url: CLAUDE_USAGE_URL }],
+    });
+  }
+
+  const meters = [];
+  for (const window of (Array.isArray(usage.windows) ? usage.windows : [])) {
+    meters.push(buildMeter({
+      id: `claude-${window.id}`,
+      label: window.label,
+      unit: 'percent',
+      utilization: window.utilization,
+      resetAt: window.resetsAt,
+      emphasis: window.emphasis === 'secondary' ? 'secondary' : 'primary',
+    }));
+  }
+
+  const extra = usage.extraUsage;
+  if (extra && (extra.isEnabled || extra.usedCredits !== null || extra.monthlyLimit !== null)) {
+    meters.push(buildMeter({
+      id: 'claude-extra-usage',
+      label: 'Extra usage credits',
+      unit: extra.currency && extra.currency.toUpperCase() !== 'USD' ? 'credits' : 'usd',
+      used: extra.usedCredits,
+      allowance: extra.monthlyLimit,
+      utilization: extra.utilization,
+      note: extra.isEnabled ? null : 'Extra usage is disabled for this account',
+      emphasis: 'secondary',
+    }));
+  }
+
+  const details = [];
+  const session = usage.session;
+  if (session) {
+    const rows = [];
+    const cost = formatUsd(session.totalCostUsd);
+    if (cost) rows.push({ label: 'Session cost (estimate)', value: cost, hint: 'Client-side estimate, not a billing statement' });
+    const apiDuration = formatDuration(session.totalApiDurationMs);
+    if (apiDuration) rows.push({ label: 'API time', value: apiDuration });
+    const wallDuration = formatDuration(session.totalDurationMs);
+    if (wallDuration) rows.push({ label: 'Wall-clock time', value: wallDuration });
+    if (session.totalLinesAdded !== null) rows.push({ label: 'Lines added', value: String(session.totalLinesAdded) });
+    if (session.totalLinesRemoved !== null) rows.push({ label: 'Lines removed', value: String(session.totalLinesRemoved) });
+    const sessionSection = buildDetailSection({ id: 'claude-session', label: 'Latest session totals', rows });
+    if (sessionSection) details.push(sessionSection);
+
+    const modelRows = (session.modelUsage || []).map((entry) => ({
+      label: entry.model,
+      value: formatUsd(entry.costUsd) ?? '—',
+      hint: [
+        formatTokens(entry.inputTokens) ? `in ${formatTokens(entry.inputTokens)}` : null,
+        formatTokens(entry.outputTokens) ? `out ${formatTokens(entry.outputTokens)}` : null,
+        formatTokens(entry.cacheReadTokens) ? `cache r ${formatTokens(entry.cacheReadTokens)}` : null,
+        formatTokens(entry.cacheWriteTokens) ? `cache w ${formatTokens(entry.cacheWriteTokens)}` : null,
+      ].filter(Boolean).join(' · ') || null,
+    }));
+    const modelSection = buildDetailSection({ id: 'claude-models', label: 'By model (session)', rows: modelRows });
+    if (modelSection) details.push(modelSection);
+  }
+
+  details.push(...behaviorSections(usage.behaviors).filter(Boolean));
+
+  const resolvedMeters = meters.filter(Boolean);
+  const planLimitsMissing = !resolvedMeters.length;
+  return buildProviderCard({
+    provider: CLAUDE_PROVIDER_ID,
+    label: CLAUDE_LABEL,
+    status: planLimitsMissing ? STATUS_PARTIAL : STATUS_OK,
+    planName: usage.subscriptionType
+      ? `${usage.subscriptionType.charAt(0).toUpperCase()}${usage.subscriptionType.slice(1)}`
+      : null,
+    message: planLimitsMissing
+      ? (usage.rateLimitsAvailable
+        ? 'Plan rate limits were not reported for this session.'
+        : 'This session authenticates without claude.ai plan limits (API key or third-party provider), so only session cost is available.')
+      : null,
+    source: stale ? SOURCE_CACHE : SOURCE_WORKER,
+    stale,
+    capturedAt,
+    meters: resolvedMeters,
+    details,
+    links: [{ label: 'Claude usage settings', url: CLAUDE_USAGE_URL }],
+  });
+}