@zenera/cli 1.1.9 → 1.1.11

package/README.md

@@ -97,6 +97,7 @@ agents:
       description: Turns a summary into a file on disk.
       system: agents/prompts/writer.md
       tools: [workspace:*]
+      handoffs: [reader] # a hand-off does not return by itself; give it a way back
 ```
 
 `agents/prompts/reader.md`:
@@ -161,6 +162,7 @@ you are not expected to hand-author `agents.yaml`.
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `sandbox` | Checks and prepares the container that command-line tools run in.    |
+| `cache`   | What work has been kept, and getting rid of it.                      |
 | `version` | CLI, library and Node versions.                                      |
 
 Commands can also come from a package installed alongside this one, so a new
@@ -254,7 +256,7 @@ zen models test vertex:gemini-embedding-001 # one real call, one verdict
 zen models pick --embedding                 # the first ref that answers, on stdout
 ```
 
-Listings are cached for a day in `~/.zenera/neo/catalog`. When a provider cannot
+Listings are cached for a day in `~/.zenera/neo/cache`. When a provider cannot
 be asked the last listing is used and said to be stale; only if there was never
 one does a short built-in list stand in.
 
@@ -292,7 +294,7 @@ The usual one is a **service-account JSON file** — give its path, not its
 contents. Run the command with nothing piped and it asks:
 
 ```sh
-zen key add vertex --location us-central1
+zen key add vertex --gcp-location us-central1
 # Paste the key, or a path to the file: /Users/you/keys/vertex-sa.json
 ```
 
@@ -300,23 +302,29 @@ The prompt is read by `zen`, not by your shell, so give a full path there — `~
 is not expanded. In a script, pipe the path in instead:
 
 ```sh
-echo ~/keys/vertex-sa.json | zen key add vertex --location us-central1
+echo ~/keys/vertex-sa.json | zen key add vertex --gcp-location us-central1
 ```
 
 The file is copied into `~/.zenera/neo/keys/`, where only you can read it, so
 moving or cleaning up the original later cannot break it.
 
-- `--location <region>` is worth setting. It must be `global` or a **concrete
-  region**; multi-region names like `us` are rejected with a 404. `global`
-  routes across regions and pays about ten seconds of cold start on the first
-  request each process makes — a region answers in about two.
-- `--project <id>` is only needed when the `project_id` inside the file is not
+- `--gcp-location <region>` is worth setting. It takes a concrete region, or one
+  of the endpoints that route across regions: `us` and `eu` pool capacity while
+  keeping processing inside that territory, `global` takes whatever is free and
+  promises no residency. `global` pays about ten seconds of cold start on the
+  first request each process makes — a region answers in about two.
+- Which models a location serves is per model, and not guessable. In one
+  project, `gemini-embedding-2` answered at `us` but 404'd at `us-central1`,
+  while `gemini-2.5-flash` did the opposite. New models often reach `global`,
+  `us` and `eu` first. `zen models test vertex:<model>` is what settles it —
+  `zen key add` only establishes that the credential itself works.
+- `--gcp-project <id>` is only needed when the `project_id` inside the file is not
   the project you want.
 
 The alternative is an **express-mode API key** — a single secret, stored under
 `VERTEX_API_KEY`. It is the Vertex console's way of handing out access without a
-service account, and it needs neither a project nor a region, so `--project` and
-`--location` mean nothing there and are not stored.
+service account, and it needs neither a project nor a region, so `--gcp-project`
+and `--gcp-location` mean nothing there and are not stored.
 
 ### Gemini, three ways
 
@@ -336,15 +344,15 @@ and a region, because the file says which project it belongs to but never which
 region to call:
 
 ```sh
-echo ~/keys/vertex-sa.json | zen key add vertex --location us-central1
+echo ~/keys/vertex-sa.json | zen key add vertex --gcp-location us-central1
 ```
 
-Add `--project` only when the `project_id` inside the file is not the one you
+Add `--gcp-project` only when the `project_id` inside the file is not the one you
 want to bill:
 
 ```sh
 echo ~/keys/vertex-sa.json \
