@nyte-ai/host 0.0.0-stage → 0.0.19

package/src/store-usage.ts

@@ -0,0 +1,347 @@
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import {
+  decodeObject,
+  decodeSessionRecord,
+  decodeWorkspaceRecord,
+  parseSessionRef,
+} from "@nyte-ai/core/store";
+import type { ModelRef, SessionId, Usage } from "@nyte-ai/schema";
+import type {
+  UsageEntry,
+  UsageReport,
+  UsageSession,
+  UsageSource,
+  UsageSubject,
+  UsageTotals,
+  UsageWindow,
+} from "./usage-types.ts";
+import { storePath } from "./sqlite.ts";
+import { cacheSavings, usageTokens } from "./usage-summary.ts";
+import { decodeEvent, parseNumber, parseText } from "./store-rows.ts";
+
+export interface UsageRecord {
+  readonly at: number;
+  readonly subject: UsageSubject;
+  readonly usage: Usage;
+}
+
+export interface SessionUsage {
+  readonly sessionId: SessionId;
+  readonly name: string | undefined;
+  readonly records: readonly UsageRecord[];
+  readonly lastActivityAt?: number;
+}
+
+export interface StoreRead {
+  readonly workspacePath: string | null;
+  readonly sessions: readonly SessionUsage[];
+  readonly failure: { readonly message: string } | null;
+}
+
+const EMPTY_TOTALS: UsageTotals = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  reasoning: 0,
+  tokens: 0,
+  cost: 0,
+  cacheSavings: 0,
+};
+
+function add(totals: UsageTotals, usage: Usage): UsageTotals {
+  return {
+    input: totals.input + usage.input,
+    output: totals.output + usage.output,
+    cacheRead: totals.cacheRead + usage.cacheRead,
+    cacheWrite: totals.cacheWrite + usage.cacheWrite,
+    reasoning: totals.reasoning + (usage.reasoning ?? 0),
+    tokens: totals.tokens + usageTokens(usage),
+    cost: totals.cost + usage.cost.total,
+    cacheSavings: totals.cacheSavings + cacheSavings(usage),
+  };
+}
+
+export const USAGE_EVENTS =
+  "SELECT session, seq, at, event FROM log WHERE json_extract(event, '$.kind') = 'request' OR (json_extract(event, '$.kind') = 'run' AND json_extract(event, '$.change') = 'started') ORDER BY session, seq";
+
+export function localDay(at: number): string {
+  const date = new Date(at);
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+
+  return `${String(date.getFullYear())}-${month}-${day}`;
+}
+
+export function shiftDay(day: string, delta: number): string {
+  const date = new Date(`${day}T00:00:00`);
+  date.setDate(date.getDate() + delta);
+
+  return localDay(date.getTime());
+}
+
+function priorWindow(
+  sinceDay: string | null,
+  untilDay: string,
+): { readonly sinceDay: string; readonly untilDay: string } | undefined {
+  if (sinceDay === null) return undefined;
+  const priorUntil = shiftDay(sinceDay, -1);
+
+  const span =
+    (Date.parse(`${untilDay}T00:00:00Z`) - Date.parse(`${sinceDay}T00:00:00Z`)) / 86_400_000 + 1;
+
+  return { sinceDay: shiftDay(priorUntil, -(span - 1)), untilDay: priorUntil };
+}
+
+export function projectUsageReport(
+  stores: readonly StoreRead[],
+  window: UsageWindow,
+  readAt: number,
+): UsageReport {
+  const requestedSince = window.sinceDay;
+  const untilDay = window.untilDay;
+  const prior = priorWindow(requestedSince, untilDay);
+
+  const cells = new Map<
+    string,
+    { readonly entry: Omit<UsageEntry, "totals">; totals: UsageTotals }
+  >();
+
+  const sessions = new Map<SessionId, UsageSession>();
+  const sources: UsageSource[] = [];
+  let priorCost = 0;
+  let priorTokens = 0;
+  let sawPrior = false;
+  let earliestDay: string | undefined;
+
+  for (const store of stores) {
+    sources.push({
+      workspacePath: store.workspacePath,
+      status: store.failure === null ? "ok" : "failed",
+      sessions: store.sessions.length,
+      message: store.failure?.message ?? null,
+    });
+
+    for (const session of store.sessions) {
+      let lastActivityAt = 0;
+      let spentInWindow = false;
+
+      for (const spend of session.records) {
+        const { usage } = spend;
+
+        const amounts = [
+          usage.total,
+          usage.input,
+          usage.output,
+          usage.cacheRead,
+          usage.cacheWrite,
+          usage.cost.total,
+        ];
+
+        if (!amounts.some((amount) => amount > 0)) continue;
+        const day = localDay(spend.at);
+
+        if (earliestDay === undefined || day < earliestDay) earliestDay = day;
+
+        if (prior !== undefined && day >= prior.sinceDay && day <= prior.untilDay) {
+          sawPrior = true;
+          priorCost += spend.usage.cost.total;
+          priorTokens += usageTokens(spend.usage);
+        }
+
+        if (day > untilDay) continue;
+
+        if (requestedSince !== null && day < requestedSince) continue;
+
+        const key = JSON.stringify([day, store.workspacePath, session.sessionId, spend.subject]);
+        const cell = cells.get(key);
+
+        if (cell === undefined) {
+          cells.set(key, {
+            entry: {
+              day,
+              workspacePath: store.workspacePath,
+              sessionId: session.sessionId,
+              subject: spend.subject,
+            },
+            totals: add(EMPTY_TOTALS, spend.usage),
+          });
+        } else {
+          cell.totals = add(cell.totals, spend.usage);
+        }
+
+        spentInWindow = true;
+        lastActivityAt = Math.max(lastActivityAt, spend.at);
+      }
+
+      if (spentInWindow) {
+        sessions.set(session.sessionId, {
+          sessionId: session.sessionId,
+          name: session.name,
+          workspacePath: store.workspacePath,
+          lastActivityAt: session.lastActivityAt ?? lastActivityAt,
+        });
+      }
+    }
+  }
+
+  return {
+    readAt,
+    sinceDay: requestedSince ?? earliestDay ?? untilDay,
+    untilDay,
+    entries: [...cells.values()]
+      .map((cell) => ({ ...cell.entry, totals: cell.totals }))
+      .toSorted((left, right) => left.day.localeCompare(right.day)),
+    sessions: [...sessions.values()],
+    sources,
+    previous: sawPrior ? { cost: priorCost, tokens: priorTokens } : undefined,
+    earliestDay,
+  };
+}
+
+export function readNyteUsage(home: string, window: UsageWindow): UsageReport {
+  const readAt = Date.now();
+  const path = storePath(home);
+
+  if (!existsSync(path)) return projectUsageReport([], window, readAt);
+  let database: DatabaseSync | undefined;
+
+  try {
+    database = new DatabaseSync(path, { readOnly: true, timeout: 5_000 });
+    database.exec("BEGIN");
+    const workspaces = new Map<string, string | null>();
+
+    const sessions = new Map<
+      SessionId,
+      {
+        readonly workspacePath: string | null;
+        readonly name: string | undefined;
+        readonly lastActivityAt: number | undefined;
+        readonly records: UsageRecord[];
+      }
+    >();
+
+    const refs = database
+      .prepare(
+        "SELECT refs.name, objects.body FROM refs JOIN objects ON objects.id = refs.target WHERE refs.name LIKE 'workspaces/%' OR (refs.name LIKE 'sessions/%' AND instr(substr(refs.name, 10), '/') = 0)",
+      )
+      .all();
+
+    for (const row of refs) {
+      const name = parseText(row.name);
+      const body = parseText(row.body);
+
+      if (name === null || body === null || !name.startsWith("workspaces/")) continue;
+      const workspace = decodeWorkspaceRecord(decodeObject(body));
+
+      if (workspace !== null)
+        workspaces.set(
+          workspace.id,
+          workspace.target.kind === "local" && "path" in workspace.target
+            ? parseText(workspace.target.path)
+            : null,
+        );
+    }
+
+    for (const row of refs) {
+      const name = parseText(row.name);
+      const body = parseText(row.body);
+
+      if (name === null || body === null || name.split("/").length !== 2) continue;
+      const id = parseSessionRef(name);
+
+      if (id === null) continue;
+      const session = decodeSessionRecord(decodeObject(body));
+
+      if (session === null) throw new Error(`Cannot read session ${id}.`);
+      sessions.set(id, {
+        workspacePath: workspaces.get(session.workspace) ?? null,
+        name: session.name ?? undefined,
+        lastActivityAt: session.lastActivityAt,
+        records: [],
+      });
+    }
+
+    const models = new Map<SessionId, Map<string | null, ModelRef>>();
+
+    for (const row of database.prepare(USAGE_EVENTS).iterate()) {
+      const session = parseSessionRef(`sessions/${parseText(row.session) ?? ""}`);
+
+      if (session === null) throw new Error("Cannot read usage session.");
+
+      const event = decodeEvent(
+        parseNumber(row.seq),
+        parseNumber(row.at),
+        parseText(row.event) ?? "",
+      );
+
+      let heads = models.get(session);
+
+      if (heads === undefined) {
+        heads = new Map();
+        models.set(session, heads);
+      }
+
+      if (event.kind === "run" && event.change === "started")
+        heads.set(event.head, event.view.configuration.model);
+
+      if (event.kind !== "request") continue;
+      const model = heads.get(event.head);
+
+      const subject: UsageSubject =
+        event.step === "compaction" || event.step === "summary"
+          ? { kind: "compaction" }
+          : event.step === "plugin"
+            ? { kind: "tool" }
+            : {
+                kind: "model",
+                provider: model?.provider ?? "unknown",
+                model: model?.id ?? "unknown",
+              };
+
+      let info = sessions.get(session);
+
+      if (info === undefined) {
+        info = { workspacePath: null, name: undefined, lastActivityAt: undefined, records: [] };
+        sessions.set(session, info);
+      }
+
+      info.records.push({ at: event.at, subject, usage: event.usage });
+    }
+
+    database.exec("COMMIT");
+    const stores = new Map<string | null, SessionUsage[]>();
+
+    for (const [sessionId, info] of sessions) {
+      const group = stores.get(info.workspacePath) ?? [];
+      group.push({
+        sessionId,
+        name: info.name,
+        records: info.records,
+        lastActivityAt: info.lastActivityAt,
+      });
+      stores.set(info.workspacePath, group);
+    }
+
+    return projectUsageReport(
+      [...stores].map(([workspacePath, sessions]) => ({ workspacePath, sessions, failure: null })),
+      window,
+      readAt,
+    );
+  } catch (cause) {
+    return projectUsageReport(
+      [
+        {
+          workspacePath: null,
+          sessions: [],
+          failure: { message: cause instanceof Error ? cause.message : String(cause) },
+        },
+      ],
+      window,
+      readAt,
+    );
+  } finally {
+    database?.close();
+  }
+}

