@zenera/cli 1.1.2 → 1.1.4

package/README.md

@@ -22,12 +22,11 @@ carries your keys with it.
 
 ## Install
 
-Node.js 24+. Install the CLI together with at least one vendor SDK — they are
-**optional peer dependencies**, so you only pay for the ones you use.
+Node.js 24+. One command — the OpenAI, Anthropic, Google and OpenRouter SDKs
+all ship with the CLI, so any provider works out of the box.
 
 ```sh
-npm i -g @zenera/cli openai
-#                or @anthropic-ai/sdk, @google/genai, @openrouter/sdk — any mix of them
+npm i -g @zenera/cli
 ```
 
 Or without installing anything:
@@ -41,8 +40,8 @@ npx @zenera/cli --help
 Four commands, from nothing to an answer:
 
 ```sh
-npm i -g @zenera/cli openai   # the CLI, plus one vendor SDK
-zen key add openai           # prompts with the echo off; stored in ~/.zenera
+npm i -g @zenera/cli         # every vendor SDK comes with it
+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"
 ```
@@ -50,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
@@ -151,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
@@ -199,39 +199,236 @@ command — so `zen run … | jq` is a supported way to use it, not an accident.
 
 The binary is installed under three names: `zen`, `zn` and `zenera`.
 
+## Credentials
+
+One keyring serves every provider, and a key goes in the same way whatever it
+is for:
+
+```sh
+zen key add <provider>              # asks for the key without showing it
+zen key add <provider> < key.txt    # or pipe it in
+```
+
+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                      |
+| ------------ | ------------------------------------- | -------------------------------- |
+| `openai`     | a secret                              | `OPENAI_API_KEY`                 |
+| `anthropic`  | a secret                              | `ANTHROPIC_API_KEY`              |
+| `google`     | a secret — AI Studio                  | `GEMINI_API_KEY`                 |
+| `vertex`     | a path to a service-account JSON file | `GOOGLE_APPLICATION_CREDENTIALS` |
+| `openrouter` | a secret                              | `OPENROUTER_API_KEY`             |
+| `exa`        | a secret — for the search tool        | `EXA_API_KEY`                    |
+
+`zen key add` verifies the credential against the provider before it finishes,
+but stores it either way: a key that cannot be checked right now — offline,
+behind a proxy — is not a key that is wrong. `--no-check` skips the call.
+
+### Which key a model uses
+
+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 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 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. 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
+echo ~/keys/vertex-sa.json | zen key add vertex --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
+  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.
+
+### 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:
+
+```sh
+zen key add openai/work         # a second entry
+zen key use openai/work         # which one runs use
+zen key ls --check              # everything stored, and whether it still works
+zen key show vertex/default     # masked — --reveal prints the secret
+zen key env openai              # shell exports, for other tools
+zen key rm openai/work
+```
+
+`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
 
-Full specification:
-[packages/cli/DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/DESIGN.md).
-Also
-[DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/DESIGN.md) ·
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md)
-·
-[docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md).
+— the folder a project is ·
+[docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
+— every key in the configuration file.
 
 ## License
 

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;
 }
@@ -22,13 +25,15 @@ export interface ModelIssue {
  * Whether a requirement is actually met, and under which variable.
  *
  * `satisfied` is the library's answer and it is about api keys, which is the
- * wrong question for Vertex: that kind is `keyOptional` because it
- * authenticates from a service-account file instead. So the file-shaped
- * credential is looked for where the keyring keeps it.
+ * wrong question for Vertex: that kind is `keyOptional` because it can
+ * authenticate from a service-account file instead. So both of its variables
+ * are looked for, along with the file `gcloud` leaves behind.
  *
- * Exported because a report that named `VERTEX_API_KEY` while the audit
- * silently checked `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to
- * one question, and the wrong one is the one people would act on.
+ * The variable named back is the one that is actually set, because a report
+ * that named `VERTEX_API_KEY` while the audit silently checked
+ * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
+ * the wrong one is the one people would act on. With nothing set there is no
+ * such answer, so it names the form the provider is usually reached by.
  */
 export declare function credentialFor(need: ModelRequirement): {
     env: string;

package/dist/audit.js

@@ -1,8 +1,5 @@
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { projectRegistry, readProjectConfig, } from '@zenera/neo';
-import { SHAPES, isProvider } from "./keys.js";
+import { envNames, form, gcloudAdc, isProvider, SHAPES, } from "./keys.js";
 import { bold, dim } from "./term.js";
 /**
  * Every model the project names, keyed by how one would refer to it.
@@ -36,32 +33,27 @@ function declared(config) {
         ['embedding', embeddings],
     ]);
 }
-/**
- * `gcloud auth application-default login` writes here, and the GenAI SDK finds
- * it with no variable set — so without this check every developer using ADC
- * would be told their working Vertex setup is broken.
- */
-function hasGcloudAdc() {
-    const dir = process.env.CLOUDSDK_CONFIG ?? join(homedir(), '.config', 'gcloud');
-    return existsSync(join(dir, 'application_default_credentials.json'));
-}
 /**
  * Whether a requirement is actually met, and under which variable.
  *
  * `satisfied` is the library's answer and it is about api keys, which is the
- * wrong question for Vertex: that kind is `keyOptional` because it
- * authenticates from a service-account file instead. So the file-shaped
- * credential is looked for where the keyring keeps it.
+ * wrong question for Vertex: that kind is `keyOptional` because it can
+ * authenticate from a service-account file instead. So both of its variables
+ * are looked for, along with the file `gcloud` leaves behind.
  *
- * Exported because a report that named `VERTEX_API_KEY` while the audit
- * silently checked `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to
- * one question, and the wrong one is the one people would act on.
+ * The variable named back is the one that is actually set, because a report
+ * that named `VERTEX_API_KEY` while the audit silently checked
+ * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
+ * the wrong one is the one people would act on. With nothing set there is no
+ * such answer, so it names the form the provider is usually reached by.
  */
 export function credentialFor(need) {
     const provider = isProvider(need.kind) ? need.kind : undefined;
-    const shape = provider ? SHAPES[provider] : undefined;
-    if (shape?.holds === 'file') {
-        return { env: shape.env, present: Boolean(process.env[shape.env]) || hasGcloudAdc() };
+    // A provider with a file form can authenticate without an api key, which is
+    // the only thing `satisfied` knows how to look for.
+    if (provider && SHAPES[provider].forms.some((f) => f.holds === 'file')) {
+        const set = envNames(provider).find((name) => process.env[name]);
+        return { env: set ?? form(provider).env, present: Boolean(set) || Boolean(gcloudAdc()) };
     }
     return { env: need.apiKeyEnv, present: need.satisfied };
 }
@@ -111,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,
                 });
             }
@@ -138,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