@nyte-ai/host 0.0.18 → 0.0.21

package/src/open.ts

@@ -1,7 +1,7 @@
 import { watch } from "node:fs";
 import { mkdir, readFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import process from "node:process";
 import type { Models, Provider } from "@nyte-ai/ai";
 import { defaultProviderAuthContext } from "@nyte-ai/ai/auth/context";
@@ -43,55 +43,28 @@ import { localProvider } from "./local/provider.ts";
 import { importLegacyTrust } from "./local/legacy-trust.ts";
 import { migrateLocalWorkspaceIdentities } from "./local/workspace-migration.ts";
 import { listen } from "./listen.ts";
+import { nodeImages } from "./images/node.ts";
 import { createMcpHub } from "./mcp/hub.ts";
 import { loadPluginDirectory, pluginLoader } from "./plugins/loader.ts";
 import { defaultSecrets } from "./secrets.ts";
 import type { SecretsSource } from "./secrets.ts";
-import { sqliteStore } from "./sqlite.ts";
+import { sqliteStore, storePath } from "./sqlite.ts";
 
 const RELOAD_DEBOUNCE_MS = 250;
 
 const STORE_POLL_MS = 500;
 
-/**
- * Describes what `openHost` takes: `OpenOptions` with `store`, `workspace`,
- * `models` and `plugins` optional, `secrets` defaulting to this machine's key,
- * and the home directory holding `.nyte`. Every `OpenOptions` is one, so the
- * sdk's Node `open` passes its options straight through.
- */
 export type OpenHostOptions = Omit<OpenOptions, "store" | "workspace" | "models" | "plugins"> & {
-  /** The host's store; absent, `sqliteStore` at `<home>/.nyte/nyte.db`, which the host then closes with itself (§51c). */
   readonly store?: Store;
-  /** Where a root session acts when `create` names none; default the local folder `process.cwd()` (§51c). */
   readonly workspace?: WorkspaceTarget;
-  /** The `@nyte-ai/ai` catalog; absent, `nyteModels` over this host's encrypted credential store (§42e). */
   readonly models?: Models;
-  /** Core plugins loaded after the first-party built-ins and before the plugin files; default none. One with a built-in's id replaces that built-in, as a bundled client's `codemode` runtime does, and a `local` environment provider among them replaces the default one. */
   readonly plugins?: readonly Plugin<"core">[];
-  /** The directory whose `.nyte` holds the store, settings, plugins, secrets key and identity key; default `os.homedir()`. */
   readonly home?: string;
-  /** The login shell the default local provider's pty jobs run, read at each start; absent or null is `$SHELL`. */
   readonly shell?: () => string | null;
+  readonly label?: string;
+  readonly onRevoked?: () => void;
 };
 
-/**
- * Opens the Node host the sdk's Node `open` calls: `composeHost` with
- * `home` (default `os.homedir()`), `store` (default `<home>/.nyte/nyte.db`,
- * checked every 500 ms for another process's commits, which are then read so
- * a second process on the file sees the first one's runs live),
- * `workspace` (default the local folder `process.cwd()`), `secrets` (default
- * `defaultSecrets(home)`), `models` (default `nyteModels`), `localProvider`
- * unless a plugin provides the `local` environment, every first-party plugin
- * of `@nyte-ai/plugin` that `plugins` does not replace by id, then `plugins`
- * and `filePlugins`' files, `settingsSeed`'s seed and
- * `hostDescription()`; each file that did not load becomes a
- * `server.report` row. The host's `loadPlugins` is `pluginLoader` over
- * the plugin directories (§47l), which `watchPlugins` watches for hot reload
- * (§49a). `listen` defaults `identity` to `identitySigner(host.hostId, home)`
- * and `describe` to the description; nothing here reads the secrets key, even
- * with a credential stored (§50d, §55). `close()` stops the watch, closes the
- * open listeners, the host, then a store it opened.
- */
 export async function openHost(options: OpenHostOptions): Promise<Host> {
   const home = options.home ?? homedir();
   const workspace = options.workspace ?? { kind: "local", path: process.cwd() };
@@ -109,9 +82,10 @@ export async function openHost(options: OpenHostOptions): Promise<Host> {
 }
 
 async function defaultStore(home: string): Promise<Store> {
-  await mkdir(join(home, ".nyte"), { recursive: true, mode: 0o700 });
+  const path = storePath(home);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
 
-  return sqliteStore({ path: join(home, ".nyte", "nyte.db") });
+  return sqliteStore({ path });
 }
 
 async function composeOpen(
@@ -156,7 +130,6 @@ async function composeOpen(
     openaiAstraContext,
     telemetry,
     canvas,
-    browserTools,
     claudeCode.plugin,
     acp.plugin,
   ];
@@ -179,6 +152,7 @@ async function composeOpen(
     models,
     mcp: options.mcp ?? createMcpHub({ home }),
     github: options.github ?? (usesLocalProvider ? localGitHubAccount({ home }) : undefined),
+    images: options.images ?? nodeImages(),
     plugins: [...plugins, ...files.plugins],
     pluginSources: files.sources,
     secrets,
@@ -186,6 +160,12 @@ async function composeOpen(
     description,
     ...(settings.seed === null ? {} : { seed: settings.seed }),
     ...(owned === null ? {} : { poll: STORE_POLL_MS }),
+    member: {
+      label: options.label ?? "nyte",
+      pid: process.pid,
+      capabilities: given.some((plugin) => plugin.id === browserTools.id) ? [browserTools.id] : [],
+    },
+    revoked: options.onRevoked,
   });
 
   projectDirs = async () =>
@@ -281,7 +261,6 @@ async function nyteModels(input: {
   readonly store: Store;
   readonly secrets: SecretsSource;
   readonly home: string;
-  /** Providers beside Nyte's catalog, each refreshed offline at open. */
   readonly providers: readonly Provider[];
 }): Promise<Models> {
   const credentials = credentialStore(input.store, input.secrets);
@@ -302,6 +281,7 @@ async function nyteModels(input: {
   });
 
   for (const provider of [...nyteProviders(), ...input.providers]) models.setProvider(provider);
+
   const [stored, selected] = await Promise.all([
     credentials.list(),
     input.store.open().then(readModelSelection),

package/src/serve/binding.ts

@@ -193,6 +193,7 @@ export function bindConnection(connection: Connection, options: BindingOptions):
       return null;
     },
     "models.setDefault": ({ ref }) => connection.models.setDefault(ref),
+    "models.setListing": ({ refs, listing }) => connection.models.setListing(refs, listing),
     "models.verify": ({ provider }) => connection.models.verify(provider),
     "models.login": async (input) => {
       const { provider } = input;
@@ -384,9 +385,9 @@ export function bindConnection(connection: Connection, options: BindingOptions):
     "mcp.remove": ({ workspace: id, server, scope }) => workspace(id).mcp.remove(server, scope),
     "workspace.update": ({ workspace: id, patch }) => workspace(id).update(patch),
     "workspace.reload": ({ workspace: id }) => workspace(id).reload(),
-    "workspace.changes": ({ workspace: id, run }) => workspace(id).changes(run),
-    "workspace.patches": async ({ workspace: id, run, paths, options }) =>
-      mapped(workspace(id).patches(run, paths, options), patchesWire),
+    "workspace.changes": ({ workspace: id, source }) => workspace(id).changes(source),
+    "workspace.patches": async ({ workspace: id, source, paths, options }) =>
+      mapped(workspace(id).patches(source, paths, options), patchesWire),
     "workspace.files": async ({ workspace: id }) => capabilityWire(await workspace(id).files()),
     "workspace.git": async ({ workspace: id }) => capabilityWire(await workspace(id).git()),
     "workspace.github": async ({ workspace: id }) => capabilityWire(await workspace(id).github()),

package/src/sqlite.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import process from "node:process";
 import { DatabaseSync } from "node:sqlite";
 import type { SQLInputValue, StatementSync } from "node:sqlite";
 import { asSeq } from "@nyte-ai/schema";
@@ -34,7 +35,6 @@ import {
 } from "./store-rows.ts";
 import { sqliteWorkers } from "./sqlite-workers.ts";
 import { sessionIndexChanges, sqlSessionIndex } from "./session-index.ts";
-import { claimStore } from "./store-owner.ts";
 
 const BUSY_TIMEOUT_MS = 5_000;
 
@@ -43,16 +43,18 @@ const BACKUPS_KEPT = 3;
 const PUT_BODY =
   "INSERT INTO objects (id, body) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET body = excluded.body WHERE objects.body IS NULL";
 
-/** Returns a `Store` over one `node:sqlite` `DatabaseSync`: a file at `path` (WAL mode, opened only by the process that `claimStore` makes its owner, so a second process rejects with `SdkError("unavailable")` before it reads or migrates the file) or an in-memory database. The first `open()` brings it to core's `STORE_VERSION` with `migrateStore` (core's `objects`, `refs`, `log` and `store_meta` tables; each commit one `BEGIN IMMEDIATE`), a file store whose migration rewrites records first saving those refs' rows (name, target, revision; objects are never deleted, so the rows restore them) to `backups/store-<time>-<pid>-<uuid>-v<from>-v<to>.json` beside it, keeping the newest three backups, and rejects with `SdkError("unavailable")` for a store a newer Nyte migrated; a `migrations` table an older Nyte left is kept and ignored. `put` ids the value with core's `objectId` and stores its JSON once; `putBlob` buffers the stream, ids it with `blobId` and stores the bytes once; an object and a blob that share an id share the row, each column filled once (§41f); `blob` reads the bytes back with their size and a null mime. `refs.set` is one `BEGIN IMMEDIATE` transaction with `RefStore.set`'s semantics, each revision a random UUID, that first rejects with `SdkError("unavailable")` when a newer Nyte has migrated the store since it opened. `list(prefix)` reads the name range from `prefix` in name order (BINARY, by code point); `log` returns the events after `after` in seq order up to `limit`, each validated as a `SessionEvent`; `tail` is the session's last seq, or 0; `commitMark` is the writer connection's `PRAGMA data_version`, which moves only for another connection's commit. `checkpoints` keeps one fold checkpoint per session in `fold_checkpoints`, a write at a lower seq leaving the kept one, and `gap` counts a session's events past a seq and sums their UTF-8 bytes. File stores run `list` and `log` on a read-only worker and WAL checkpoints on a separate worker, checking at 1,000 frames and after 100 ms idle with a 10,000-frame writer backstop; unavailable workers warn and fall back to the main connection. Checkpoints use fullfsync on macOS, WAL reuse retains at most 32 MiB, and opening refreshes planner statistics. Writes binding more than 64 KiB use uncached statements. Every `open()` returns a connection over the one writer; `close()` waits for opening and worker shutdown before closing it, and an open during close waits to reopen. */
+/** The local store's file: `NYTE_DB` when set, so a source run keeps its own chats, else `.nyte/nyte.db` under `home`. */
+export function storePath(home: string): string {
+  return process.env["NYTE_DB"] ?? join(home, ".nyte", "nyte.db");
+}
+
 export function sqliteStore(input: { readonly path: string } | { readonly memory: true }): Store {
   let database: DatabaseSync | null = null;
   let opening: Promise<StoreConnection> | null = null;
   let closing: Promise<void> | null = null;
   let workers: ReturnType<typeof sqliteWorkers> | null = null;
-  let release: (() => void) | null = null;
 
   const open = async (): Promise<StoreConnection> => {
-    const claim = "path" in input ? claimStore(input.path) : null;
     let created: DatabaseSync | undefined;
 
     try {
@@ -69,13 +71,11 @@ export function sqliteStore(input: { readonly path: string } | { readonly memory
       created.exec("PRAGMA optimize = 0x10012");
     } catch (error) {
       created?.close();
-      claim?.();
 
       throw error;
     }
 
     database = created;
-    release = claim;
     workers = "path" in input ? sqliteWorkers(created, input.path) : null;
 
     return connect(created, workers);
@@ -98,11 +98,10 @@ export function sqliteStore(input: { readonly path: string } | { readonly memory
       closing ??= (async () => {
         await opening?.catch(() => undefined);
         await workers?.close();
-        database?.close();
-        release?.();
+
+        if (database !== null) closeDatabase(database);
         workers = null;
         database = null;
-        release = null;
         opening = null;
       })().finally(() => {
         closing = null;
@@ -113,6 +112,17 @@ export function sqliteStore(input: { readonly path: string } | { readonly memory
   };
 }
 
+function closeDatabase(database: DatabaseSync): void {
+  if ("bun" in process.versions) {
+    const empty = new DatabaseSync(":memory:");
+    empty.exec("CREATE TABLE closed (id INTEGER)");
+    database.deserialize(empty.serialize());
+    empty.close();
+  }
+
+  database.close();
+}
+
 function hasTable(database: DatabaseSync, name: string): boolean {
   return (
     database.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name) !==
@@ -189,6 +199,7 @@ function sqliteTarget(database: DatabaseSync, path: string | null): MigrationTar
 
             return "conflict";
           }
+
           updateSessionIndex(database, moved.name, moved.id, mintRevision());
         }
 
@@ -308,6 +319,7 @@ function connect(
   );
 
   const deleteRef = database.prepare("DELETE FROM refs WHERE name = ?");
+  const audit = auditing(database);
   const append = database.prepare("INSERT INTO log (session, seq, at, event) VALUES (?, ?, ?, ?)");
 
   const readLog = database.prepare(
@@ -327,6 +339,7 @@ function connect(
   const readGap = database.prepare(
     "SELECT COUNT(*) AS events, COALESCE(SUM(LENGTH(CAST(event AS BLOB))), 0) AS bytes FROM log WHERE session = ? AND seq > ?",
   );
+
   const readVersion = database.prepare("SELECT version FROM store_meta WHERE id = 1");
   const readDataVersion = database.prepare("PRAGMA data_version");
 
@@ -422,11 +435,23 @@ function connect(
           }
 
           const touched = new Map<SessionId, Revision>();
+          const current = new Map([...before].map(([name, row]) => [name, row?.revision ?? null]));
+
           const revisions = updates.map((update) => {
             const revision = mintRevision();
 
             if (update.target === null) deleteRef.run(update.name);
             else putRef.run(update.name, update.target, revision);
+            audit?.run(
+              Date.now(),
+              process.pid,
+              fenceNames([update]).find((name) => name.startsWith("processes/")) ?? null,
+              update.name,
+              current.get(update.name) ?? null,
+              update.target === null ? null : revision,
+              update.target,
+            );
+            current.set(update.name, update.target === null ? null : revision);
             updateSessionIndex(database, update.name, update.target, revision);
             const session = parseSessionRef(update.name);
 
@@ -496,6 +521,17 @@ function connect(
   };
 }
 
+function auditing(database: DatabaseSync): StatementSync | null {
+  if (process.env.NYTE_STORE_AUDIT !== "1") return null;
+  database.exec(
+    "CREATE TABLE IF NOT EXISTS store_audit (id INTEGER PRIMARY KEY, at INTEGER NOT NULL, pid INTEGER NOT NULL, writer TEXT, name TEXT NOT NULL, before TEXT, after TEXT, target TEXT)",
+  );
+
+  return database.prepare(
+    "INSERT INTO store_audit (at, pid, writer, name, before, after, target) VALUES (?, ?, ?, ?, ?, ?, ?)",
+  );
+}
+
 function updateSessionIndex(
   database: DatabaseSync,
   name: string,
@@ -503,6 +539,7 @@ function updateSessionIndex(
   revision: Revision,
 ): void {
   if (sessionIndexRef(name) === null) return;
+
   const body =
     target === null
       ? null

package/src/store-usage.ts

@@ -1,5 +1,4 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import {
   decodeObject,
@@ -17,6 +16,7 @@ import type {
   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";
 
@@ -129,6 +129,7 @@ export function projectUsageReport(
 
       for (const spend of session.records) {
         const { usage } = spend;
+
         const amounts = [
           usage.total,
           usage.input,
@@ -201,7 +202,7 @@ export function projectUsageReport(
 
 export function readNyteUsage(home: string, window: UsageWindow): UsageReport {
   const readAt = Date.now();
-  const path = join(home, ".nyte", "nyte.db");
+  const path = storePath(home);
 
   if (!existsSync(path)) return projectUsageReport([], window, readAt);
   let database: DatabaseSync | undefined;
@@ -268,11 +269,13 @@ export function readNyteUsage(home: string, window: UsageWindow): UsageReport {
       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) {

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-service.ts

@@ -5,7 +5,12 @@ import type { Models } from "@nyte-ai/ai";
 import { serial } from "@nyte-ai/schema/serial";
 import type { Api, Model } from "@nyte-ai/schema/model";
 import { readNyteUsage } from "./store-usage.ts";
-import { createUsageScanCaches, readLocalUsage } from "./usage.ts";
+import {
+  loadUsageScanCaches,
+  readLocalUsage,
+  saveUsageScanCaches,
+  type UsageScanCaches,
+} from "./usage.ts";
 import type { UsageSnapshot, UsageWindow } from "./usage-types.ts";
 
 export interface UsageScanRequest {
@@ -26,12 +31,14 @@ export function catalogForUsage(models: Pick<Models, "getModels">): readonly Mod
 
 export class UsageScanner implements UsageScanReader {
   private readonly home: string;
-  private readonly caches = createUsageScanCaches();
+  private readonly cachePath: string;
+  private caches: UsageScanCaches | undefined;
   private readonly models: ReturnType<typeof createModels>;
   private readonly scans = serial();
 
   constructor(home: string) {
     this.home = home;
+    this.cachePath = join(home, ".nyte", "usage-scan-cache.json");
     this.models = createModels({
       modelsStore: new FileModelsStore(join(home, ".nyte", "models-store.json")),
     });
@@ -56,8 +63,10 @@ export class UsageScanner implements UsageScanReader {
                 catalog.filter((model) => provider === undefined || model.provider === provider),
             };
 
-      const local = await readLocalUsage({ models, caches: this.caches });
+      const caches = (this.caches ??= await loadUsageScanCaches(this.cachePath));
+      const local = await readLocalUsage({ models, window: request.window, caches });
       const report = readNyteUsage(this.home, request.window);
+      void this.scans.run(() => saveUsageScanCaches(this.cachePath, caches));
 
       return {
         ...report,