@zenera/cli 1.1.3 → 1.1.4

package/README.md

@@ -41,7 +41,7 @@ Four commands, from nothing to an answer:
 
 ```sh
 npm i -g @zenera/cli         # every vendor SDK comes with it
-zen key add openai           # prompts with the echo off; stored in ~/.zenera
+zen key add openai           # asks for the key without showing it; stored in ~/.zenera
 zen init my-project          # scaffolds a project and registers it
 cd my-project && zen run "introduce yourself"
 ```
@@ -49,7 +49,7 @@ cd my-project && zen run "introduce yourself"
 Then the rest of the loop:
 
 ```sh
-zen run                         # nothing to say yet — a TUI on a terminal
+zen run                         # nothing to say yet — a full-screen terminal app (a TUI)
 zen check                       # validate the project and every file it names
 zen inspect                     # open the last run's report.html
 zen list --sessions             # every project, its sessions and last run
@@ -150,17 +150,18 @@ you are not expected to hand-author `agents.yaml`.
 
 ## Commands
 
-| Command   | Does                                                                     |
-| --------- | ------------------------------------------------------------------------ |
-| `init`    | Creates a project here, or in `<dir>`, and registers it.                 |
-| `list`    | Every known project: sessions, last run, whether one is live.            |
-| `open`    | Opens a project in your editor.                                          |
-| `key`     | The credential keyring — add, check, switch, remove.                     |
-| `run`     | Runs the project — the TUI on a terminal, one shot otherwise.            |
-| `inspect` | Opens or rebuilds a run's `report.html`.                                 |
-| `models`  | Resolves providers and models and validates the config, calling nothing. |
-| `sandbox` | Checks and prepares the container that command-line tools run in.        |
-| `version` | CLI, library and Node versions.                                          |
+| Command   | Does                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `init`    | Creates a project here, or in `<dir>`, and registers it.             |
+| `list`    | Every known project: sessions, last run, whether one is live.        |
+| `open`    | Opens a project in your editor.                                      |
+| `key`     | The credential keyring — add, check, switch, remove.                 |
+| `models`  | What this machine can use — list, search, test, pick.                |
+| `run`     | Runs the project — the TUI on a terminal, a single answer otherwise. |
+| `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.    |
+| `version` | CLI, library and Node versions.                                      |
 
 Commands can also come from a package installed alongside this one, so a new
 capability is a subcommand rather than a new binary to remember — one thing on
@@ -204,16 +205,16 @@ One keyring serves every provider, and a key goes in the same way whatever it
 is for:
 
 ```sh
-zen key add <provider>              # prompts with the echo off
-zen key add <provider> < key.txt    # or pipe it
+zen key add <provider>              # asks for the key without showing it
+zen key add <provider> < key.txt    # or pipe it in
 ```
 
-The value never comes from argv — a command line lands in `ps`, in shell
-history and in CI logs — so piped stdin and the echo-off prompt are the only
-two ways in. Entries live in `~/.zenera/neo/keys.json` (mode `0600`) and are
-materialised into the environment just before a run, so a real environment
-variable always wins and a project checked out on a machine without `zen` still
-runs.
+The value is never given as an argument — a command line is visible to anyone
+listing running processes, is saved in your shell history and is captured in CI
+logs — so piping it in and the hidden prompt are the only two ways. Entries live
+in `~/.zenera/neo/keys.json`, in a file only you can read, and 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.
 
 | Provider     | The value is                          | Exported as                      |
 | ------------ | ------------------------------------- | -------------------------------- |
@@ -234,22 +235,76 @@ A model reference is `[provider[/api]:]model`, and the first segment names a
 **provider, not a vendor**. So `vertex:gemini-3.5-flash` and
 `google:gemini-3.5-flash` are the same model reached through two different
 services, needing two different credentials — and a bare `gpt-5.4-mini` goes to
