@zenera/cli 1.1.30 → 1.1.32

package/README.md

@@ -14,6 +14,9 @@
 [![npm](https://img.shields.io/npm/v/@zenera/cli.svg)](https://www.npmjs.com/package/@zenera/cli)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/andreyryabov/ZeneraNeo/actions/workflows/ci.yml/badge.svg)](https://github.com/andreyryabov/ZeneraNeo/actions/workflows/ci.yml)
+
+[Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) · [Documentation](#documentation) · [Family](#the-rest-of-the-family) · [License](#license)
 
 </div>
 
@@ -1125,6 +1128,16 @@ terminal:
 - [docs/gateway.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/gateway.md)
     - every model through a Bifrost gateway, with one virtual key.
 
+## The rest of the family
+
+| Package                                                                                         | What it is                                                    |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **`@zenera/cli`**                                                                               | `zen` - agent projects on the command line                    |
+| [`@zenera/neo`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/neo/README.md)     | the runtime - agents, models, tools, skills, memory           |
+| [`@zenera/faker`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md) | `zen faker` - a mock API from an openapi/swagger document     |
+| [`@zenera/rag`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md)     | `zen rag` - indexing and search for documents and API schemas |
+| [`@zenera/view`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/view/README.md)   | `zen view` - a live local viewer for a folder                 |
+
 ## License
 
 Early days and moving fast - issues, questions and pull requests are welcome.

package/dist/catalog.js

@@ -463,10 +463,6 @@ 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;
     }
@@ -483,6 +479,29 @@ function readCache(provider) {
         ? file
         : undefined;
 }
+/**
+ * Through a gateway nothing is cached on disk: the gateway caches its own
+ * listing, one request serves every provider, and a stale copy outlives the
+ * gateway's providers or the virtual key that was allowed to see them.
+ */
+async function loadGatewayCatalog(provider, at) {
+    const via = { via: { name: GATEWAY_NAME, url: at.baseURL } };
+    try {
+        const entries = await fetchGatewayCatalog(provider, at);
+        return { provider, entries, origin: 'live', fetchedAt: new Date().toISOString(), ...via };
+    }
+    catch (err) {
+        // No built-in list: it names vendor models the gateway may not serve at all.
+        return {
+            provider,
+            entries: [],
+            origin: 'curated',
+            fetchedAt: new Date(0).toISOString(),
+            problem: classify(err),
+            ...via,
+        };
+    }
+}
 /**
  * The listing for one provider, from the cheapest source that can answer.
  *
@@ -494,9 +513,9 @@ function readCache(provider) {
  */
 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));
+    if (at) {
+        return loadGatewayCatalog(provider, at);
+    }
     const cached = readCache(provider);
     const fresh = cached && Date.now() - new Date(cached.fetchedAt).getTime() < CATALOG_TTL_MS
         ? cached
@@ -507,17 +526,14 @@ export async function loadCatalog(provider, opts = {}) {
             entries: fresh.entries,
             origin: 'cache',
             fetchedAt: fresh.fetchedAt,
-            ...via,
         };
     }
     if (!opts.offline) {
         try {
-            const entries = at
-                ? await fetchGatewayCatalog(provider, at)
-                : await fetchCatalog(provider);
+            const entries = await fetchCatalog(provider);
             const fetchedAt = new Date().toISOString();
             store().put(catalogKey(provider), { provider, fetchedAt, entries });
-            return { provider, entries, origin: 'live', fetchedAt, ...via };
+            return { provider, entries, origin: 'live', fetchedAt };
         }
         catch (err) {
             const problem = classify(err);
@@ -528,16 +544,14 @@ export async function loadCatalog(provider, opts = {}) {
                     origin: 'stale',
                     fetchedAt: cached.fetchedAt,
                     problem,
-                    ...via,
                 };
             }
             return {
                 provider,
-                entries: fallback(),
+                entries: curated(provider),
                 origin: 'curated',
                 fetchedAt: new Date(0).toISOString(),
                 problem,
-                ...via,
             };
         }
     }
@@ -547,15 +561,13 @@ export async function loadCatalog(provider, opts = {}) {
             entries: cached.entries,
             origin: 'stale',
             fetchedAt: cached.fetchedAt,
-            ...via,
         };
     }
     return {
         provider,
-        entries: fallback(),
+        entries: curated(provider),
         origin: 'curated',
         fetchedAt: new Date(0).toISOString(),
-        ...via,
     };
 }
 // ---------------------------------------------------------------------------

package/dist/commands/meta.js

@@ -1,4 +1,4 @@
-import { readProjectConfig } from '@zenera/neo';
+import { gatewayOf, readProjectConfig } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -11,7 +11,7 @@ import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
 import { assertOwner, isProvider, KeyStore, PROVIDERS } from "../keys.js";
 import { probeChat, probeModel } from "../liveness.js";
-import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
+import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, wireGateway, writeMeta, } from "../meta/index.js";
 import { splitRef } from "../modelref.js";
 import { duration } from "../narrate.js";
 import * as Projects from "../projects.js";