-  | zen key add vertex --project other-project --location europe-west4
+  | zen key add vertex --gcp-project other-project --gcp-location europe-west4
 ```
 
 **Vertex, express mode** — paste the key at the prompt; no flags apply:
@@ -356,8 +364,8 @@ zen key add vertex
 Holding several at once is the ordinary case. Name them and switch:
 
 ```sh
-echo ~/keys/prod-sa.json | zen key add vertex/prod --location us-central1
-echo ~/keys/dev-sa.json  | zen key add vertex/dev  --location global
+echo ~/keys/prod-sa.json | zen key add vertex/prod --gcp-location us-central1
+echo ~/keys/dev-sa.json  | zen key add vertex/dev  --gcp-location global
 zen key add vertex/express       # the express key, same provider
 
 zen key use vertex/dev           # which one the next run uses
@@ -413,6 +421,32 @@ clear where a working provider actually comes from.
 - **Keyring** — `~/.zenera/neo`, readable only by you. Keys are copied into the
   environment just before a run, so an environment variable you set yourself
   always wins and a project checked out on a machine without `zen` still runs.
+- **Cache** — `~/.zenera/neo/cache`, one place for work already done: vectors,
+  parses, model listings, generated mocks. Shared by every project on the
+  machine, and never evicted by anything but you.
+
+## What has already been paid for
+
+Embedding a paragraph, parsing a document, asking a provider what it serves —
+all expensive, all perfectly repeatable. They are kept in one store,
+`~/.zenera/neo/cache/<kind>/`, keyed by every input that produced them. Change
+an input and you are asking a different question, which is why nothing in there
+is ever invalidated: it is simply never asked for again.
+
+```
+zen cache ls                          # what is kept, by kind
+zen cache ls --kind vectors           # and what is in one of them
+zen cache prune --older-than 30d      # drop what has gone unread for a month
+zen cache prune --max-size 2GB        # or keep it under a ceiling
+zen cache clear --kind docs-parse     # throw one kind away
+```
+
+Age is when an entry was last _used_, not when it was written, so a vector a
+weekly rebuild reads is never old. Nothing evicts on its own — a store that
+quietly deletes things is only ever noticed when it has deleted the wrong one —
+so retention is a decision made out loud, here. Nothing in it is precious
+either: every entry is work that can be done again, and the only cost of
+removing one is paying for it a second time.
 
 ## The library underneath
 

package/dist/cache.d.ts