-the default provider, `openai`. `zen models` resolves every reference in a
-project against what is stored, and calls nothing.
+the default provider, `openai`. `zen check` resolves every reference in a
+project against what is stored, says which credential each one needs, and spends
+a few tokens asking each of them to answer — the only way to catch a model id
+this account is not served. `--no-models` stops before the asking.
+
+### Which models you can use
+
+`zen check` answers _does my project work_. `zen models` answers _what can I
+use_, needs no project, and asks the providers themselves:
+
+```sh
+zen models                                  # who has a credential, and what is cached
+zen models openai                           # everything OpenAI serves this account
+zen models search haiku --tools --free      # narrow it
+zen models show openrouter:anthropic/claude-haiku-4.5
+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
+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.
+
+`test` distinguishes three failures, because they want three different actions.
+A **refused** model means the credential was rejected. A **blocked** one means
+the credential was accepted and the account then said no — an API switched off,
+an empty balance, a model this key was never granted — and the fix comes with
+it:
+
+```
+$ zen models test vertex:gemini-embedding-001
+vertex:gemini-embedding-001  blocked  Vertex AI API has not been used in project my-proj …
+vertex:gemini-embedding-001: gcloud services enable aiplatform.googleapis.com --project my-proj
+error 1 of 1 did not answer
+        find one that does: zen models pick --embedding
+```
+
+`pick` tries a short list of candidates one at a time and stops at the first
+that works, printing the bare ref on stdout — so recovering from the above is
+one substitution, whether a person or an agent is doing it:
+
+```sh
+zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
+```
 
 ### Vertex AI
 
-Vertex accepts either shape, and which one you gave is read off the value.
+Vertex takes two kinds of credential, and you never say which you are giving:
+if the value is a path to a file that exists it is a service-account key, and
+otherwise it is treated as an API key. The name you choose for the entry has no
+say in it — `vertex/express` is simply an entry called `express`, exactly as
+`vertex/prod` is one called `prod`, and either name can hold either kind.
 
 The usual one is a **service-account JSON file** — give its path, not its
-contents:
+contents. Run the command with nothing piped and it asks:
+
+```sh
+zen key add vertex --location us-central1
+# Paste the key, or a path to the file: /Users/you/keys/vertex-sa.json
+```
+
+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
-printf '%s' ~/keys/vertex-sa.json | zen key add vertex --location us-central1
+echo ~/keys/vertex-sa.json | zen key add vertex --location us-central1
 ```
 
-The file is copied into `~/.zenera/neo/keys/` at mode `0600`, so moving or
-cleaning up the original later cannot break it.
+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`
@@ -258,10 +313,73 @@ cleaning up the original later cannot break it.
 - `--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**, an ordinary secret under
-`VERTEX_API_KEY`. Express mode addresses no project, so `--project` and
+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.
 
+### Gemini, three ways
+
+The same Gemini models are reachable through three different credentials, and
+which one you hold decides the prefix a model reference needs.
+
+**AI Studio** — one key and nothing else to configure, the shortest way to a
+working `gemini-3.5-flash`:
+
+```sh
+zen key add google                # asks for the key without showing it
+zen check                         # google:gemini-3.5-flash now resolves
+```
+
+**Vertex, service account** — what production usually runs on. Give the path
+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
+```
+
+Add `--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
+```
+
+**Vertex, express mode** — paste the key at the prompt; no flags apply:
+
+```sh
+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
+zen key add vertex/express       # the express key, same provider
+
+zen key use vertex/dev           # which one the next run uses
+zen key ls --check               # all three, and whether they still work
+zen key show vertex/prod         # masked; --reveal prints the path
+```
+
+`google` and `vertex` can both be configured — they are separate entries for
+separate services, and the reference picks:
+
+```sh
+zen run --model google:gemini-3.5-flash "summarise this repo"
+zen run --model vertex:gemini-3.5-flash "summarise this repo"
+```
+
+If you have already run `gcloud auth application-default login`, that login is
+itself a usable credential: `zen key ls` shows it as `adc`, marked `~` because
+it came from outside the keyring, and Vertex works with nothing stored at all.
+Anything already set in `GOOGLE_APPLICATION_CREDENTIALS`, `VERTEX_API_KEY` or
+`GEMINI_API_KEY` is listed the same way and wins over the keyring, so it is
+always visible which credential a run will actually use.
+
 ### More than one key per provider
 
 Entries are named, so a provider can hold several and one of them is active:
@@ -275,32 +393,34 @@ zen key env openai              # shell exports, for other tools
 zen key rm openai/work
 ```
 
