@zenera/cli 1.1.28 → 1.1.29

package/README.md

@@ -117,6 +117,28 @@ Or without installing anything:
 npx @zenera/cli --help
 ```
 
+Tab completion for zsh, bash and fish - commands, projects, stored prompts - is
+set up automatically by the global npm install. It appends a guarded loader to
+your current shell's startup file, once. **Open a new terminal** to activate it;
+the installer cannot update the terminal where you ran npm.
+
+Setup respects `ZDOTDIR` for zsh and `XDG_CONFIG_HOME` for fish. For Bash on
+macOS it covers both login shells (the active `.bash_profile`, `.bash_login` or
+`.profile`) and non-login shells (`.bashrc`). The loader does nothing when `zen`
+is no longer installed.
+
+Local installs and `npx` do not change shell files. Automatic setup is skipped
+under root/sudo, in CI, on Windows, or when `$SHELL` is missing or unsupported.
+Disabling lifecycle scripts with `--ignore-scripts` also disables setup.
+If automatic setup is skipped or fails, or to enable another shell, run:
+
+```sh
+zen completion --install            # the shell you are in; --yes to skip the question
+zen completion fish --install       # or name one
+```
+
+Or add it yourself: `eval "$(zen completion zsh)"` in `~/.zshrc`.
+
 ## Quickstart
 
 From nothing to a specialized agent system:
@@ -557,24 +579,25 @@ The commands to run next are printed for you to read and type.
 
 ## 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.                 |
-| `models`  | What this machine can use - list, search, test, pick.                |
-| `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
-| `meta`    | Runs the meta agent over the project - the one that edits it.        |
-| `inspect` | Opens or rebuilds a run's `report.html`.                             |
-| `view`    | Shows a folder in the browser, redrawn live as its files change.     |
-| `memory`  | What the agents remember - size, listing, one node, or a whole page. |
-| `check`   | Validates the project and every file it names, and asks the models.  |
-| `export`  | Writes the project to a shareable zip archive.                       |
-| `import`  | Unpacks one, registers it, and runs nothing in it.                   |
-| `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.                                      |
+| 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. |
+| `meta`       | Runs the meta agent over the project - the one that edits it.        |
+| `inspect`    | Opens or rebuilds a run's `report.html`.                             |
+| `view`       | Shows a folder in the browser, redrawn live as its files change.     |
+| `memory`     | What the agents remember - size, listing, one node, or a whole page. |
+| `check`      | Validates the project and every file it names, and asks the models.  |
+| `export`     | Writes the project to a shareable zip archive.                       |
+| `import`     | Unpacks one, registers it, and runs nothing in it.                   |
+| `sandbox`    | Checks and prepares the container that command-line tools run in.    |
+| `cache`      | What work has been kept, and getting rid of it.                      |
+| `completion` | Tab completion for zsh, bash and fish - printed, or installed.       |
+| `version`    | CLI, library and Node versions.                                      |
 
 ### Commands from other packages
 
@@ -760,6 +783,9 @@ fixes and the memory are making runs cheaper; each case has its own
 every try. `start` prints a local address that shows those pages in a browser,
 with their diagrams drawn, updated in place as the tuning writes them.
 
+The whole method, with how to write a rubric that tunes the right thing:
+[docs/finetuning.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/finetuning.md).
+
 ## Credentials
 
 One keyring serves every provider, and a key goes in the same way whatever it
@@ -816,7 +842,6 @@ zen models openai                           # everything OpenAI serves this acco
 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
 zen models browse                           # walk providers and models with the arrow keys
 ```
 
@@ -840,15 +865,15 @@ $ zen models test vertex:gemini-embedding-001
 vertex:gemini-embedding-001  blocked  Vertex AI API has not been used in project my-proj …
 fix 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
+        see what else there is: zen models ls --embeddings
 ```
 
-`zen models pick` tries a short list of candidates one at a time, stops at the
-first that works, and prints the bare reference on stdout. So recovering from
-the above is a single substitution, whether a person or an agent is doing it:
+To take another model instead, list what the account serves, test one, and put
+its ref in `agents.yaml` or the flag that needs it:
 
 ```sh
-zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
+zen models ls --embeddings
+zen models test openai:text-embedding-3-small
 ```
 
 `zen models browse [provider]` is the interactive way in: arrow keys through
@@ -1026,6 +1051,26 @@ clear where a working provider actually comes from.
 
 </details>
 
+<details>
+<summary><strong>Every model through a Bifrost gateway</strong></summary>
+
+With one virtual key in place of every vendor key:
+
+```sh
+zen key add bifrost --url https://bifrost.example.com
+zen key mode bifrost            # every run goes through the gateway
+zen key mode direct             # back to the vendor keys
+```
+
+`agents.yaml` does not change. Each model keeps its own vendor's protocol and
+is sent to the gateway's matching endpoint - `vertex:gemini-3.5-flash` reaches
+`/genai` as `vertex/gemini-3.5-flash` - so thinking and cache accounting
+survive the trip. The whole story - variables, the sandbox, `zen models`, known
+limits - is in
+[docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md).
+
+</details>
+
 ## Cache - work you have already paid for
 
 Embedding a paragraph, parsing a document, asking a provider what it serves: all
@@ -1075,6 +1120,10 @@ terminal:
     - making an API description searchable and mockable.
 - [docs/memory.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/memory.md)
     - what agents keep between sessions.
+- [docs/finetuning.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/finetuning.md)
+    - building a dataset, writing rubrics, and tuning the project on them.
+- [docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md)
+    - every model through a Bifrost gateway, with one virtual key.
 
 ## License
 

package/dist/audit.d.ts

@@ -1,5 +1,5 @@
 import { type ModelRequirement } from '@zenera/neo';
-import { type KeyStore, type Provider } from './keys.ts';
+import { type KeyOwner, type KeyStore } from './keys.ts';
 /** Which key of the config named a reference: `model:`/`models:` or `embedding:`/`embeddings:`. */
 export type DeclaredRole = 'model' | 'embedding';
 export interface ModelIssue {
@@ -19,7 +19,7 @@ export interface ModelIssue {
     /** 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;
+    add?: KeyOwner;
 }
 /**
  * Whether a requirement is actually met, and under which variable.

package/dist/audit.js

@@ -1,5 +1,5 @@
 import { projectRegistry, readProjectConfig, } from '@zenera/neo';
-import { envNames, form, gcloudAdc, isProvider, SHAPES, } from "./keys.js";
+import { envNames, form, gcloudAdc, isOwner, isProvider, SHAPES, } from "./keys.js";
 import { bold, dim } from "./term.js";
 /**
  * Every model the project names, keyed by how one would refer to it.
@@ -48,6 +48,9 @@ function declared(config) {
  * such answer, so it names the form the provider is usually reached by.
  */
 export function credentialFor(need) {
+    if (need.gateway) {
+        return { env: need.apiKeyEnv, present: need.satisfied };
+    }
     const provider = isProvider(need.kind) ? need.kind : undefined;
     // A provider with a file form can authenticate without an api key, which is
     // the only thing `satisfied` knows how to look for.
@@ -86,7 +89,11 @@ export function auditModels(projectDir, store) {
                 continue;
             }
             const { env, present } = credentialFor(need);
-            const provider = isProvider(need.kind) ? need.kind : undefined;
+            const provider = need.gateway && isOwner(need.gateway)
+                ? need.gateway
+                : isProvider(need.kind)
+                    ? need.kind
+                    : undefined;
             if (!present) {
                 issues.push({
                     name,
@@ -132,8 +139,8 @@ export function describeIssue(issue) {
     }
     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 list = `zen models ls --${issue.role === 'embedding' ? 'embeddings' : 'chat'}`;
+        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? list)}`;
     }
     const fix = `zen key check ${issue.add ?? ''}`.trim();
     return `${what} was rejected when last checked${why} — ${dim(fix)}`;

package/dist/candidates.d.ts

@@ -0,0 +1,9 @@
+export interface Candidate {
+    value: string;
+    description?: string;
+}
+/** Candidates the word being typed is a prefix of. */
+export declare const matching: (found: readonly Candidate[], prefix: string) => Candidate[];
+/** Registered projects whose directory is still there. */
+export declare function projectNames(): Promise<Candidate[]>;
+//# sourceMappingURL=candidates.d.ts.map