@@ -554,6 +554,8 @@ async function go(ctx, values, project, prompt, promptName) {
     ensureHome();
     const store = await KeyStore.open();
     store.materialize();
+    // After materialize: a keyring in bifrost mode is what sets the url.
+    const gateway = gatewayOf();
     const only = values.provider ? asProvider(values.provider) : undefined;
     const chosen = chooseModel({
         flag: values.model,
@@ -561,7 +563,7 @@ async function go(ctx, values, project, prompt, promptName) {
         env: process.env[MODEL_ENV],
         stored: (await readMeta()).model,
         project: projectModel(project.dir),
-        fallback: defaultRef(store, only),
+        fallback: defaultRef(store, only, gateway !== undefined),
     });
     if (!chosen) {
         if (only) {
@@ -577,11 +579,11 @@ async function go(ctx, values, project, prompt, promptName) {
     if (meant && !only) {
         warn(`${chosen.ref} names no provider — did you mean ${meant}/${id}?`);
     }
-    const entry = store.active(owner);
-    if (!entry) {
+    const entry = gateway ? undefined : store.active(owner);
+    if (!gateway && !entry) {
         throw credentialError(`no ${owner} key`, `add one: zen key add ${owner}`);
     }
-    const wiring = wire(store, entry, id);
+    const wiring = gateway ? wireGateway(gateway, owner, id) : wire(store, entry, id);
     const binary = locate();
     // Copilot cannot carry a session to another model: the resume fails on the first call.
     const ran = values.resume ? sessionModel(values.resume) : undefined;
@@ -999,10 +1001,10 @@ async function vet(ctx, ref) {
     const { provider, id } = splitRef(ref);
     const owner = provider ?? 'openai';
     const store = await KeyStore.open();
-    if (!store.active(owner)) {
+    store.materialize();
+    if (!gatewayOf() && !store.active(owner)) {
         throw credentialError(`no ${owner} key to try ${id} with`, `add one: zen key add ${owner}`);
     }
-    store.materialize();
     const bar = ctx.json ? undefined : progress();
     bar?.update(dim(`asking ${owner} about ${id} …`));
     const probe = await probeModel({
@@ -1058,13 +1060,12 @@ async function pickModel(ctx) {
         throw usageError('--pick needs a terminal', 'name the model instead');
     }
     const store = await KeyStore.open();
-    const known = store.entries
-        .filter((e) => e.provider !== 'exa')
-        .map((e) => e.provider);
-    if (known.length === 0) {
+    store.materialize();
+    const known = store.entries.map((e) => e.provider).filter(isProvider);
+    if (known.length === 0 && !gatewayOf()) {
         throw credentialError('no keys to choose from', 'add one: zen key add openai');
     }
-    const held = [...new Set(known)];
+    const held = gatewayOf() ? [] : [...new Set(known)];
     const { browseModels } = await import("./models.js");
     const chosen = await browseModels({
         initial: held.length === 1 ? held[0] : undefined,

package/dist/keys.d.ts

@@ -202,7 +202,12 @@ export declare class KeyStore {
      * since its url alone is what switches the library over.
      */
     environment(only?: KeyOwner[]): Record<string, string>;
-    /** Applies `environment()` to this process. Returns what it set. */
+    /**
+     * Copies the keyring's active credentials into `process.env`, the only
+     * place the library looks. Must run before anything that reads them —
+     * in `bifrost` mode this is what sets `BIFROST_BASE_URL`, so `gatewayOf()`
+     * returns undefined until it has. Returns what it set.
+     */
     materialize(only?: KeyOwner[]): Record<string, string>;
 }
 /**

package/dist/keys.js

@@ -482,7 +482,12 @@ export class KeyStore {
         }
         return env;
     }
-    /** Applies `environment()` to this process. Returns what it set. */
+    /**
+     * Copies the keyring's active credentials into `process.env`, the only
+     * place the library looks. Must run before anything that reads them —
+     * in `bifrost` mode this is what sets `BIFROST_BASE_URL`, so `gatewayOf()`
+     * returns undefined until it has. Returns what it set.
+     */
     materialize(only) {
         const env = this.environment(only);
         Object.assign(process.env, env);

package/dist/meta/model.d.ts

@@ -21,12 +21,21 @@ export interface ModelSources {
 }
 /** Where the answer is looked for, best first. */
 export declare const ORDER: readonly ModelSource[];
+/**
+ * Decides which model `zen meta` runs copilot on, when it can be named in six
+ * places at once. The source comes back too, so a surprising pick can be traced
+ * ("from agents.yaml model:") instead of guessed at.
+ */
 export declare function chooseModel(sources: ModelSources): ModelChoice | undefined;
 export declare const SOURCE_LABELS: Record<ModelSource, string>;
 /** First of each row is the default; the rest are the next best. */
 export declare const RECOMMENDED: Partial<Record<Provider, readonly string[]>>;
-/** The recommended ref for the first provider with a key, or for `only`. */
-export declare function defaultRef(store: KeyStore, only?: Provider): string | undefined;
+/**
+ * The model `zen meta` falls back to when nothing names one, so a machine with
+ * just a key (or just a gateway, which reaches every provider) still runs.
+ * `only` is `--provider`: the recommendation for that provider, if it is held.
+ */
+export declare function defaultRef(store: KeyStore, only?: Provider, gateway?: boolean): string | undefined;
 export interface MetaFile {
     version: 1;
     model?: string;

package/dist/meta/model.js

@@ -13,6 +13,11 @@ export const ORDER = [
     'project',
     'default',
 ];
+/**
+ * Decides which model `zen meta` runs copilot on, when it can be named in six
+ * places at once. The source comes back too, so a surprising pick can be traced
+ * ("from agents.yaml model:") instead of guessed at.
+ */
 export function chooseModel(sources) {
     const at = {
         flag: sources.flag,
@@ -57,11 +62,15 @@ export const RECOMMENDED = {
 };
 /** Which provider is tried first when several are held. */
 const PREFERENCE = ['anthropic', 'openai', 'vertex', 'google', 'openrouter'];
-/** The recommended ref for the first provider with a key, or for `only`. */
-export function defaultRef(store, only) {
+/**
+ * The model `zen meta` falls back to when nothing names one, so a machine with
+ * just a key (or just a gateway, which reaches every provider) still runs.
+ * `only` is `--provider`: the recommendation for that provider, if it is held.
+ */
+export function defaultRef(store, only, gateway = false) {
     for (const provider of only ? [only] : PREFERENCE) {
         const id = RECOMMENDED[provider]?.[0];
-        if (id && store.active(provider)) {
+        if (id && (gateway || store.active(provider))) {
             return `${provider}/${id}`;
         }
     }

package/dist/meta/wire.d.ts

@@ -1,3 +1,4 @@
+import { type Gateway } from '@zenera/neo';
 import { type KeyEntry, type KeyStore, type Provider } from './host.ts';
 /**
  * Copilot offers its tools as OpenAI *custom* tools, which the completions API
@@ -35,6 +36,12 @@ export declare const RELAY_URL = "http://127.0.0.1:<relay>";
  * through a GitHub account we are deliberately not using.
  */
 export declare function wire(store: KeyStore, entry: KeyEntry, id: string): Wiring;
+/**
+ * Through a gateway: one virtual key, and Bifrost's OpenAI or Anthropic drop-in,
+ * which routes on an `<upstream>/<id>` wire model. Claude speaks Anthropic
+ * wherever it is hosted; everything else goes through the OpenAI one.
+ */
+export declare function wireGateway(at: Gateway, provider: Provider, id: string): Wiring;
 /** Values a `--dry-run` may print. A key is four characters and an apology. */
 export declare function masked(env: Record<string, string>, secret: readonly string[]): string[];
 /** Non-fatal, said once, because a competing file is a silent override. */

package/dist/meta/wire.js

@@ -1,3 +1,4 @@
+import { GATEWAY_UPSTREAMS } from '@zenera/neo';
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { credentialError, envOf, invokedAs, yellow, } from "./host.js";
@@ -112,6 +113,31 @@ export function wire(store, entry, id) {
     }
     return { provider, model: env.COPILOT_PROVIDER_WIRE_MODEL ?? id, env, secret, warnings };
 }
+/**
+ * Through a gateway: one virtual key, and Bifrost's OpenAI or Anthropic drop-in,
+ * which routes on an `<upstream>/<id>` wire model. Claude speaks Anthropic
+ * wherever it is hosted; everything else goes through the OpenAI one.
+ */
+export function wireGateway(at, provider, id) {
+    const claude = provider === 'anthropic' || (provider === 'vertex' && vertexClaude(id));
+    const model = provider === 'vertex' ? id.replace(/^anthropic\//, '') : id;
+    const env = {
+        COPILOT_PROVIDER_TYPE: claude ? 'anthropic' : 'openai',
+        COPILOT_PROVIDER_BASE_URL: `${at.baseURL}${claude ? '/anthropic' : '/openai/v1'}`,
+        COPILOT_PROVIDER_MODEL_ID: model.replace(/^google\//, ''),
+        COPILOT_PROVIDER_WIRE_MODEL: `${GATEWAY_UPSTREAMS[provider]}/${model}`,
+    };
+    const api = wireApi(provider, model);
+    if (api) {
+        env.COPILOT_PROVIDER_WIRE_API = api;
+    }
+    const secret = [];
+    if (at.apiKey) {
+        env.COPILOT_PROVIDER_API_KEY = at.apiKey;
+        secret.push('COPILOT_PROVIDER_API_KEY');
+    }
+    return { provider, model: env.COPILOT_PROVIDER_WIRE_MODEL, env, secret, warnings: [] };
+}
 /** Values a `--dry-run` may print. A key is four characters and an apology. */
 export function masked(env, secret) {
     return Object.entries(env)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.30",
+    "version": "1.1.32",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -54,8 +54,8 @@
         "@google/genai": "^2.30.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.4.25",
-        "@zenera/neo": "^1.1.30",
-        "@zenera/view": "^1.1.30",
+        "@zenera/neo": "^1.1.32",
+        "@zenera/view": "^1.1.32",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",