-`zen key ls` marks the active entry with `*`, and something it found in your
-real environment or in `gcloud`'s ADC with `~`, so it is always clear where a
-working provider actually comes from.
+`zen key ls` marks the active entry with `*`, and anything it found outside the
+keyring — in your environment, or in a `gcloud` login — with `~`, so it is always
+clear where a working provider actually comes from.
 
 ## Concepts
 
 - **Project** — a named directory holding a complete agent definition and the
   sessions that ran against it. Self-describing: `agents.yaml` is what makes it
   one, so moving or cloning the directory loses nothing.
-- **Session** — a context that persists: one workspace, one memory, one blob
-  store, one accumulating trajectory. Resumable.
+- **Session** — a context that persists: one workspace, one memory, one store
+  for large files, and a record of everything that happened, added to as it
+  goes. Resumable.
 - **Run** — one prompt in, one answer out, inside a session. Recorded in full,
   whether or not you were watching.
 - **Workspace** — the directory the agents may read and write. A prompt given on
   the command line uses the current directory; the TUI offers the session's own
   empty folder and confirms anything outside it.
-- **Keyring** — `~/.zenera/neo`, mode `0700`. Keys are materialised into the
-  environment just before a run, so a real env var always wins and a project
-  checked out on a machine without `zen` still runs.
+- **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.
 
 ## The library underneath
 
 This is a shell over
 [`@zenera/neo`](https://www.npmjs.com/package/@zenera/neo) — agents, models,
-tools, skills, memory and an append-only trajectory. Use it directly when you
-want the runtime inside your own application rather than on a terminal:
+tools, skills, memory and a running record of everything that happened. Use it
+directly when you want the runtime inside your own application rather than on a
+terminal:
 [its README](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/neo/README.md).
 
 ## Documentation

package/dist/audit.d.ts

@@ -11,10 +11,13 @@ export interface ModelIssue {
     provider: string;
     /** the variable that would carry the credential */
     env: string;
-    /** `missing` — nothing to authenticate with. `dead` — rejected when checked. */
-    reason: 'missing' | 'dead';
+    /** `missing` — nothing to authenticate with. `dead` — rejected when checked.
+     *  `blocked` — accepted, and then refused by the account behind it. */
+    reason: 'missing' | 'dead' | 'blocked';
     /** the provider's own words, when it was the one to say no */
     detail?: string;
+    /** what to do about a refusal that a new key would not fix */
+    fix?: string;
     /** the keyring provider the fix names, when the kind is one of them */
     add?: Provider;
 }

package/dist/audit.js

@@ -103,14 +103,15 @@ export function auditModels(projectDir, store) {
             // reinstated between the check and the run, and a stale verdict must
             // not be the thing that stops a run from being attempted.
             const check = provider ? store.active(provider)?.check : undefined;
-            if (check?.state === 'dead') {
+            if (check?.state === 'dead' || check?.state === 'blocked') {
                 issues.push({
                     name,
                     role,
                     provider: need.provider,
                     env,
-                    reason: 'dead',
+                    reason: check.state,
                     detail: check.detail,
+                    fix: check.fix,
                     add: provider,
                 });
             }
@@ -130,6 +131,10 @@ export function describeIssue(issue) {
         return `${what} has no credential — ${issue.env} is not set; ${dim(fix)}`;
     }
     const why = issue.detail ? `: ${issue.detail}` : '';
+    if (issue.reason === 'blocked') {
+        const pick = `zen models pick --${issue.role === 'embedding' ? 'embedding' : 'chat'}`;
+        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? pick)}`;
+    }
     const fix = `zen key check ${issue.add ?? ''}`.trim();
     return `${what} was rejected when last checked${why} — ${dim(fix)}`;
 }

package/dist/catalog.d.ts

@@ -0,0 +1,111 @@
+import { type KeyCheck, type Provider } from './keys.ts';
+/**
+ * What a model is *for*. A model can hold more than one — Gemini's embedding
+ * endpoint and its chat endpoint are the same catalog row on some providers —
+ * so this is a set rather than a field.
+ */
+export type Role = 'chat' | 'embedding' | 'image' | 'audio';
+export interface CatalogEntry {
+    /** `provider:id` — paste-able straight into `agents.yaml` */
+    ref: string;
+    /** the id that goes on the wire, with any resource prefix already stripped */
+    id: string;
+    provider: Provider;
+    roles: Role[];
+    name?: string;
+    description?: string;
+    /** total tokens the model will accept in one request */
+    contextLength?: number;
+    maxOutputTokens?: number;
+    /** embeddings only, when the vendor publishes it */
+    dimensions?: number;
+    modalities?: {
+        input?: string[];
+        output?: string[];
+    };
+    supports?: {
+        tools?: boolean;
+        reasoning?: boolean;
+        vision?: boolean;
+    };
+    /** USD per token, as the vendor writes it — strings, because they are tiny */
+    pricing?: {
+        prompt?: string;
+        completion?: string;
+        free?: boolean;
+    };
+    /** ISO date the model was published, when known */
+    created?: string;
+    source: 'live' | 'curated';
+}
+/** A provider's listing, and an honest account of where it came from. */
+export interface Catalog {
+    provider: Provider;
+    entries: CatalogEntry[];
+    /** `live` asked just now; `cache` a fresh file; `stale` an expired one; `curated` the fallback */
+    origin: 'live' | 'cache' | 'stale' | 'curated';
+    /** when the entries were actually fetched, not when they were read */
+    fetchedAt: string;
+    /** why the live call was not used, when it was tried and failed */
+    problem?: KeyCheck;
+}
+/** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
+export declare const CATALOG_TTL_MS: number;
+/**
+ * Enough to work with when the provider cannot be asked — offline, no
+ * credential, or a listing endpoint that is down. Deliberately short: this is
+ * the set worth typing, not the set that exists.
+ *
+ * Anthropic publishes no embeddings API at all, which is why it has no
+ * embedding row here and why the registry throws rather than guessing.
+ */
+export declare const CURATED: Record<Provider, readonly Omit<CatalogEntry, 'ref' | 'provider' | 'source'>[]>;
+/**
+ * The order `zen models pick` walks, per provider and per role.
+ *
+ * Cheap and fast first. `pick` exists to answer "give me something that works"
+ * in one round trip where it can, and the small models answer soonest and cost
+ * least when the answer is thrown away — which it always is.
+ */
+export declare const PREFERRED: Record<Provider, {
+    chat: readonly string[];
+    embedding: readonly string[];
+}>;
+/**
+ * Asks one provider what it serves. Throws whatever the SDK throws.
+ *
+ * `client` is a seam, not a feature: the four adapters are the part most likely
+ * to break when a vendor reshapes a payload, and they are untestable if the
+ * only way to reach them is a credential and a network. It mirrors
+ * `ProviderSpec.client`, which exists in the library for the same reason.
+ */
+export declare function fetchCatalog(provider: Provider, client?: unknown): Promise<CatalogEntry[]>;
+export interface CatalogOptions {
+    /** ignore a fresh cache and ask the provider again */
+    refresh?: boolean;
+    /** do not make a network call at all — cache, however old, then curated */
+    offline?: boolean;
+}
+/**
+ * The listing for one provider, from the cheapest source that can answer.
+ *
+ * Fresh cache, else the provider, else a *stale* cache, else the curated table.
+ * Stale-before-curated is the important ordering: yesterday's real answer from
+ * this account beats today's guess about accounts in general, and a listing
+ * that failed because the wifi dropped should not silently shrink someone's
+ * model list to four rows.
+ */
+export declare function loadCatalog(provider: Provider, opts?: CatalogOptions): Promise<Catalog>;
+/** Every provider asked at once — they are independent and mostly latency. */
+export declare function loadCatalogs(providers: readonly Provider[], opts?: CatalogOptions): Promise<Catalog[]>;
+export interface Filters {
+    roles?: readonly Role[];
+    tools?: boolean;
+    vision?: boolean;
+    free?: boolean;
+    minContext?: number;
+}
+export declare function matches(row: CatalogEntry, query: string, filters?: Filters): boolean;
+/** The providers a search covers when none was named. */
+export declare const catalogProviders: () => readonly Provider[];
+//# sourceMappingURL=catalog.d.ts.map