package/src/usage-history.ts

@@ -0,0 +1,219 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import type { Stats } from "node:fs";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Type, type TSchema } from "typebox";
+
+export interface HistoryLine {
+  readonly text: string;
+  /** False for a last line without its newline: its writer may still be appending it. */
+  readonly terminated: boolean;
+}
+
+export interface HistoryFold<Scan> {
+  line(line: HistoryLine): void;
+  scan(): Scan;
+}
+
+/** Folds a history file's lines into a scan. `scan()` returns a copy, so folding goes on without changing it. */
+export type HistoryParser<Scan> = (from: Scan | undefined) => HistoryFold<Scan>;
+
+export interface FileScan<Scan> {
+  readonly size: number;
+  readonly mtimeMs: number;
+  /** The byte after the last newline, where a grown file resumes. */
+  readonly position: number;
+  /** The scan of every line up to `position`. */
+  readonly committed: Scan;
+}
+
+export function fileScanSchema<Scan extends TSchema>(scan: Scan) {
+  return Type.Object({
+    size: Type.Number({ minimum: 0 }),
+    mtimeMs: Type.Number(),
+    position: Type.Number({ minimum: 0 }),
+    committed: scan,
+  });
+}
+
+/** Scans keyed by path. A scan answers while its file keeps the size and mtime it was read at. */
+export class UsageScanCache<Scan> {
+  readonly #files: Map<string, FileScan<Scan>>;
+  #changed = false;
+
+  constructor(files: Iterable<readonly [string, FileScan<Scan>]> = []) {
+    this.#files = new Map(files);
+  }
+
+  keys(): IterableIterator<string> {
+    return this.#files.keys();
+  }
+
+  entries(): IterableIterator<[string, FileScan<Scan>]> {
+    return this.#files.entries();
+  }
+
+  get(path: string): FileScan<Scan> | undefined {
+    return this.#files.get(path);
+  }
+
+  set(path: string, scan: FileScan<Scan>): void {
+    if (this.#files.get(path) === scan) return;
+    this.#files.set(path, scan);
+    this.#changed = true;
+  }
+
+  /** Forgets every file a read did not reach. */
+  keepOnly(seen: ReadonlySet<string>): void {
+    for (const path of this.#files.keys()) {
+      if (seen.has(path)) continue;
+      this.#files.delete(path);
+      this.#changed = true;
+    }
+  }
+
+  /** Whether a scan was added or forgotten since the last {@link markSaved}. */
+  get changed(): boolean {
+    return this.#changed;
+  }
+
+  markSaved(): void {
+    this.#changed = false;
+  }
+}
+
+/**
+ * Reads a history file through `cache`. An unchanged file answers from the cache without being
+ * opened, and a file that only grew is read from its last newline on; any other change rereads it.
+ * A last line without its newline is folded into the answer but not the cache, since its writer may
+ * still be appending it: the next read starts from that line again.
+ */
+export async function readHistory<Scan>(
+  path: string,
+  info: Stats,
+  parser: HistoryParser<Scan>,
+  cache: UsageScanCache<Scan> | undefined,
+  signal: AbortSignal | undefined,
+): Promise<Scan> {
+  const hit = cache?.get(path);
+  const unchanged = hit !== undefined && hit.size === info.size && hit.mtimeMs === info.mtimeMs;
+
+  if (unchanged && hit.position === info.size) return hit.committed;
+  const from = unchanged || (hit !== undefined && info.size > hit.size) ? hit : undefined;
+  const fold = parser(from?.committed);
+  let position = from?.position ?? 0;
+  let unterminated: HistoryLine | undefined;
+
+  for await (const line of historyLines(path, position, signal)) {
+    signal?.throwIfAborted();
+
+    if (!line.terminated) {
+      unterminated = line;
+      continue;
+    }
+
+    fold.line(line);
+    position = line.end;
+  }
+
+  const committed = fold.scan();
+  cache?.set(
+    path,
+    unchanged ? hit : { size: info.size, mtimeMs: info.mtimeMs, position, committed },
+  );
+
+  if (unterminated === undefined) return committed;
+  fold.line(unterminated);
+
+  return fold.scan();
+}
+
+/** Yields a history file's lines from byte `start` up to the size it had when opened, though its writer may keep appending. */
+async function* historyLines(path: string, start: number, signal: AbortSignal | undefined) {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+
+  try {
+    const stat = await file.stat();
+
+    if (!stat.isFile()) throw new Error("History is not a regular file.");
+    const buffer = Buffer.alloc(64 * 1024);
+    let pending = Buffer.alloc(0);
+    let pendingStart = start;
+    let position = start;
+
+    while (position < stat.size) {
+      signal?.throwIfAborted();
+
+      const { bytesRead } = await file.read(
+        buffer,
+        0,
+        Math.min(buffer.length, stat.size - position),
+        position,
+      );
+
+      if (bytesRead === 0) break;
+      position += bytesRead;
+      const read = buffer.subarray(0, bytesRead);
+      const chunk = pending.length === 0 ? read : Buffer.concat([pending, read]);
+      let from = 0;
+
+      // oxlint-disable-next-line nyte-code/no-index-of -- a byte search keeps offsets exact, which decoded text cannot
+      for (let newline = chunk.indexOf(0x0a); newline !== -1; newline = chunk.indexOf(0x0a, from)) {
+        yield {
+          text: chunk.toString("utf8", from, newline),
+          terminated: true,
+          end: pendingStart + newline + 1,
+        };
+        from = newline + 1;
+      }
+
+      pendingStart += from;
+      pending = Buffer.from(chunk.subarray(from));
+    }
+
+    if (pending.length > 0)
+      yield {
+        text: pending.toString("utf8"),
+        terminated: false,
+        end: pendingStart + pending.length,
+      };
+  } finally {
+    await file.close();
+  }
+}
+
+/** Reads a cache document written by {@link writeCacheDocument}; a missing, torn or outdated one reads as `undefined`. */
+export async function readCacheDocument<Document>(
+  path: string,
+  validator: { Check(value: unknown): value is Document },
+): Promise<Document | undefined> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+
+    return validator.Check(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Replaces the cache document whole, so a reader never sees half of one. Resolves whether the write landed. */
+export async function writeCacheDocument<Document>(
+  path: string,
+  document: Document,
+): Promise<boolean> {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(temporary, JSON.stringify(document), { mode: 0o600 });
+    await rename(temporary, path);
+
+    return true;
+  } catch {
+    await rm(temporary, { force: true }).catch(() => undefined);
+
+    return false;
+  }
+}

package/src/usage-scan.ts

@@ -0,0 +1,81 @@
+import { Worker } from "node:worker_threads";
+import type { UsageScan, UsageScanReader, UsageScanRequest } from "./usage-service.ts";
+
+export interface UsageWorkerRequest extends UsageScanRequest {
+  readonly id: number;
+  readonly home: string;
+}
+
+export type UsageWorkerReply =
+  | { readonly id: number; readonly scan: UsageScan }
+  | { readonly id: number; readonly error: string };
+
+export class UsageScanWorker implements UsageScanReader {
+  private readonly home: string;
+  private readonly entry: string | URL;
+  private worker: Worker | undefined;
+  private nextId = 1;
+  private readonly pending = new Map<
+    number,
+    { resolve: (scan: UsageScan) => void; reject: (cause: unknown) => void }
+  >();
+
+  constructor(home: string, entry: string | URL) {
+    this.home = home;
+    this.entry = entry;
+  }
+
+  async scan(request: UsageScanRequest): Promise<UsageScan> {
+    const worker = this.spawn();
+    const id = this.nextId++;
+
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+
+      try {
+        worker.postMessage({ id, home: this.home, ...request } satisfies UsageWorkerRequest);
+      } catch (cause) {
+        this.pending.delete(id);
+        reject(cause);
+      }
+    });
+  }
+
+  async close(): Promise<void> {
+    const worker = this.worker;
+
+    if (worker === undefined) return;
+
+    this.fail(worker, new Error("Usage worker closed."));
+    await worker.terminate();
+  }
+
+  private spawn(): Worker {
+    if (this.worker !== undefined) return this.worker;
+    const worker = new Worker(this.entry);
+    worker.unref();
+    worker.on("message", (reply: UsageWorkerReply) => {
+      const request = this.pending.get(reply.id);
+      this.pending.delete(reply.id);
+
+      if ("scan" in reply) request?.resolve(reply.scan);
+      else request?.reject(new Error(reply.error));
+    });
+
+    worker.on("error", (cause) => this.fail(worker, cause));
+    worker.on("exit", (code) => {
+      this.fail(worker, new Error(`Usage worker exited with code ${String(code)}.`));
+    });
+    this.worker = worker;
+
+    return worker;
+  }
+
+  private fail(worker: Worker, cause: unknown): void {
+    if (this.worker !== worker) return;
+    this.worker = undefined;
+
+    for (const request of this.pending.values()) request.reject(cause);
+    this.pending.clear();
+  }
+}