@cgaravitoq/aiusage 0.4.0

package/src/collect.ts

@@ -0,0 +1,329 @@
+import {
+  type AntigravityStep,
+  antigravityConversationsDir,
+  readAntigravitySteps,
+} from "./antigravity";
+import {
+  calendarDate,
+  readCcusageDaily,
+  sinceArgument,
+  windowStart,
+} from "./ccusage";
+import { type CommandRunner, runCommand } from "./command";
+import { type CollectorTarget, readConfig, runtimeTimezone } from "./config";
+import { type DevinStep, devinTranscriptsDir, readDevinSteps } from "./devin";
+import type { Fetcher } from "./http";
+import { type MachineIdentity, machineId } from "./machine";
+import {
+  antigravityProvider,
+  ccusageProviders,
+  devinProvider,
+  type MappedDays,
+  mapAntigravitySteps,
+  mapCcusageDays,
+  mapDevinSteps,
+} from "./mapping";
+import { type CollectorEnv, collectorPaths, processEnv } from "./paths";
+import { loadPrices, type PriceTable } from "./pricing";
+import type { UsageDay, UsageReport } from "./usage";
+
+export interface CollectOptions {
+  identity: MachineIdentity;
+  env?: CollectorEnv;
+  fetcher?: Fetcher;
+  requestTimeoutMs?: number;
+  runner?: CommandRunner;
+  today?: Date;
+  timezone?: string;
+}
+
+export type TargetResult =
+  | { accepted: number; url: string }
+  | { message: string; url: string };
+
+export type CollectResult =
+  | {
+      kind: "reported";
+      machine: string;
+      targets: TargetResult[];
+      warnings: string[];
+    }
+  | { kind: "empty"; warnings: string[] }
+  | { kind: "missing-config"; configFile: string }
+  | { kind: "failed"; message: string; warnings: string[] };
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const fetchTimeoutMs = 30_000;
+const sliceSize = 1000;
+
+const reportUrl = (baseUrl: string): string =>
+  `${baseUrl.replace(/\/+$/, "")}/api/report`;
+
+const providerDay = (day: UsageDay): string =>
+  `${day.date}\u0000${day.provider}`;
+
+function acceptedCount(body: string): number | null {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    !("accepted" in payload)
+  ) {
+    return null;
+  }
+  const accepted = payload.accepted;
+  if (
+    typeof accepted !== "number" ||
+    !Number.isInteger(accepted) ||
+    accepted < 0
+  ) {
+    return null;
+  }
+  return accepted;
+}
+
+interface LocalSource<Step extends { at: Date }> {
+  map: (steps: Step[], timezone: string, prices: PriceTable) => MappedDays;
+  provider: string;
+  read: (home: string) => Promise<{ failures: string[]; steps: Step[] }>;
+}
+
+interface LocalWindow {
+  fetcher: Fetcher;
+  home: string;
+  pricesFile: string;
+  requestTimeoutMs: number;
+  since: string;
+  timezone: string;
+  today: Date;
+}
+
+const antigravitySource: LocalSource<AntigravityStep> = {
+  map: mapAntigravitySteps,
+  provider: antigravityProvider,
+  read: (home) => readAntigravitySteps(antigravityConversationsDir(home)),
+};
+
+const devinSource: LocalSource<DevinStep> = {
+  map: mapDevinSteps,
+  provider: devinProvider,
+  read: (home) => readDevinSteps(devinTranscriptsDir(home)),
+};
+
+async function report(
+  fetcher: Fetcher,
+  target: CollectorTarget,
+  body: string,
+  requestTimeoutMs: number,
+): Promise<TargetResult> {
+  const { url } = target;
+  try {
+    const response = await fetcher(reportUrl(url), {
+      body,
+      headers: {
+        Authorization: `Bearer ${target.key}`,
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+      signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+    const answer = await response.text();
+    if (response.status !== 200) {
+      return {
+        message: `aiusage responded ${response.status}: ${answer}`,
+        url,
+      };
+    }
+    const accepted = acceptedCount(answer);
+    if (accepted === null) {
+      return {
+        message: `aiusage responded an unexpected body: ${answer}`,
+        url,
+      };
+    }
+    return { accepted, url };
+  } catch (error) {
+    return { message: messageOf(error), url };
+  }
+}
+
+function daySlices(days: UsageDay[], size: number): UsageDay[][] {
+  const groups: UsageDay[][] = [];
+  for (const day of days) {
+    const group = groups.at(-1);
+    if (group !== undefined && group[0].date === day.date) {
+      group.push(day);
+    } else {
+      groups.push([day]);
+    }
+  }
+
+  const slices: UsageDay[][] = [];
+  let current: UsageDay[] = [];
+  for (const group of groups) {
+    if (current.length > 0 && current.length + group.length > size) {
+      slices.push(current);
+      current = [];
+    }
+    current.push(...group);
+  }
+  if (current.length > 0) {
+    slices.push(current);
+  }
+  return slices;
+}
+
+async function reportTarget(
+  fetcher: Fetcher,
+  target: CollectorTarget,
+  usage: UsageReport,
+  requestTimeoutMs: number,
+): Promise<TargetResult> {
+  let accepted = 0;
+  for (const slice of daySlices(usage.days, sliceSize)) {
+    const result = await report(
+      fetcher,
+      target,
+      JSON.stringify({ ...usage, days: slice }),
+      requestTimeoutMs,
+    );
+    if ("message" in result) {
+      return result;
+    }
+    accepted += result.accepted;
+  }
+  return { accepted, url: target.url };
+}
+
+interface LocalDays extends MappedDays {
+  providers: string[];
+}
+
+async function localDays<Step extends { at: Date }>(
+  source: LocalSource<Step>,
+  window: LocalWindow,
+): Promise<LocalDays> {
+  try {
+    const usage = await source.read(window.home);
+    const warnings = usage.failures.map(
+      (failure) => `${source.provider}: skipped ${failure}`,
+    );
+    const providers = usage.failures.length === 0 ? [source.provider] : [];
+    const steps = usage.steps.filter(
+      (step) => calendarDate(step.at, window.timezone) >= window.since,
+    );
+    if (steps.length === 0) {
+      return { days: [], providers, warnings };
+    }
+    const prices = await loadPrices(
+      window.fetcher,
+      window.pricesFile,
+      window.today,
+      window.requestTimeoutMs,
+    );
+    const mapped = source.map(steps, window.timezone, prices);
+    return {
+      days: mapped.days,
+      providers,
+      warnings: [...warnings, ...mapped.warnings],
+    };
+  } catch (error) {
+    return {
+      days: [],
+      providers: [],
+      warnings: [`${source.provider}: ${messageOf(error)}`],
+    };
+  }
+}
+
+export async function collect(options: CollectOptions): Promise<CollectResult> {
+  const env = options.env ?? processEnv();
+  const paths = collectorPaths(env);
+  const config = await readConfig(paths.configFile);
+  if (config.kind === "missing") {
+    return { configFile: paths.configFile, kind: "missing-config" };
+  }
+  if (config.kind === "invalid") {
+    return { kind: "failed", message: config.message, warnings: [] };
+  }
+
+  const machine = machineId(
+    options.identity.hostname,
+    options.identity.platformUuid,
+  );
+  const timezone =
+    config.config.timezone ?? options.timezone ?? runtimeTimezone();
+  const runner = options.runner ?? runCommand;
+  const fetcher = options.fetcher ?? fetch;
+  const requestTimeoutMs = options.requestTimeoutMs ?? fetchTimeoutMs;
+  const today = options.today ?? new Date();
+
+  let days: UsageDay[];
+  let ccusageFailure: string | null = null;
+  let ccusageCovered: string[] = [];
+  try {
+    const daily = await readCcusageDaily(
+      runner,
+      sinceArgument(today, timezone),
+      timezone,
+    );
+    days = mapCcusageDays(daily);
+    ccusageCovered = ccusageProviders(daily);
+  } catch (error) {
+    ccusageFailure = messageOf(error);
+    days = [];
+  }
+
+  const window: LocalWindow = {
+    fetcher,
+    home: env.home,
+    pricesFile: paths.pricesFile,
+    requestTimeoutMs,
+    since: windowStart(today, timezone),
+    timezone,
+    today,
+  };
+  const antigravity = await localDays(antigravitySource, window);
+  const devin = await localDays(devinSource, window);
+  const covered = new Set(days.map(providerDay));
+  days.push(
+    ...[...antigravity.days, ...devin.days].filter(
+      (day) => !covered.has(providerDay(day)),
+    ),
+  );
+  days.sort((a, b) => a.date.localeCompare(b.date));
+  const warnings =
+    ccusageFailure === null ? [] : [`ccusage: ${ccusageFailure}`];
+  warnings.push(...antigravity.warnings, ...devin.warnings);
+  if (days.length === 0) {
+    if (ccusageFailure !== null) {
+      return { kind: "failed", message: ccusageFailure, warnings };
+    }
+    return { kind: "empty", warnings };
+  }
+
+  const usage: UsageReport = {
+    days,
+    machine,
+    providers: [
+      ...new Set([
+        ...ccusageCovered,
+        ...antigravity.providers,
+        ...devin.providers,
+      ]),
+    ].sort(),
+    timezone,
+  };
+  const targets: TargetResult[] = [];
+  for (const target of config.config.targets) {
+    targets.push(await reportTarget(fetcher, target, usage, requestTimeoutMs));
+  }
+  return { kind: "reported", machine, targets, warnings };
+}

package/src/command.ts

@@ -0,0 +1,94 @@
+import { type ChildProcess, spawn } from "node:child_process";
+
+export interface CommandResult {
+  exitCode: number;
+  stderr: string;
+  stdout: string;
+}
+
+export type CommandRunner = (
+  command: string,
+  args: string[],
+  timeoutMs?: number,
+) => Promise<CommandResult>;
+
+const defaultTimeoutMs = 120_000;
+const maxOutputBytes = 8 * 1024 * 1024;
+
+const toText = (chunks: Buffer[]): string =>
+  Buffer.concat(chunks).toString("utf8");
+
+function killGroup(child: ChildProcess): void {
+  if (child.pid === undefined) {
+    return;
+  }
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+export function runCommand(
+  command: string,
+  args: string[],
+  timeoutMs = defaultTimeoutMs,
+): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let outputBytes = 0;
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const finish = (result: CommandResult): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+    const push = (chunks: Buffer[], chunk: Buffer): void => {
+      if (settled) {
+        return;
+      }
+      outputBytes += chunk.length;
+      if (outputBytes > maxOutputBytes) {
+        killGroup(child);
+        finish({
+          exitCode: 1,
+          stderr: `output exceeded ${maxOutputBytes} bytes`,
+          stdout: "",
+        });
+        return;
+      }
+      chunks.push(chunk);
+    };
+    timer = setTimeout(() => {
+      killGroup(child);
+      finish({
+        exitCode: 1,
+        stderr: `timed out after ${timeoutMs}ms`,
+        stdout: "",
+      });
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk: Buffer) => push(stdout, chunk));
+    child.stderr?.on("data", (chunk: Buffer) => push(stderr, chunk));
+    child.on("error", (error: Error) => {
+      finish({ exitCode: 1, stderr: error.message, stdout: "" });
+    });
+    child.on("close", (exitCode: number | null) => {
+      finish({
+        exitCode: exitCode ?? 1,
+        stderr: toText(stderr),
+        stdout: toText(stdout),
+      });
+    });
+  });
+}

package/src/config.ts

@@ -0,0 +1,101 @@
+import fsp from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+
+const collectorTarget = z.object({
+  key: z.string().min(1),
+  url: z.url({ protocol: /^https?$/ }),
+});
+
+const timezone = z
+  .string()
+  .refine((value) => canonicalTimezone(value) !== null, "invalid timezone")
+  .optional();
+
+export const collectorConfig = z.object({
+  targets: z.array(collectorTarget).min(1),
+  timezone,
+});
+
+const singleTargetConfig = collectorTarget
+  .extend({ timezone })
+  .transform(({ key, url, ...rest }) => ({ targets: [{ key, url }], ...rest }));
+
+const storedConfig = z.union([collectorConfig, singleTargetConfig]);
+
+export type CollectorTarget = z.infer<typeof collectorTarget>;
+export type CollectorConfig = z.infer<typeof collectorConfig>;
+
+export function canonicalTimezone(value: string): string | null {
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: value,
+    }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+export function runtimeTimezone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+export type ConfigReadResult =
+  | { kind: "ok"; config: CollectorConfig }
+  | { kind: "missing" }
+  | { kind: "invalid"; message: string };
+
+const issueText = (error: z.ZodError): string =>
+  error.issues
+    .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+    .join("; ");
+
+export async function readConfig(
+  configFile: string,
+): Promise<ConfigReadResult> {
+  let source: string;
+  try {
+    source = await fsp.readFile(configFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "invalid",
+      message: `could not read aiusage config at ${configFile}: ${message}`,
+    };
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "invalid",
+      message: `could not parse aiusage config at ${configFile}: ${message}`,
+    };
+  }
+
+  const parsed = storedConfig.safeParse(payload);
+  if (!parsed.success) {
+    return {
+      kind: "invalid",
+      message: `invalid aiusage config at ${configFile}: ${issueText(parsed.error)}`,
+    };
+  }
+  return { kind: "ok", config: parsed.data };
+}
+
+export async function writeConfig(
+  configFile: string,
+  config: CollectorConfig,
+): Promise<void> {
+  await fsp.mkdir(dirname(configFile), { recursive: true });
+  const temporary = `${configFile}.tmp`;
+  await fsp.writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await fsp.rename(temporary, configFile);
+}