@@ -0,0 +1,98 @@
+export interface CacheOptions {
+    /** where the store lives; defaults to `~/.zenera/neo/cache` */
+    dir?: string;
+    /** file mode, 0600 unless the value is public */
+    mode?: number;
+}
+export interface CacheEntry<T> {
+    value: T;
+    /** when it was written, for callers that have an opinion about freshness */
+    storedAt: string;
+}
+/** What a `Cache` does, so that `NO_CACHE` can be one without being one. */
+export interface CacheStore {
+    readonly kind: string;
+    readonly hits: number;
+    readonly misses: number;
+    entry<T>(key: string): CacheEntry<T> | undefined;
+    get<T>(key: string): T | undefined;
+    put(key: string, value: unknown): void;
+    delete(key: string): void;
+    commit(): void;
+}
+/** Joins the parts of a composite key. NUL cannot occur in any of them. */
+export declare function cacheKey(...parts: readonly (string | number | undefined)[]): string;
+export declare class Cache implements CacheStore {
+    #private;
+    readonly kind: string;
+    constructor(kind: string, options?: CacheOptions);
+    get hits(): number;
+    get misses(): number;
+    entry<T>(key: string): CacheEntry<T> | undefined;
+    get<T>(key: string): T | undefined;
+    put(key: string, value: unknown): void;
+    delete(key: string): void;
+    commit(): void;
+}
+/** Remembers nothing, for `--no-cache` and for anywhere a store cannot be opened. */
+export declare const NO_CACHE: CacheStore;
+export interface CacheKind {
+    kind: string;
+    entries: number;
+    bytes: number;
+    /** epoch ms of the least and most recently used entry; absent when empty */
+    oldest?: number;
+    newest?: number;
+}
+export interface CacheItem {
+    kind: string;
+    key: string;
+    bytes: number;
+    /** epoch ms, last used */
+    usedAt: number;
+    storedAt?: string;
+    /** what was stored — the file is parsed anyway to recover the key */
+    value?: unknown;
+}
+/** A row per kind, for `zen cache ls`. One stat walk; nothing is parsed. */
+export declare function kinds(dir?: string): CacheKind[];
+/**
+ * The entries of one kind, most recently used first. Reading a key means
+ * parsing the file, so the sort happens on stat data and only what will be
+ * shown is opened.
+ */
+export declare function items(kind: string, options?: {
+    dir?: string;
+    limit?: number;
+}): {
+    rows: CacheItem[];
+    found: number;
+};
+export interface SweepOptions {
+    dir?: string;
+    /** only this kind */
+    kind?: string;
+    /** anything unused for longer than this */
+    olderThanMs?: number;
+    /** a ceiling on what is left, met by removing the least recently used */
+    maxBytes?: number;
+}
+export interface Swept {
+    kind: string;
+    removed: number;
+    bytes: number;
+}
+/**
+ * Removes what the options describe and reports what went, by kind.
+ *
+ * `maxBytes` applies to the whole selection rather than to each kind
+ * separately: the disk is one thing, and least-recently-used across the store
+ * is the only ordering that means anything on it.
+ */
+export declare function sweep(options?: SweepOptions): Swept[];
+/** Everything, or one kind of everything. */
+export declare function clear(options?: {
+    dir?: string;
+    kind?: string;
+}): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -0,0 +1,301 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, rmdirSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths, writeJson } from "./home.js";
+// ---------------------------------------------------------------------------
+// One place for work already done
+//
+// Embedding a paragraph, parsing a document, asking a provider what models it
+// serves: all expensive, all perfectly repeatable, and all previously cached by
+// a different hand-rolled file format sitting in a different directory. This is
+// the one store they share, at `~/.zenera/neo/cache/<kind>/<ab>/<sha>.json`,
+// one file per object.
+//
+// Three rules hold the whole thing up.
+//
+// **Nothing here throws.** A corrupt file, a full disk, an unreadable
+// directory, a key that does not match: every one of them is a miss. A cache
+// that cannot work costs time and must never cost correctness, so there is no
+// error path for a caller to get wrong.
+//
+// **The key carries every input.** Not the text alone but the model, the
+// dimensions, the version of whatever produced the value — all of it. That is
+// why there is no invalidation step anywhere: change any input and you are
+// asking a different question, which has no answer yet. Vectors from another
+// model are not evicted, they are simply never found.
+//
+// **The key is written into the entry and checked on the way out.** The path is
+// only a hash of it. Reading proves the file is the one that was asked for
+// rather than trusting sha256 to be injective, and — much more likely to
+// actually happen — it catches a key derivation that changed shape without
+// anyone bumping a version.
+// ---------------------------------------------------------------------------
+/** Characters of the digest that name the subdirectory, so no one directory grows huge. */
+const SHARD = 2;
+/**
+ * How stale a mtime has to be before reading an entry rewrites it.
+ *
+ * `commit` is what makes "older than 30 days" mean *unused* for 30 days rather
+ * than *unwritten* for 30 days. Doing it on every read would be a write per
+ * read; a day's granularity costs nothing and is far finer than any retention
+ * anyone will ask for.
+ */
+const TOUCH_AFTER_MS = 24 * 60 * 60 * 1000;
+/** Joins the parts of a composite key. NUL cannot occur in any of them. */
+export function cacheKey(...parts) {
+    return parts.map((part) => part ?? '').join('\u0000');
+}
+export class Cache {
+    kind;
+    #dir;
+    #mode;
+    /** entries read this run, so `commit` can say they are still wanted */
+    #used = new Set();
+    #hits = 0;
+    #misses = 0;
+    constructor(kind, options = {}) {
+        this.kind = kind;
+        this.#dir = join(options.dir ?? paths.cache(), kind);
+        this.#mode = options.mode;
+    }
+    get hits() {
+        return this.#hits;
+    }
+    get misses() {
+        return this.#misses;
+    }
+    #path(key) {
+        const sha = createHash('sha256')
+            .update(this.kind, 'utf8')
+            .update('\u0000', 'utf8')
+            .update(key, 'utf8')
+            .digest('hex');
+        return join(this.#dir, sha.slice(0, SHARD), `${sha}.json`);
+    }
+    entry(key) {
+        const path = this.#path(key);
+        let found;
+        try {
+            found = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            this.#misses++;
+            return undefined;
+        }
+        if (found?.kind !== this.kind || found.key !== key) {
+            this.#misses++;
+            return undefined;
+        }
+        this.#hits++;
+        this.#used.add(path);
+        return { value: found.value, storedAt: found.storedAt };
+    }
+    get(key) {
+        return this.entry(key)?.value;
+    }
+    put(key, value) {
+        const stored = {
+            kind: this.kind,
+            key,
+            storedAt: new Date().toISOString(),
+            value,
+        };
+        try {
+            writeJson(this.#path(key), stored, this.#mode);
+        }
+        catch {
+            // Out of disk, or the directory went away. Nothing depends on this.
+        }
+    }
+    delete(key) {
+        try {
+            rmSync(this.#path(key), { force: true });
+        }
+        catch {
+            // Still cached, then. It will be pruned by age eventually.
+        }
+    }
+    commit() {
+        const now = new Date();
+        for (const path of this.#used) {
+            try {
+                if (now.getTime() - statSync(path).mtimeMs > TOUCH_AFTER_MS) {
+                    utimesSync(path, now, now);
+                }
+            }
+            catch {
+                // Gone, or read-only. Neither is worth a word.
+            }
+        }
+        this.#used.clear();
+    }
+}
+/** Remembers nothing, for `--no-cache` and for anywhere a store cannot be opened. */
+export const NO_CACHE = {
+    kind: 'none',
+    hits: 0,
+    misses: 0,
+    entry: () => undefined,
+    get: () => undefined,
+    put: () => { },
+    delete: () => { },
+    commit: () => { },
+};
+const dirents = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).map((e) => ({
+            name: e.name,
+            dir: e.isDirectory(),
+            file: e.isFile(),
+        }));
+    }
+    catch {
+        return [];
+    }
+};
+/** Every entry file, kind by kind. Half-written `.tmp` siblings are not entries. */
+function* walk(dir, only) {
+    for (const kind of dirents(dir)) {
+        if (!kind.dir || (only !== undefined && kind.name !== only)) {
+            continue;
+        }
+        const kindDir = join(dir, kind.name);
+        for (const shard of dirents(kindDir)) {
+            if (!shard.dir) {
+                continue;
+            }
+            const shardDir = join(kindDir, shard.name);
+            for (const file of dirents(shardDir)) {
+                if (!file.file || !file.name.endsWith('.json')) {
+                    continue;
+                }
+                const path = join(shardDir, file.name);
+                try {
+                    const info = statSync(path);
+                    yield { kind: kind.name, path, bytes: info.size, usedAt: info.mtimeMs };
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+}
+/** A row per kind, for `zen cache ls`. One stat walk; nothing is parsed. */
+export function kinds(dir = paths.cache()) {
+    const rows = new Map();
+    for (const found of walk(dir)) {
+        const row = rows.get(found.kind) ?? { kind: found.kind, entries: 0, bytes: 0 };
+        row.entries++;
+        row.bytes += found.bytes;
+        row.oldest = Math.min(row.oldest ?? found.usedAt, found.usedAt);
+        row.newest = Math.max(row.newest ?? found.usedAt, found.usedAt);
+        rows.set(found.kind, row);
+    }
+    return [...rows.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+/**
+ * The entries of one kind, most recently used first. Reading a key means
+ * parsing the file, so the sort happens on stat data and only what will be
+ * shown is opened.
+ */
+export function items(kind, options = {}) {
+    const all = [...walk(options.dir ?? paths.cache(), kind)].sort((a, b) => b.usedAt - a.usedAt);
+    const take = options.limit === undefined ? all : all.slice(0, options.limit);
+    const rows = take.map((found) => {
+        const row = {
+            kind: found.kind,
+            key: '',
+            bytes: found.bytes,
+            usedAt: found.usedAt,
+        };
+        try {
+            const stored = JSON.parse(readFileSync(found.path, 'utf8'));
+            row.key = stored.key ?? '';
+            row.storedAt = stored.storedAt;
+            row.value = stored.value;
+        }
+        catch {
+            // An unreadable entry is still an entry taking up room.
+        }
+        return row;
+    });
+    return { rows, found: all.length };
+}
+/**
+ * Removes what the options describe and reports what went, by kind.
+ *
+ * `maxBytes` applies to the whole selection rather than to each kind
+ * separately: the disk is one thing, and least-recently-used across the store
+ * is the only ordering that means anything on it.
+ */
+export function sweep(options = {}) {
+    const dir = options.dir ?? paths.cache();
+    const cutoff = options.olderThanMs === undefined ? undefined : Date.now() - options.olderThanMs;
+    const kept = [];
+    const doomed = [];
+    for (const found of walk(dir, options.kind)) {
+        (cutoff !== undefined && found.usedAt < cutoff ? doomed : kept).push(found);
+    }
+    if (options.maxBytes !== undefined) {
+        kept.sort((a, b) => a.usedAt - b.usedAt);
+        let total = kept.reduce((n, f) => n + f.bytes, 0);
+        while (total > options.maxBytes && kept.length > 0) {
+            const found = kept.shift();
+            total -= found.bytes;
+            doomed.push(found);
+        }
+    }
+    const swept = new Map();
+    for (const found of doomed) {
+        try {
+            rmSync(found.path, { force: true });
+        }
+        catch {
+            continue;
+        }
+        const row = swept.get(found.kind) ?? { kind: found.kind, removed: 0, bytes: 0 };
+        row.removed++;
+        row.bytes += found.bytes;
+        swept.set(found.kind, row);
+    }
+    tidy(dir);
+    return [...swept.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+/** Everything, or one kind of everything. */
+export function clear(options = {}) {
+    const dir = options.dir ?? paths.cache();
+    try {
+        rmSync(options.kind === undefined ? dir : join(dir, options.kind), {
+            recursive: true,
+            force: true,
+        });
+    }
+    catch {
+        // Whatever survived will be reported by the next `ls`.
+    }
+}
+/** Drops the shard and kind directories a sweep emptied. */
+function tidy(dir) {
+    for (const kind of dirents(dir)) {
+        if (!kind.dir) {
+            continue;
+        }
+        const kindDir = join(dir, kind.name);
+        for (const shard of dirents(kindDir)) {
+            if (shard.dir) {
+                rmdir(join(kindDir, shard.name));
+            }
+        }
+        rmdir(kindDir);
+    }
+}
+function rmdir(dir) {
+    try {
+        rmdirSync(dir);
+    }
+    catch {
+        // Not empty, which is the usual answer.
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/catalog.d.ts

@@ -51,6 +51,7 @@ export interface Catalog {
 }
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export declare const CATALOG_TTL_MS: number;
+export declare const CATALOG_KIND = "catalog";
 /**
  * Enough to work with when the provider cannot be asked — offline, no
  * credential, or a listing endpoint that is down. Deliberately short: this is
@@ -80,6 +81,8 @@ export declare const PREFERRED: Record<Provider, {
  * `ProviderSpec.client`, which exists in the library for the same reason.
  */
 export declare function fetchCatalog(provider: Provider, client?: unknown): Promise<CatalogEntry[]>;
+/** The key one provider's listing is filed under, version and all. */
+export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {
     /** ignore a fresh cache and ask the provider again */
     refresh?: boolean;

package/dist/catalog.js

@@ -16,14 +16,15 @@
 // `source` for exactly that reason: a curated guess must never be mistaken for
 // the vendor's own word.
 // ---------------------------------------------------------------------------
-import { join } from 'node:path';
 import { ModelRegistry } from '@zenera/neo';
-import { paths, readJson, writeJson } from "./home.js";
+import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
-const CACHE_VERSION = 1;
+export const CATALOG_KIND = 'catalog';
+/** Bumped when the stored shape changes, which makes every old entry a miss. */
+const CATALOG_VERSION = 1;
 // ---------------------------------------------------------------------------
 // The fallback table
 // ---------------------------------------------------------------------------
@@ -341,10 +342,35 @@ function enrich(provider, live) {
         };
     });
 }
-const cachePath = (provider) => join(paths.catalog(), `${provider}.json`);
-async function readCache(provider) {
-    const file = await readJson(cachePath(provider), undefined);
-    return file?.version === CACHE_VERSION && Array.isArray(file.entries) ? file : undefined;
+/**
+ * Listings are public data, so the file is left readable — someone wondering
+ * where a model row came from can go and look at it. Opened per call rather
+ * than once, because the home directory is an environment variable and a test
+ * is allowed to move it.
+ */
+const store = () => new Cache(CATALOG_KIND, { mode: 0o644 });
+/**
+ * What else decides a listing's contents. Vertex answers per project and per
+ * location — one account was offered eight models at `us` and forty at
+ * `us-central1` — so a key naming only the provider serves one of those lists
+ * to both. A project left to the service-account file is not seen here.
+ */
+function scope(provider) {
+    if (provider !== 'vertex') {
+        return undefined;
+    }
+    return cacheKey(process.env.GOOGLE_CLOUD_PROJECT, process.env.GOOGLE_CLOUD_LOCATION ?? 'global');
+}
+/** The key one provider's listing is filed under, version and all. */
+export const catalogKey = (provider) => {
+    const extra = scope(provider);
+    return extra ? cacheKey(CATALOG_VERSION, provider, extra) : cacheKey(CATALOG_VERSION, provider);
+};
+function readCache(provider) {
+    const file = store().get(catalogKey(provider));
+    return file && Array.isArray(file.entries) && typeof file.fetchedAt === 'string'
+        ? file
+        : undefined;
 }
 /**
  * The listing for one provider, from the cheapest source that can answer.
@@ -356,7 +382,7 @@ async function readCache(provider) {
  * model list to four rows.
  */
 export async function loadCatalog(provider, opts = {}) {
-    const cached = await readCache(provider);
+    const cached = readCache(provider);
     const fresh = cached && Date.now() - new Date(cached.fetchedAt).getTime() < CATALOG_TTL_MS
         ? cached
         : undefined;
@@ -367,9 +393,7 @@ export async function loadCatalog(provider, opts = {}) {
         try {
             const entries = await fetchCatalog(provider);
             const fetchedAt = new Date().toISOString();
-            writeJson(cachePath(provider), { version: CACHE_VERSION, provider, fetchedAt, entries }, 
-            // Public data, and readable so a human can look at what was cached.
-            0o644);
+            store().put(catalogKey(provider), { provider, fetchedAt, entries });
             return { provider, entries, origin: 'live', fetchedAt };
         }
         catch (err) {

package/dist/commands/cache.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from '../command.ts';
+export declare const cache: Command;
+/** `30d`, `12h`, `2w`. A bare number is days: nobody means milliseconds. */
+export declare function duration(text: string | undefined): number | undefined;
+/** `500MB`, `2GB`. Powers of 1000, the way `bytes()` prints them back. */
+export declare function size(text: string | undefined): number | undefined;
+//# sourceMappingURL=cache.d.ts.map