@cgaravitoq/aiusage 0.4.0

package/src/install.ts

@@ -0,0 +1,162 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  type CollectorConfig,
+  type CollectorTarget,
+  canonicalTimezone,
+  collectorConfig,
+  readConfig,
+  runtimeTimezone,
+  writeConfig,
+} from "./config";
+import {
+  type CollectorEnv,
+  collectorPaths,
+  processEnv,
+  systemdUserUnitDir,
+} from "./paths";
+import {
+  launchAgentPlist,
+  loadCommand,
+  type ScheduleOptions,
+  type SupportedPlatform,
+  systemdService,
+  systemdTimer,
+} from "./schedule";
+
+export interface ScheduleFile {
+  contents: string;
+  path: string;
+}
+
+export interface InstallPlan {
+  config: CollectorConfig;
+  configFile: string;
+  files: ScheduleFile[];
+  loadCommand: string;
+}
+
+export interface InstallOptions {
+  key: string;
+  url: string;
+  cliPath?: string;
+  dryRun?: boolean;
+  env?: CollectorEnv;
+  execPath?: string;
+  log?: (line: string) => void;
+  platform?: NodeJS.Platform;
+  timezone?: string;
+  uid?: number;
+}
+
+const resolvePlatform = (value: NodeJS.Platform): SupportedPlatform => {
+  if (value === "darwin" || value === "linux") {
+    return value;
+  }
+  throw new Error(`unsupported platform: ${value}`);
+};
+
+const resolveCliPath = (): string =>
+  fileURLToPath(new URL("./cli.ts", import.meta.url));
+
+const canonicalUrl = (url: string): string => url.replace(/\/+$/, "");
+
+function scheduleFiles(
+  platform: SupportedPlatform,
+  paths: { plist: string; service: string; timer: string },
+  options: ScheduleOptions,
+): ScheduleFile[] {
+  if (platform === "darwin") {
+    return [{ contents: launchAgentPlist(options), path: paths.plist }];
+  }
+  return [
+    { contents: systemdService(options), path: paths.service },
+    { contents: systemdTimer(), path: paths.timer },
+  ];
+}
+
+async function configuredTargets(
+  configFile: string,
+): Promise<CollectorTarget[]> {
+  const existing = await readConfig(configFile);
+  if (existing.kind === "invalid") {
+    throw new Error(existing.message);
+  }
+  return existing.kind === "ok" ? existing.config.targets : [];
+}
+
+export async function install(options: InstallOptions): Promise<InstallPlan> {
+  const env = options.env ?? processEnv();
+  const platform = resolvePlatform(options.platform ?? process.platform);
+  const paths = collectorPaths(env);
+  const requestedTimezone = options.timezone ?? runtimeTimezone();
+  const timezone = canonicalTimezone(requestedTimezone);
+  if (timezone === null) {
+    throw new Error(`invalid timezone: ${requestedTimezone}`);
+  }
+  const url = canonicalUrl(options.url);
+  const others = (await configuredTargets(paths.configFile)).filter(
+    (target) => canonicalUrl(target.url) !== url,
+  );
+  const config = collectorConfig.parse({
+    targets: [...others, { key: options.key, url }],
+    timezone,
+  });
+  const cliPath = options.cliPath ?? resolveCliPath();
+  if (
+    options.dryRun !== true &&
+    (cliPath.includes("/install/cache/") || /\/bunx-\d+-[^/]+\//.test(cliPath))
+  ) {
+    throw new Error(
+      "refusing to schedule from a bunx path; install globally: bun add -g @cgaravitoq/aiusage, then run: aiusage install --url <url> --key <key>",
+    );
+  }
+  const files = scheduleFiles(platform, paths, {
+    cliPath,
+    execPath: options.execPath ?? process.execPath,
+    stderrLog: paths.stderrLog,
+    stdoutLog: paths.stdoutLog,
+  });
+  const uid = options.uid ?? process.getuid?.() ?? 0;
+  const plan: InstallPlan = {
+    config,
+    configFile: paths.configFile,
+    files,
+    loadCommand: loadCommand(platform, paths.plist, uid),
+  };
+  const log = options.log ?? console.log;
+
+  log(`config: ${plan.configFile} (600, key redacted)`);
+  for (const target of plan.config.targets) {
+    log(`target: ${target.url}`);
+  }
+  for (const file of plan.files) {
+    log(`schedule: ${file.path}`);
+  }
+  if (platform === "linux") {
+    const unitDir = dirname(paths.service);
+    const systemdDir = systemdUserUnitDir(env);
+    if (unitDir !== systemdDir) {
+      log(
+        `warning: systemd will not read units from ${unitDir}; it reads them from ${systemdDir}`,
+      );
+    }
+  }
+
+  if (options.dryRun === true) {
+    for (const file of plan.files) {
+      log(`--- ${file.path} ---`);
+      log(file.contents.trimEnd());
+    }
+  } else {
+    await writeConfig(plan.configFile, plan.config);
+    for (const file of plan.files) {
+      await mkdir(dirname(file.path), { recursive: true });
+      await writeFile(file.path, file.contents);
+    }
+  }
+
+  log(`load: ${plan.loadCommand}`);
+  return plan;
+}

package/src/machine.ts

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { runCommand } from "./command";
+
+export interface MachineIdentity {
+  hostname: string;
+  platformUuid: string | null;
+}
+
+const disallowed = /[^A-Za-z0-9._-]/g;
+
+const platformUuidPattern = /"IOPlatformUUID"\s*=\s*"([^"]+)"/;
+
+/** The hostname changes with the network, and every spelling of it used to open
+ * a new machine on the server, so the platform identifier travels alone. */
+export function machineId(
+  hostnameValue: string,
+  platformUuid: string | null,
+): string {
+  const raw = platformUuid ?? hostnameValue;
+  return raw.replace(disallowed, "-").slice(0, 64);
+}
+
+export function platformUuidFromIoreg(source: string): string | null {
+  return platformUuidPattern.exec(source)?.[1] ?? null;
+}
+
+async function readDarwinPlatformUuid(): Promise<string | null> {
+  const result = await runCommand("ioreg", [
+    "-rd1",
+    "-c",
+    "IOPlatformExpertDevice",
+  ]);
+  return result.exitCode === 0 ? platformUuidFromIoreg(result.stdout) : null;
+}
+
+async function readLinuxPlatformUuid(): Promise<string | null> {
+  try {
+    const value = (await readFile("/etc/machine-id", "utf8")).trim();
+    return value === "" ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+export async function readMachineIdentity(
+  platform: NodeJS.Platform = process.platform,
+): Promise<MachineIdentity> {
+  const platformUuid =
+    platform === "darwin"
+      ? await readDarwinPlatformUuid()
+      : platform === "linux"
+        ? await readLinuxPlatformUuid()
+        : null;
+  return { hostname: hostname(), platformUuid };
+}

package/src/mapping.ts

@@ -0,0 +1,172 @@
+import type { AntigravityStep } from "./antigravity";
+import { type CcusageDaily, calendarDate } from "./ccusage";
+import type { DevinStep } from "./devin";
+import { costOf, type ModelPrice, type PriceTable } from "./pricing";
+import type { UsageDay } from "./usage";
+
+export const antigravityProvider = "antigravity";
+export const devinProvider = "devin";
+
+const agentModelPrefix = /^\[[^\]]*\]\s*/;
+const effortSuffix = /-(low|medium|high|xhigh)$/;
+const gptMinorVersion = /^gpt-(\d+)-(\d+)-/;
+
+const litellmModel = (devinModel: string): string =>
+  devinModel.replace(effortSuffix, "").replace(gptMinorVersion, "gpt-$1.$2-");
+
+const rowKey = (day: UsageDay): string =>
+  `${day.date}\u0000${day.provider}\u0000${day.model}`;
+
+const isEmptyRow = (row: UsageDay): boolean =>
+  row.input === 0 &&
+  row.output === 0 &&
+  row.cache_create === 0 &&
+  row.cache_read === 0;
+
+function addRow(rows: Map<string, UsageDay>, row: UsageDay): void {
+  const key = rowKey(row);
+  const existing = rows.get(key);
+  if (existing === undefined) {
+    rows.set(key, row);
+    return;
+  }
+  existing.cache_create += row.cache_create;
+  existing.cache_read += row.cache_read;
+  existing.cost_usd += row.cost_usd;
+  existing.input += row.input;
+  existing.output += row.output;
+}
+
+export function ccusageProviders(output: CcusageDaily): string[] {
+  const providers = new Set<string>();
+  for (const day of output.daily) {
+    for (const agent of day.agents) {
+      providers.add(agent.agent);
+    }
+  }
+  return [...providers].sort();
+}
+
+export function mapCcusageDays(output: CcusageDaily): UsageDay[] {
+  const rows = new Map<string, UsageDay>();
+
+  for (const day of output.daily) {
+    for (const agent of day.agents) {
+      for (const breakdown of agent.modelBreakdowns) {
+        const row: UsageDay = {
+          cache_create: breakdown.cacheCreationTokens,
+          cache_read: breakdown.cacheReadTokens,
+          cost_usd: breakdown.cost,
+          date: day.period,
+          input: breakdown.inputTokens,
+          model: breakdown.modelName.replace(agentModelPrefix, ""),
+          output: breakdown.outputTokens,
+          provider: agent.agent,
+        };
+        if (isEmptyRow(row)) {
+          continue;
+        }
+        addRow(rows, row);
+      }
+    }
+  }
+
+  return sortedRows(rows);
+}
+
+interface LocalStep {
+  at: Date;
+  cacheCreate?: number;
+  cacheRead: number;
+  input: number;
+  model: string;
+  output: number;
+}
+
+export interface MappedDays {
+  days: UsageDay[];
+  warnings: string[];
+}
+
+function mapLocalSteps(
+  steps: LocalStep[],
+  provider: string,
+  timezone: string,
+  priceOf: (model: string) => ModelPrice | undefined,
+): MappedDays {
+  const rows = new Map<string, UsageDay>();
+
+  for (const step of steps) {
+    const row: UsageDay = {
+      cache_create: step.cacheCreate ?? 0,
+      cache_read: step.cacheRead,
+      cost_usd: 0,
+      date: calendarDate(step.at, timezone),
+      input: step.input,
+      model: step.model,
+      output: step.output,
+      provider,
+    };
+    if (isEmptyRow(row)) {
+      continue;
+    }
+    addRow(rows, row);
+  }
+
+  const unpriced = new Set<string>();
+  for (const row of rows.values()) {
+    const price = priceOf(row.model);
+    if (price === undefined) {
+      unpriced.add(row.model);
+      continue;
+    }
+    row.cost_usd = costOf(price, {
+      cacheCreate: row.cache_create,
+      cacheRead: row.cache_read,
+      input: row.input,
+      output: row.output,
+    });
+  }
+
+  return {
+    days: sortedRows(rows),
+    warnings: [...unpriced].map(
+      (model) => `${provider}: no price for ${model}`,
+    ),
+  };
+}
+
+export function mapAntigravitySteps(
+  steps: AntigravityStep[],
+  timezone: string,
+  prices: PriceTable,
+): MappedDays {
+  return mapLocalSteps(
+    steps,
+    antigravityProvider,
+    timezone,
+    (model) => prices.get(model) ?? prices.get(`gemini/${model}`),
+  );
+}
+
+export function mapDevinSteps(
+  steps: DevinStep[],
+  timezone: string,
+  prices: PriceTable,
+): MappedDays {
+  return mapLocalSteps(
+    steps.map((step) => ({ ...step, model: litellmModel(step.model) })),
+    devinProvider,
+    timezone,
+    (model) => prices.get(model),
+  );
+}
+
+function sortedRows(rows: Map<string, UsageDay>): UsageDay[] {
+  return [...rows.values()].sort(
+    (a, b) =>
+      a.date.localeCompare(b.date) ||
+      a.provider.localeCompare(b.provider) ||
+      a.model.localeCompare(b.model),
+  );
+}

package/src/paths.ts

@@ -0,0 +1,70 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export interface CollectorEnv {
+  home: string;
+  platform?: NodeJS.Platform;
+  aiusageHome?: string;
+  xdgConfigHome?: string;
+  xdgStateHome?: string;
+}
+
+export interface CollectorPaths {
+  configFile: string;
+  plist: string;
+  pricesFile: string;
+  service: string;
+  stderrLog: string;
+  stdoutLog: string;
+  timer: string;
+}
+
+export function processEnv(): CollectorEnv {
+  return {
+    home: homedir(),
+    platform: process.platform,
+    aiusageHome: process.env.AIUSAGE_HOME,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    xdgStateHome: process.env.XDG_STATE_HOME,
+  };
+}
+
+function logDirFor(env: CollectorEnv, home: string): string {
+  if (env.platform !== "linux") {
+    return resolve(home, "Library", "Logs", "aiusage");
+  }
+  if (env.aiusageHome === undefined && env.xdgStateHome !== undefined) {
+    return resolve(env.xdgStateHome, "aiusage", "logs");
+  }
+  return resolve(home, ".local", "state", "aiusage", "logs");
+}
+
+export function systemdUserUnitDir(env: CollectorEnv): string {
+  return env.xdgConfigHome === undefined
+    ? resolve(env.home, ".config", "systemd", "user")
+    : resolve(env.xdgConfigHome, "systemd", "user");
+}
+
+export function collectorPaths(env: CollectorEnv): CollectorPaths {
+  const home = resolve(env.aiusageHome ?? env.home);
+  const configHome =
+    env.aiusageHome === undefined && env.xdgConfigHome !== undefined
+      ? resolve(env.xdgConfigHome)
+      : resolve(home, ".config");
+  const logDir = logDirFor(env, home);
+
+  return {
+    configFile: resolve(configHome, "aiusage", "config.json"),
+    plist: resolve(
+      home,
+      "Library",
+      "LaunchAgents",
+      "dev.aiusage.collector.plist",
+    ),
+    pricesFile: resolve(configHome, "aiusage", "litellm-prices.json"),
+    service: resolve(configHome, "systemd", "user", "aiusage.service"),
+    stderrLog: resolve(logDir, "aiusage.err.log"),
+    stdoutLog: resolve(logDir, "aiusage.log"),
+    timer: resolve(configHome, "systemd", "user", "aiusage.timer"),
+  };
+}

package/src/pricing.ts

@@ -0,0 +1,137 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import type { Fetcher } from "./http";
+
+export interface ModelPrice {
+  cacheCreate: number;
+  cacheRead: number;
+  input: number;
+  output: number;
+}
+
+export type PriceTable = Map<string, ModelPrice>;
+
+export interface PricedUsage {
+  cacheCreate?: number;
+  cacheRead: number;
+  input: number;
+  output: number;
+}
+
+export const litellmPricesUrl =
+  "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
+const maxAgeMs = 24 * 60 * 60 * 1000;
+const fetchTimeoutMs = 30_000;
+
+const pricedEntry = z.object({
+  cache_creation_input_token_cost: z.number().optional(),
+  cache_read_input_token_cost: z.number().optional(),
+  input_cost_per_token: z.number(),
+  output_cost_per_token: z.number(),
+});
+
+const litellmPrices = z.record(z.string(), z.unknown());
+
+export function parseLitellmPrices(source: string): PriceTable {
+  const table: PriceTable = new Map();
+  for (const [model, entry] of Object.entries(
+    litellmPrices.parse(JSON.parse(source)),
+  )) {
+    const priced = pricedEntry.safeParse(entry);
+    if (priced.success) {
+      table.set(model, {
+        cacheCreate: priced.data.cache_creation_input_token_cost ?? 0,
+        cacheRead: priced.data.cache_read_input_token_cost ?? 0,
+        input: priced.data.input_cost_per_token,
+        output: priced.data.output_cost_per_token,
+      });
+    }
+  }
+  return table;
+}
+
+export function costOf(price: ModelPrice, usage: PricedUsage): number {
+  return (
+    usage.input * price.input +
+    usage.output * price.output +
+    usage.cacheRead * price.cacheRead +
+    (usage.cacheCreate ?? 0) * price.cacheCreate
+  );
+}
+
+async function readCache(
+  pricesFile: string,
+): Promise<{ modifiedAt: number; table: PriceTable } | null> {
+  let source: string;
+  let modifiedAt: number;
+  try {
+    [source, modifiedAt] = await Promise.all([
+      readFile(pricesFile, "utf8"),
+      stat(pricesFile).then((info) => info.mtimeMs),
+    ]);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  try {
+    const table = parseLitellmPrices(source);
+    return table.size === 0 ? null : { modifiedAt, table };
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(pricesFile: string, source: string): Promise<void> {
+  await mkdir(dirname(pricesFile), { recursive: true });
+  const partial = `${pricesFile}.${process.pid}.tmp`;
+  await writeFile(partial, source);
+  await rename(partial, pricesFile);
+}
+
+async function fetchPrices(
+  fetcher: Fetcher,
+  timeoutMs: number,
+): Promise<string> {
+  const response = await fetcher(litellmPricesUrl, {
+    method: "GET",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const source = await response.text();
+  if (response.status !== 200) {
+    throw new Error(`LiteLLM responded ${response.status}`);
+  }
+  return source;
+}
+
+export async function loadPrices(
+  fetcher: Fetcher,
+  pricesFile: string,
+  now: Date,
+  timeoutMs = fetchTimeoutMs,
+): Promise<PriceTable> {
+  const cached = await readCache(pricesFile);
+  if (cached !== null && now.getTime() - cached.modifiedAt < maxAgeMs) {
+    return cached.table;
+  }
+  let source: string;
+  let table: PriceTable;
+  try {
+    source = await fetchPrices(fetcher, timeoutMs);
+    table = parseLitellmPrices(source);
+    if (table.size === 0) {
+      throw new Error("LiteLLM returned an empty price table");
+    }
+  } catch (error) {
+    if (cached !== null) {
+      return cached.table;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`could not load model prices: ${message}`);
+  }
+  await writeCache(pricesFile, source);
+  return table;
+}

package/src/schedule.ts

@@ -0,0 +1,86 @@
+export interface ScheduleOptions {
+  cliPath: string;
+  execPath: string;
+  stderrLog: string;
+  stdoutLog: string;
+}
+
+export type SupportedPlatform = "darwin" | "linux";
+
+const escapeXml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const shellSafe = /^[A-Za-z0-9/._:@+,=^-]+$/;
+
+const quoteForShell = (value: string): string =>
+  shellSafe.test(value) ? value : `'${value.replaceAll("'", () => "'\\''")}'`;
+
+const escapeSystemd = (value: string): string =>
+  value
+    .replaceAll("\\", () => "\\\\")
+    .replaceAll("%", "%%")
+    .replaceAll("$", () => "$$")
+    .replaceAll('"', '\\"');
+
+export function launchAgentPlist(options: ScheduleOptions): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.aiusage.collector</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(options.execPath)}</string>
+    <string>${escapeXml(options.cliPath)}</string>
+    <string>collect</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>300</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(options.stdoutLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(options.stderrLog)}</string>
+</dict>
+</plist>
+`;
+}
+
+export function systemdService(options: ScheduleOptions): string {
+  return `[Unit]
+Description=Report local token usage to aiusage
+
+[Service]
+Type=oneshot
+ExecStart="${escapeSystemd(options.execPath)}" "${escapeSystemd(options.cliPath)}" collect
+`;
+}
+
+export function systemdTimer(): string {
+  return `[Unit]
+Description=Report local token usage to aiusage every five minutes
+
+[Timer]
+Unit=aiusage.service
+OnBootSec=1min
+OnUnitActiveSec=5min
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+export function loadCommand(
+  platform: SupportedPlatform,
+  plistPath: string,
+  uid: number,
+): string {
+  return platform === "darwin"
+    ? `launchctl bootstrap gui/${uid} ${quoteForShell(plistPath)}`
+    : "systemctl --user enable --now aiusage.timer";
+}

package/src/usage.ts

@@ -0,0 +1,17 @@
+export interface UsageDay {
+  cache_create: number;
+  cache_read: number;
+  cost_usd: number;
+  date: string;
+  input: number;
+  model: string;
+  output: number;
+  provider: string;
+}
+
+export interface UsageReport {
+  days: UsageDay[];
+  machine: string;
+  providers?: string[];
+  timezone?: string;
+}