package/dist/candidates.js

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs';
+import * as Projects from "./projects.js";
+/** Candidates the word being typed is a prefix of. */
+export const matching = (found, prefix) => found.filter((c) => c.value.startsWith(prefix));
+/** Registered projects whose directory is still there. */
+export async function projectNames() {
+    try {
+        const registry = await Projects.Registry.open();
+        return registry.entries
+            .filter((e) => existsSync(e.path))
+            .map((e) => ({ value: e.name, description: e.path }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=candidates.js.map

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { type Gateway } from '@zenera/neo';
 import { type KeyCheck, type Provider } from './keys.ts';
 /**
  * What a model is *for*. A model can hold more than one — Gemini's embedding
@@ -50,6 +51,11 @@ export interface Catalog {
     fetchedAt: string;
     /** why the live call was not used, when it was tried and failed */
     problem?: KeyCheck;
+    /** the gateway it was listed through, when the keyring is in a gateway mode */
+    via?: {
+        name: string;
+        url: string;
+    };
 }
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export declare const CATALOG_TTL_MS: number;
@@ -64,11 +70,8 @@ export declare const CATALOG_KIND = "catalog";
  */
 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.
+ * The cheap, fast models per provider and role, best first. `zen init` takes
+ * its default embedder from here.
  */
 export declare const PREFERRED: Record<Provider, {
     chat: readonly string[];
@@ -85,6 +88,8 @@ export declare function fromVertexPartners(): Promise<CatalogEntry[]>;
  * `partners` is the same seam for Vertex's second listing.
  */
 export declare function fetchCatalog(provider: Provider, client?: unknown, partners?: () => Promise<CatalogEntry[]>): Promise<CatalogEntry[]>;
+/** What the gateway serves under one provider's name, enriched like a vendor listing. */
+export declare function fetchGatewayCatalog(provider: Provider, at: Gateway): Promise<CatalogEntry[]>;
 /** The key one provider's listing is filed under, version and all. */
 export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {

package/dist/catalog.js

@@ -16,7 +16,7 @@
 // `source` for exactly that reason: a curated guess must never be mistaken for
 // the vendor's own word.
 // ---------------------------------------------------------------------------
-import { ModelRegistry, vertexEndpoint } from '@zenera/neo';
+import { GATEWAY_KEY_HEADER, GATEWAY_NAME, GATEWAY_UPSTREAMS, gatewayOf, ModelRegistry, vertexEndpoint, } from '@zenera/neo';
 import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
@@ -72,11 +72,8 @@ export const CURATED = {
     ],
 };
 /**
- * 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.
+ * The cheap, fast models per provider and role, best first. `zen init` takes
+ * its default embedder from here.
  */
 export const PREFERRED = {
     openai: {
@@ -369,6 +366,65 @@ export async function fetchCatalog(provider, client = new ModelRegistry().client
             return enrich(provider, await fromRouter(client, provider));
     }
 }
+const UPSTREAM_OF = new Map(PROVIDERS.map((p) => [GATEWAY_UPSTREAMS[p], p]));
+/** One request per gateway per process, however many providers ask. */
+const listings = new Map();
+function gatewayListing(at) {
+    const key = `${at.baseURL}\0${at.apiKey ?? ''}`;
+    let listing = listings.get(key);
+    if (!listing) {
+        listing = fetchGatewayListing(at);
+        listings.set(key, listing);
+        listing.catch(() => listings.delete(key));
+    }
+    return listing;
+}
+async function fetchGatewayListing(at) {
+    const res = await fetch(`${at.baseURL}/v1/models`, {
+        headers: at.apiKey
+            ? { authorization: `Bearer ${at.apiKey}`, [GATEWAY_KEY_HEADER]: at.apiKey }
+            : {},
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw Object.assign(new Error(`${GATEWAY_NAME} answered ${res.status}: ${body}`), {
+            status: res.status,
+        });
+    }
+    const { data } = (await res.json());
+    const by = new Map();
+    for (const model of data ?? []) {
+        if (typeof model.id !== 'string') {
+            continue;
+        }
+        const slash = model.id.indexOf('/');
+        const provider = slash > 0 ? UPSTREAM_OF.get(model.id.slice(0, slash)) : undefined;
+        const id = model.id.slice(slash + 1);
+        const role = openaiRole(id);
+        if (!provider || !id || !role) {
+            continue;
+        }
+        const rows = by.get(provider) ?? [];
+        rows.push(entry(provider, {
+            id,
+            roles: [role],
+            name: typeof model.name === 'string' ? model.name : undefined,
+            contextLength: typeof model.context_length === 'number' ? model.context_length : undefined,
+            created: iso(typeof model.created === 'number' ? model.created : undefined),
+            publisher: provider === 'vertex' ? publisherOf(id) : undefined,
+        }));
+        by.set(provider, rows);
+    }
+    return by;
+}
+function publisherOf(id) {
+    return /^claude-/.test(id) ? 'anthropic' : id.includes('/') ? id.split('/')[0] : 'google';
+}
+/** What the gateway serves under one provider's name, enriched like a vendor listing. */
+export async function fetchGatewayCatalog(provider, at) {
+    return enrich(provider, (await gatewayListing(at)).get(provider) ?? []);
+}
 // ---------------------------------------------------------------------------
 // Enrichment and cache
 // ---------------------------------------------------------------------------
@@ -407,6 +463,10 @@ const store = () => new Cache(CATALOG_KIND, { mode: 0o644 });
  * to both. A project left to the service-account file is not seen here.
  */
 function scope(provider) {
+    const at = gatewayOf();
+    if (at) {
+        return cacheKey(GATEWAY_NAME, at.baseURL);
+    }
     if (provider !== 'vertex') {
         return undefined;
     }
@@ -433,19 +493,31 @@ function readCache(provider) {
  * model list to four rows.
  */
 export async function loadCatalog(provider, opts = {}) {
+    const at = gatewayOf();
+    const via = at ? { via: { name: GATEWAY_NAME, url: at.baseURL } } : {};
+    // The built-in list names vendor models the gateway may not serve at all.
+    const fallback = () => (at ? [] : curated(provider));
     const cached = readCache(provider);
     const fresh = cached && Date.now() - new Date(cached.fetchedAt).getTime() < CATALOG_TTL_MS
         ? cached
         : undefined;
     if (fresh && !opts.refresh) {
-        return { provider, entries: fresh.entries, origin: 'cache', fetchedAt: fresh.fetchedAt };
+        return {
+            provider,
+            entries: fresh.entries,
+            origin: 'cache',
+            fetchedAt: fresh.fetchedAt,
+            ...via,
+        };
     }
     if (!opts.offline) {
         try {
-            const entries = await fetchCatalog(provider);
+            const entries = at
+                ? await fetchGatewayCatalog(provider, at)
+                : await fetchCatalog(provider);
             const fetchedAt = new Date().toISOString();
             store().put(catalogKey(provider), { provider, fetchedAt, entries });
-            return { provider, entries, origin: 'live', fetchedAt };
+            return { provider, entries, origin: 'live', fetchedAt, ...via };
         }
         catch (err) {
             const problem = classify(err);
@@ -456,25 +528,34 @@ export async function loadCatalog(provider, opts = {}) {
                     origin: 'stale',
                     fetchedAt: cached.fetchedAt,
                     problem,
+                    ...via,
                 };
             }
             return {
                 provider,
-                entries: curated(provider),
+                entries: fallback(),
                 origin: 'curated',
                 fetchedAt: new Date(0).toISOString(),
                 problem,
+                ...via,
             };
         }
     }
     if (cached) {
-        return { provider, entries: cached.entries, origin: 'stale', fetchedAt: cached.fetchedAt };
+        return {
+            provider,
+            entries: cached.entries,
+            origin: 'stale',
+            fetchedAt: cached.fetchedAt,
+            ...via,
+        };
     }
     return {
         provider,
-        entries: curated(provider),
+        entries: fallback(),
         origin: 'curated',
         fetchedAt: new Date(0).toISOString(),
+        ...via,
     };
 }
 // ---------------------------------------------------------------------------

package/dist/commands/completion.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../command.ts';
+export { install, installed, loader, rcFile } from '../completion-install.ts';
+/**
+ * Prints the shell's side of tab completion. The script is a few lines that
+ * call back into `zen __complete`, so the project names and stored prompts it
+ * offers are always read from the machine it runs on, never baked in.
+ */
+export declare const completion: Command;
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.js

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { one, parse } from "../args.js";
+import { install, installed, loader, rcFiles, shellOf } from "../completion-install.js";
+import { TEMPLATES } from "../scaffold.js";
+import { bold, confirm, usageError, write } from "../term.js";
+export { install, installed, loader, rcFile } from "../completion-install.js";
+const USAGE = 'zen completion [<zsh|bash|fish>] [--install [--yes]]';
+/**
+ * Prints the shell's side of tab completion. The script is a few lines that
+ * call back into `zen __complete`, so the project names and stored prompts it
+ * offers are always read from the machine it runs on, never baked in.
+ */
+export const completion = {
+    summary: 'Print the tab-completion script for your shell.',
+    usage: USAGE,
+    banner: { head: 'Zenera', accent: 'Completion', subtitle: 'Shell Integration', hue: 'magenta' },
+    quiet: () => true,
+    details: [
+        'Global npm installs set this up automatically. Open a new shell afterward.',
+        '',
+        'Add one line to your shell’s startup file:',
+        '  zsh    eval "$(zen completion zsh)"      in ~/.zshrc',
+        '  bash   eval "$(zen completion bash)"     in ~/.bashrc',
+        '  fish   zen completion fish | source      in ~/.config/fish/config.fish',
+        '',
+        'Or let zen do it — it appends that line to the file, once, after asking:',
+        '  zen completion --install                 for the shell you are in',
+        '  zen completion zsh --install --yes       without asking',
+        '',
+        'Then, in a new shell:',
+        '  zen meta run my-project /<Tab>           the project’s stored prompts',
+        '  zen meta <Tab>                           run, prompts, resume, model …',
+        '  zen run <Tab>                            your projects',
+        '',
+        'The prompts are the files in .github/prompts/ — the same ones an editor',
+        'offers as slash commands. Where there is nothing to offer, file names are.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, { install: { type: 'boolean' }, yes: { type: 'boolean' } }, USAGE);
+        const name = one(positionals, 'shell', USAGE) ?? basename(process.env.SHELL ?? '');
+        const shell = shellOf(name);
+        if (!shell) {
+            throw usageError(name ? `no completion for "${name}"` : 'which shell?', 'try: zen completion zsh|bash|fish');
+        }
+        if (values.yes && !values.install) {
+            throw usageError('--yes only goes with --install', USAGE);
+        }
+        if (values.install) {
+            const files = rcFiles(shell).filter((file) => !installed(shell, file));
+            if (files.length === 0) {
+                write(`Already set up in ${rcFiles(shell).join(', ')}.`);
+                return;
+            }
+            const line = bold(loader(shell));
+            if (!values.yes && !(await confirm(`Add ${line} to ${files.join(', ')}?`, true))) {
+                write('Nothing changed.');
+                return;
+            }
+            for (const file of files) {
+                install(shell, file);
+                write(`Added to ${file}.`);
+            }
+            write('Open a new shell to use tab completion.');
+            return;
+        }
+        process.stdout.write(readFileSync(`${TEMPLATES}/completions/zen.${shell}`, 'utf8'));
+    },
+};
+//# sourceMappingURL=completion.js.map

package/dist/commands/index.js

@@ -1,5 +1,6 @@
 import { cache } from "./cache.js";
 import { check } from "./check.js";
+import { completion } from "./completion.js";
 import { pack } from "./export.js";
 import { unpack } from "./import.js";
 import { init } from "./init.js";
@@ -39,6 +40,7 @@ export const COMMANDS = {
     memory,
     sandbox,
     cache,
+    completion,
     version,
 };
 /** Names that are not listed in help but still work. */

package/dist/commands/init.js

@@ -47,7 +47,7 @@ const DEFAULT_MODEL = {
 /**
  * What vectorises the project's memory, given the provider it ends up on.
  *
- * Taken from the same table `zen models pick` ranks by rather than written out
+ * Taken from the catalogue's `PREFERRED` table rather than written out
  * again here, so the scaffold cannot drift from what the catalogue calls
  * current. Anthropic publishes no embeddings API, and a `--model` naming a
  * provider we do not ship gives nothing to guess from; both scaffold without