@selesai/code 0.6.3 → 0.8.0

package/dist/extensions/pi-powerline-footer/bash-mode/history.ts

@@ -1,7 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-import { getAgentDir } from "@selesai/code";
+import { getAgentPath, getHomeDir } from "../paths.ts";
 
 interface PersistedHistoryEntry {
   command: string;
@@ -9,12 +8,31 @@ interface PersistedHistoryEntry {
   timestamp: number;
 }
 
-function getHomeDir(): string {
-  return process.env.HOME || process.env.USERPROFILE || homedir();
+// mode and ctimeMs are part of the fingerprint so permission/ACL transitions
+// (e.g. chmod 000) invalidate the cache even when content is unchanged.
+interface FileFingerprint {
+  ctimeMs: number;
+  mtimeMs: number;
+  mode: number;
+  size: number;
 }
 
+interface CachedHistory<T> extends FileFingerprint {
+  entries: T;
+}
+
+function matchesFingerprint(cached: FileFingerprint, stat: FileFingerprint): boolean {
+  return cached.ctimeMs === stat.ctimeMs
+    && cached.mtimeMs === stat.mtimeMs
+    && cached.mode === stat.mode
+    && cached.size === stat.size;
+}
+
+const projectHistoryCache = new Map<string, CachedHistory<PersistedHistoryEntry[]>>();
+const globalHistoryCache = new Map<string, CachedHistory<string[]>>();
+
 function getHistoryDir(): string {
-  return join(getAgentDir(), "powerline-footer", "bash-history");
+  return getAgentPath("powerline-footer", "bash-history");
 }
 
 function projectKey(cwd: string): string {
@@ -44,13 +62,30 @@ function normalizePersistedEntries(value: unknown): PersistedHistoryEntry[] {
 
 export function readProjectHistory(cwd: string): PersistedHistoryEntry[] {
   const filePath = projectHistoryPath(cwd);
-  if (!existsSync(filePath)) return [];
+  if (!existsSync(filePath)) {
+    projectHistoryCache.delete(filePath);
+    return [];
+  }
 
   try {
+    const stat = statSync(filePath);
+    const cached = projectHistoryCache.get(filePath);
+    if (cached && matchesFingerprint(cached, stat)) {
+      return cached.entries;
+    }
+
     const parsed = JSON.parse(readFileSync(filePath, "utf8"));
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
-    return normalizePersistedEntries((parsed as { entries?: unknown }).entries)
+    const entries = normalizePersistedEntries((parsed as { entries?: unknown }).entries)
       .sort((a, b) => b.timestamp - a.timestamp);
+    projectHistoryCache.set(filePath, {
+      ctimeMs: stat.ctimeMs,
+      mtimeMs: stat.mtimeMs,
+      mode: stat.mode,
+      size: stat.size,
+      entries,
+    });
+    return entries;
   } catch (error) {
     // Project history is a best-effort cache. If it is unreadable or malformed,
     // bash mode should keep working instead of failing command entry entirely.
@@ -67,12 +102,23 @@ export function appendProjectHistory(cwd: string, command: string, entryCwd: str
   const next: PersistedHistoryEntry[] = [
     { command: normalizedCommand, cwd: entryCwd, timestamp: Date.now() },
     ...existing.filter((entry) => entry.command !== normalizedCommand),
-  ].slice(0, 500);
+  ]
+    .slice(0, 500)
+    .sort((a, b) => b.timestamp - a.timestamp);
 
   const filePath = projectHistoryPath(cwd);
+  projectHistoryCache.delete(filePath);
   try {
     mkdirSync(dirname(filePath), { recursive: true });
     writeFileSync(filePath, JSON.stringify({ version: 1, entries: next }, null, 2) + "\n");
+    const stat = statSync(filePath);
+    projectHistoryCache.set(filePath, {
+      ctimeMs: stat.ctimeMs,
+      mtimeMs: stat.mtimeMs,
+      mode: stat.mode,
+      size: stat.size,
+      entries: next,
+    });
   } catch (error) {
     // History persistence should never block a successful shell command from completing.
     console.debug(`[powerline-footer] Failed to persist bash project history to ${filePath}:`, error);
@@ -105,31 +151,37 @@ function parseFishHistory(raw: string): string[] {
 export function readGlobalShellHistory(shellPath: string): string[] {
   const shellName = shellPath.split("/").pop()?.toLowerCase() ?? "";
   const home = getHomeDir();
+  const filePath = shellName.includes("fish")
+    ? join(home, ".local", "share", "fish", "fish_history")
+    : process.env.HISTFILE || join(home, shellName.includes("zsh") ? ".zsh_history" : ".bash_history");
+  const cacheKey = `${shellName}\0${filePath}`;
 
-  try {
-    if (shellName.includes("zsh")) {
-      const filePath = process.env.HISTFILE || join(home, ".zsh_history");
-      if (!existsSync(filePath)) return [];
-      return readFileSync(filePath, "utf8")
-        .split("\n")
-        .map(parseZshHistoryLine)
-        .filter((entry): entry is string => Boolean(entry))
-        .reverse();
-    }
+  if (!existsSync(filePath)) {
+    globalHistoryCache.delete(cacheKey);
+    return [];
+  }
 
-    if (shellName.includes("fish")) {
-      const filePath = join(home, ".local", "share", "fish", "fish_history");
-      if (!existsSync(filePath)) return [];
-      return parseFishHistory(readFileSync(filePath, "utf8")).reverse();
+  let stat: FileFingerprint | undefined;
+  try {
+    stat = statSync(filePath);
+    const cached = globalHistoryCache.get(cacheKey);
+    if (cached && matchesFingerprint(cached, stat)) {
+      return cached.entries;
     }
 
-    const filePath = process.env.HISTFILE || join(home, ".bash_history");
-    if (!existsSync(filePath)) return [];
-    return parseBashHistory(readFileSync(filePath, "utf8").split("\n")).reverse();
+    const raw = readFileSync(filePath, "utf8");
+    const entries = shellName.includes("zsh")
+      ? raw.split("\n").map(parseZshHistoryLine).filter((entry): entry is string => Boolean(entry)).reverse()
+      : shellName.includes("fish")
+        ? parseFishHistory(raw).reverse()
+        : parseBashHistory(raw.split("\n")).reverse();
+    globalHistoryCache.set(cacheKey, { ...stat, entries });
+    return entries;
   } catch (error) {
-    // Global shell history is optional recall data. If it is unavailable, shell predictions
-    // should degrade to other sources instead of failing the editor.
-    console.debug(`[powerline-footer] Failed to read global shell history for ${shellName}:`, error);
+    if (stat) {
+      globalHistoryCache.set(cacheKey, { ...stat, entries: [] });
+      console.debug(`[powerline-footer] Failed to read global shell history for ${shellName}:`, error);
+    }
     return [];
   }
 }

package/dist/extensions/pi-powerline-footer/bash-mode/types.ts

@@ -1,5 +1,5 @@
 export interface BashModeSettings {
-  toggleShortcut: string;
+  toggleShortcut: string | null;
   transcriptMaxLines: number;
   transcriptMaxBytes: number;
 }

package/dist/extensions/pi-powerline-footer/cd-command.ts

@@ -0,0 +1,190 @@
+import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { SessionManager, type ExtensionAPI, type ExtensionCommandContext } from "@selesai/code";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+function stripMatchingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+function unescapePathArg(value: string): string {
+  return stripMatchingQuotes(value).replace(/\\(.)/g, "$1");
+}
+
+function expandHomePath(value: string, homeDir = homedir()): string {
+  if (value === "~") return homeDir;
+  if (value.startsWith("~/")) return join(homeDir, value.slice(2));
+  return value;
+}
+
+function escapeCompletionPath(value: string): string {
+  return value.replace(/([\\\s"'`$&|;<>()[\]{}?!*])/g, "\\$1");
+}
+
+function displayPath(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+export function resolveCdTarget(args: string, cwd: string, homeDir = homedir()): { path: string } | { error: string } | null {
+  const input = unescapePathArg(args);
+  if (!input) return null;
+
+  const expanded = expandHomePath(input, homeDir);
+  const target = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+
+  if (!existsSync(target)) {
+    return { error: `Directory does not exist: ${target}` };
+  }
+
+  try {
+    if (!statSync(target).isDirectory()) {
+      return { error: `Not a directory: ${target}` };
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: `Cannot access directory: ${message}` };
+  }
+
+  return { path: target };
+}
+
+function pathBase(token: string, cwd: string, homeDir: string): { dir: string; prefix: string; displayPrefix: string } {
+  const unescaped = unescapePathArg(token);
+  const expanded = expandHomePath(unescaped, homeDir);
+  const hasSlash = expanded.includes("/");
+
+  if (!hasSlash) {
+    return { dir: cwd, prefix: expanded, displayPrefix: "" };
+  }
+
+  const baseDir = expanded.endsWith("/") ? expanded.slice(0, -1) : dirname(expanded);
+  const dir = isAbsolute(baseDir) ? baseDir : resolve(cwd, baseDir);
+  const prefix = expanded.endsWith("/") ? "" : basename(expanded);
+  const displayPrefix = unescaped.endsWith("/") ? unescaped : unescaped.slice(0, Math.max(0, unescaped.length - prefix.length));
+  return { dir, prefix, displayPrefix };
+}
+
+function isDirectoryEntry(dir: string, name: string): boolean {
+  try {
+    return statSync(join(dir, name)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function getCdArgumentCompletions(argumentPrefix: string, cwd: string, homeDir = homedir()): AutocompleteItem[] {
+  const prefix = argumentPrefix.trimStart();
+  const suggestions: AutocompleteItem[] = [];
+
+  for (const quickPick of ["../", "~/"]) {
+    if (!prefix || quickPick.startsWith(prefix)) {
+      suggestions.push({ value: quickPick, label: quickPick, description: quickPick === "../" ? "Parent directory" : "Home directory" });
+    }
+  }
+
+  const { dir, prefix: entryPrefix, displayPrefix } = pathBase(prefix, cwd, homeDir);
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.name.startsWith(entryPrefix) && (entry.isDirectory() || entry.isSymbolicLink() && isDirectoryEntry(dir, entry.name)))
+      .slice(0, 50)
+      .map((entry) => {
+        const path = displayPath(`${displayPrefix}${entry.name}/`);
+        return {
+          value: escapeCompletionPath(path),
+          label: path,
+        } satisfies AutocompleteItem;
+      });
+
+    suggestions.push(...entries);
+  } catch {
+    return suggestions;
+  }
+
+  const seen = new Set<string>();
+  return suggestions.filter((item) => {
+    if (seen.has(item.value)) return false;
+    seen.add(item.value);
+    return true;
+  });
+}
+
+function removeSessionFile(filePath: string | undefined): void {
+  if (!filePath) return;
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Best-effort cleanup only; the command still reports the cancellation/error.
+  }
+}
+
+export async function runCdCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const resolved = resolveCdTarget(args, ctx.cwd);
+  if (resolved === null) {
+    ctx.ui.notify(ctx.cwd, "info");
+    return;
+  }
+  if ("error" in resolved) {
+    ctx.ui.notify(resolved.error, "error");
+    return;
+  }
+  if (resolved.path === ctx.cwd) {
+    ctx.ui.notify(`Already in ${ctx.cwd}`, "info");
+    return;
+  }
+
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) {
+    ctx.ui.notify("/cd requires a persisted Pi session", "error");
+    return;
+  }
+
+  await ctx.waitForIdle();
+  const nextSession = SessionManager.forkFrom(sessionFile, resolved.path);
+  const nextSessionFile = nextSession.getSessionFile();
+
+  try {
+    const result = await ctx.switchSession(nextSessionFile!, {
+      withSession: async (nextCtx) => {
+        try {
+          process.chdir(nextCtx.cwd);
+          nextCtx.ui.notify(`Changed directory to ${nextCtx.cwd}`, "info");
+          nextCtx.ui.setTitle(`pi - ${basename(nextCtx.cwd) || nextCtx.cwd}`);
+        } catch (error) {
+          console.debug("[powerline-footer] Failed to update process cwd after /cd:", error);
+        }
+      },
+    });
+    if (result.cancelled) {
+      removeSessionFile(nextSessionFile);
+      ctx.ui.notify("Directory change cancelled", "warning");
+      return;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+      ctx.ui.notify(`Failed to change directory: ${message}`, "error");
+    } catch {
+      console.debug("[powerline-footer] Failed to report /cd error:", error);
+    }
+  }
+}
+
+export function registerCdCommand(pi: ExtensionAPI, getCwd: () => string): void {
+  pi.registerCommand("cd", {
+    description: "Switch the Pi session working directory",
+    getArgumentCompletions(argumentPrefix) {
+      return getCdArgumentCompletions(argumentPrefix, getCwd());
+    },
+    handler: runCdCommand,
+  });
+}

package/dist/extensions/pi-powerline-footer/colors.ts

@@ -32,10 +32,11 @@ const THEME = {
   path: "#00afaf",        // Teal/cyan
   gitClean: "#5faf5f",    // Green
   accent: "#febc38",      // Orange
+  queue: "#febc38",       // Orange
 };
 
 // Color name to ANSI code mapping
-type ColorName = "sep" | "model" | "path" | "gitClean" | "accent";
+type ColorName = keyof typeof THEME;
 
 function getAnsiCode(color: ColorName): string {
   const value = THEME[color as keyof typeof THEME];

package/dist/extensions/pi-powerline-footer/context-usage.ts

@@ -1,11 +1,123 @@
-interface CoreContextUsage {
-  contextTokens: number;
+import { estimateTokens, sessionEntryToContextMessages, type SessionEntry } from "@selesai/code";
+
+export interface CoreContextUsage {
+  contextTokens: number | null;
   contextWindow: number;
-  contextPercent: number;
+  contextPercent: number | null;
+}
+
+interface DisplayContextUsageInput {
+  coreContextUsage: CoreContextUsage | null;
+  unknownCoreFallback: CoreContextUsage | null;
+  fallbackContextTokens: number;
+  fallbackContextWindow: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+interface ContextUsageSource {
+  sessionManager: {
+    getLeafId(): string | null;
+  };
+  getContextUsage(): unknown;
+}
+
+interface UnknownContextEstimateSource {
+  sessionManager: {
+    buildContextEntries(): SessionEntry[];
+  };
+  getContextUsage(): unknown;
+  getSystemPrompt(): string;
+}
+
+function isContextUsageSource(value: unknown): value is ContextUsageSource {
+  if (!isRecord(value) || typeof value.getContextUsage !== "function" || !isRecord(value.sessionManager)) {
+    return false;
+  }
+  return typeof value.sessionManager.getLeafId === "function";
+}
+
+function isUnknownContextEstimateSource(value: unknown): value is UnknownContextEstimateSource {
+  return isRecord(value)
+    && typeof value.getContextUsage === "function"
+    && typeof value.getSystemPrompt === "function"
+    && isRecord(value.sessionManager)
+    && typeof value.sessionManager.buildContextEntries === "function";
+}
+
+export class CoreContextUsageCache {
+  private sessionManager: ContextUsageSource["sessionManager"] | null = null;
+  private leafId: string | null = null;
+  private usage: CoreContextUsage | null = null;
+
+  get(ctx: unknown): CoreContextUsage | null {
+    if (!isContextUsageSource(ctx)) return readCoreContextUsage(ctx);
+
+    const sessionManager = ctx.sessionManager;
+    const leafId = sessionManager.getLeafId();
+    // A reset cache holds sessionManager === null, which never matches a live one.
+    if (this.sessionManager !== sessionManager || this.leafId !== leafId) {
+      this.sessionManager = sessionManager;
+      this.leafId = leafId;
+      this.usage = readCoreContextUsage(ctx);
+    }
+    return this.usage;
+  }
+
+  reset(): void {
+    this.sessionManager = null;
+    this.leafId = null;
+    this.usage = null;
+  }
+}
+
+export function estimateInitialContextTokens(ctx: unknown): number | null {
+  if (!isRecord(ctx) || typeof ctx.getSystemPrompt !== "function") {
+    return null;
+  }
+
+  const prompt = ctx.getSystemPrompt();
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    return null;
+  }
+
+  return Math.ceil(prompt.length / 4);
+}
+
+export function resolveDisplayContextUsage({
+  coreContextUsage,
+  unknownCoreFallback,
+  fallbackContextTokens,
+  fallbackContextWindow,
+}: DisplayContextUsageInput): CoreContextUsage {
+  if (coreContextUsage?.contextTokens === null && unknownCoreFallback) return unknownCoreFallback;
+  if (coreContextUsage) return coreContextUsage;
+
+  return {
+    contextTokens: fallbackContextTokens,
+    contextWindow: fallbackContextWindow,
+    contextPercent: fallbackContextWindow > 0 ? (fallbackContextTokens / fallbackContextWindow) * 100 : 0,
+  };
+}
+
+export function estimateUnknownContextUsage(ctx: unknown): CoreContextUsage | null {
+  if (!isUnknownContextEstimateSource(ctx)) return null;
+
+  const coreContextUsage = readCoreContextUsage(ctx);
+  if (!coreContextUsage || coreContextUsage.contextTokens !== null) return null;
+
+  const messageTokens = ctx.sessionManager.buildContextEntries()
+    .flatMap(sessionEntryToContextMessages)
+    .reduce((total, message) => total + estimateTokens(message), 0);
+  const contextTokens = (estimateInitialContextTokens(ctx) ?? 0) + messageTokens;
+
+  return {
+    contextTokens,
+    contextWindow: coreContextUsage.contextWindow,
+    contextPercent: (contextTokens / coreContextUsage.contextWindow) * 100,
+  };
 }
 
 export function readCoreContextUsage(ctx: unknown): CoreContextUsage | null {
@@ -21,8 +133,7 @@ export function readCoreContextUsage(ctx: unknown): CoreContextUsage | null {
   const tokens = usage.tokens;
   const contextWindow = usage.contextWindow;
   if (
-    typeof tokens !== "number"
-    || !Number.isFinite(tokens)
+    !(tokens === null || (typeof tokens === "number" && Number.isFinite(tokens)))
     || typeof contextWindow !== "number"
     || !Number.isFinite(contextWindow)
     || contextWindow <= 0
@@ -30,6 +141,10 @@ export function readCoreContextUsage(ctx: unknown): CoreContextUsage | null {
     return null;
   }
 
+  if (tokens === null) {
+    return { contextTokens: null, contextWindow, contextPercent: null };
+  }
+
   const percent = usage.percent;
   return {
     contextTokens: tokens,

package/dist/extensions/pi-powerline-footer/currency-rates.ts

@@ -0,0 +1,142 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getAgentPath } from "./paths.ts";
+
+export const SUPPORTED_COST_CURRENCIES = ["USD", "CNY", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "INR", "KRW"] as const;
+export type CostCurrencyCode = typeof SUPPORTED_COST_CURRENCIES[number];
+
+const CURRENCY_SYMBOLS: Record<CostCurrencyCode, string> = {
+  USD: "$",
+  CNY: "¥",
+  EUR: "€",
+  GBP: "£",
+  JPY: "¥",
+  CAD: "CA$",
+  AUD: "A$",
+  CHF: "CHF ",
+  INR: "₹",
+  KRW: "₩",
+};
+
+const RATE_TTL_MS = 24 * 60 * 60 * 1000;
+const RATE_URL = "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/usd.min.json";
+const RATE_CACHE_PATH = getAgentPath("powerline-footer", "currency-rates.json");
+
+type RateTable = Partial<Record<CostCurrencyCode, number>>;
+
+interface CachedRates {
+  timestamp: number;
+  rates: RateTable;
+}
+
+let cachedRates: CachedRates | null = null;
+let pendingFetch: Promise<void> | null = null;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function normalizeCostCurrency(value: unknown): CostCurrencyCode | undefined {
+  if (typeof value !== "string") return undefined;
+  const code = value.trim().toUpperCase();
+  return (SUPPORTED_COST_CURRENCIES as readonly string[]).includes(code) ? code as CostCurrencyCode : undefined;
+}
+
+function parseCachedRates(value: unknown): CachedRates | null {
+  if (!isRecord(value) || typeof value.timestamp !== "number" || !isRecord(value.rates)) return null;
+
+  const rates: RateTable = { USD: 1 };
+  for (const currency of SUPPORTED_COST_CURRENCIES) {
+    const rate = value.rates[currency.toLowerCase()] ?? value.rates[currency];
+    if (typeof rate === "number" && Number.isFinite(rate) && rate > 0) {
+      rates[currency] = rate;
+    }
+  }
+
+  return { timestamp: value.timestamp, rates };
+}
+
+async function readCachedRatesFromDisk(): Promise<CachedRates | null> {
+  try {
+    return parseCachedRates(JSON.parse(await readFile(RATE_CACHE_PATH, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCachedRatesToDisk(rates: CachedRates): Promise<void> {
+  try {
+    await mkdir(dirname(RATE_CACHE_PATH), { recursive: true });
+    await writeFile(RATE_CACHE_PATH, JSON.stringify(rates));
+  } catch {
+    // The footer can still use in-memory rates when the cache file is unavailable.
+  }
+}
+
+async function fetchLatestRates(): Promise<CachedRates> {
+  const response = await fetch(RATE_URL);
+  if (!response.ok) throw new Error(`currency rate fetch failed with HTTP ${response.status}`);
+
+  const body = await response.json();
+  if (!isRecord(body) || !isRecord(body.usd)) throw new Error("currency rate response did not include USD rates");
+
+  const rates: RateTable = { USD: 1 };
+  for (const currency of SUPPORTED_COST_CURRENCIES) {
+    if (currency === "USD") continue;
+    const rate = body.usd[currency.toLowerCase()];
+    if (typeof rate === "number" && Number.isFinite(rate) && rate > 0) {
+      rates[currency] = rate;
+    }
+  }
+
+  return { timestamp: Date.now(), rates };
+}
+
+function ensureRatesRefreshing(now: number): void {
+  if (pendingFetch) return;
+  if (cachedRates && now - cachedRates.timestamp < RATE_TTL_MS) return;
+
+  pendingFetch = (async () => {
+    if (!cachedRates) cachedRates = await readCachedRatesFromDisk();
+    if (cachedRates && Date.now() - cachedRates.timestamp < RATE_TTL_MS) return;
+    if (typeof fetch !== "function") return;
+
+    try {
+      const rates = await fetchLatestRates();
+      cachedRates = rates;
+      void writeCachedRatesToDisk(rates);
+    } catch {
+      if (!cachedRates) cachedRates = await readCachedRatesFromDisk();
+    }
+  })().finally(() => {
+    pendingFetch = null;
+  });
+}
+
+function getRate(currency: CostCurrencyCode): number | null {
+  if (currency === "USD") return 1;
+
+  const rate = cachedRates?.rates[currency];
+  ensureRatesRefreshing(Date.now());
+
+  return typeof rate === "number" && Number.isFinite(rate) && rate > 0 ? rate : null;
+}
+
+export function formatUsdCost(amountUsd: number, currency: CostCurrencyCode = "USD"): string | null {
+  const rate = getRate(currency);
+  if (!rate) return `-- ${currency}`;
+
+  const amount = amountUsd * rate;
+  const decimals = currency === "JPY" || currency === "KRW" ? 0 : 2;
+  return `${CURRENCY_SYMBOLS[currency]}${amount.toFixed(decimals)}`;
+}
+
+export function __setCurrencyRatesForTest(rates: RateTable, timestamp = Date.now()): void {
+  cachedRates = { timestamp, rates: { USD: 1, ...rates } };
+  pendingFetch = null;
+}
+
+export function __resetCurrencyRatesForTest(): void {
+  cachedRates = null;
+  pendingFetch = null;
+}