package/src/devin.ts

@@ -0,0 +1,124 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+
+export interface DevinStep {
+  at: Date;
+  cacheCreate: number;
+  cacheRead: number;
+  input: number;
+  model: string;
+  output: number;
+}
+
+export interface DevinUsage {
+  failures: string[];
+  steps: DevinStep[];
+}
+
+export interface ReaderSteps<Step> {
+  failures: string[];
+  steps: Step[];
+}
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const unknownModel = "devin-unknown";
+
+const metrics = z.object({
+  cached_tokens: z.int().optional(),
+  completion_tokens: z.int(),
+  extra: z
+    .object({ cache_creation_input_tokens: z.int().optional() })
+    .optional(),
+  prompt_tokens: z.int(),
+});
+
+const step = z.object({
+  metrics: metrics.optional(),
+  model_name: z.string().optional(),
+  source: z.string(),
+  step_id: z.unknown().optional(),
+  timestamp: z.iso.datetime({ offset: true }),
+});
+
+const transcript = z.object({ steps: z.array(step) });
+
+const issueText = (error: z.ZodError): string =>
+  error.issues
+    .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+    .join("; ");
+
+export function devinTranscriptsDir(home: string): string {
+  return resolve(home, ".local", "share", "devin", "cli", "transcripts");
+}
+
+function parseTranscript(source: string): ReaderSteps<DevinStep> {
+  const parsed = transcript.safeParse(JSON.parse(source));
+  if (!parsed.success) {
+    throw new Error(issueText(parsed.error));
+  }
+  const steps: DevinStep[] = [];
+  const failures: string[] = [];
+  for (const entry of parsed.data.steps) {
+    if (entry.source !== "agent" || entry.metrics === undefined) {
+      continue;
+    }
+    const cacheRead = entry.metrics.cached_tokens ?? 0;
+    const cacheCreate = entry.metrics.extra?.cache_creation_input_tokens ?? 0;
+    const input = entry.metrics.prompt_tokens - cacheRead - cacheCreate;
+    if (input < 0) {
+      failures.push(
+        `step ${entry.step_id ?? "?"} reports more cached than prompt tokens`,
+      );
+      continue;
+    }
+    steps.push({
+      at: new Date(entry.timestamp),
+      cacheCreate,
+      cacheRead,
+      input,
+      model: entry.model_name ?? unknownModel,
+      output: entry.metrics.completion_tokens,
+    });
+  }
+  return { failures, steps };
+}
+
+export async function readDirectorySteps<Step>(
+  dir: string,
+  suffix: string,
+  read: (file: string) => Promise<ReaderSteps<Step>>,
+): Promise<ReaderSteps<Step>> {
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { failures: [], steps: [] };
+    }
+    throw error;
+  }
+  const steps: Step[] = [];
+  const failures: string[] = [];
+  for (const name of files.filter((file) => file.endsWith(suffix)).sort()) {
+    const file = resolve(dir, name);
+    try {
+      const readFile = await read(file);
+      steps.push(...readFile.steps);
+      failures.push(
+        ...readFile.failures.map((failure) => `${file}: ${failure}`),
+      );
+    } catch (error) {
+      failures.push(`${file}: ${messageOf(error)}`);
+    }
+  }
+  return { failures, steps };
+}
+
+export async function readDevinSteps(dir: string): Promise<DevinUsage> {
+  return readDirectorySteps(dir, ".json", async (file) =>
+    parseTranscript(await readFile(file, "utf8")),
+  );
+}

package/src/http.ts

@@ -0,0 +1,6 @@
+export interface HttpResponse {
+  status: number;
+  text(): Promise<string>;
+}
+
+export type Fetcher = (url: string, init: RequestInit) => Promise<HttpResponse>;